> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devin.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# グループ管理
> サービスキー API を通じてグループ、メンバーシップ、モデルの利用可否、グループの ACU 上限を作成・管理します。
このドキュメントは、Devin の連邦政府向け導入環境向けです。[Devin ドキュメントに戻る](/ja/get-started/devin-intro)
[グループ](/ja/federal/groups)をプログラムで管理できます。グループの作成、取得、更新、削除、メンバーシップの管理、[モデルの利用可否](/ja/federal/model-provisioning)と[ACU 上限](/ja/federal/acu-limits)の設定を行えます。これらのエンドポイントは、マルチテナントの連邦政府向け導入環境でのみ利用できます。
すべてのエンドポイントは JSON の `POST` リクエストです。すべてのリクエストボディには `service_key` が含まれます。認証、スコーピング、ページネーション、エラーについては、[API の概要](/ja/federal/api/overview)を参照してください。読み取りエンドポイントには **Teams Read-Only**、書き込みエンドポイントには **Teams Update** が必要です。これらのハンドラーにはセルフホスト型マルチテナントデプロイメントの制限がありますが、`/Analytics` で使用される個別の analytics-access ティアチェックは適用されません。
読み取りおよび書き込みエンドポイントから返されるグループオブジェクト:
| フィールド | 説明 |
| ---------------------------- | ----------------------------------------------------------- |
| `group_id` | グループの ID。 |
| `name` | グループ名。 |
| `member_count` | 現在のメンバー数。 |
| `cascade_model_uids` | Cascade で許可されるモデル UID。空のリストは、グループによる Cascade の制限がないことを示します。 |
| `command_model_uids` | Command で許可されるモデル UID。空のリストは、グループによる Command の制限がないことを示します。 |
| `configured_cycle_acu_limit` | グループに設定されたメンバーごとの ACU 上限。設定されていない場合は省略されます。存在する場合は常に正の値です。 |
| `effective_cycle_acu_limit` | チームの上限を考慮したうえで、グループに実際に適用される上限。上限が適用されない場合は省略されます。 |
***
## グループの一覧
```
POST /api/v1/ListGroups
```
サービスキーから参照可能なグループを一覧表示します。Team スコープのキーではチーム内のすべてのグループが、グループスコープのキーでは割り当てられたグループのみが一覧表示されます。**Teams Read-Only** が必要です。`page_size` / `page_token` をサポートします。
```bash theme={null}
curl -X POST https:///api/v1/ListGroups \
-H "Content-Type: application/json" \
-d '{"service_key": "your_service_key"}'
```
```json theme={null}
{
"groups": [
{"groupId": "group_a", "name": "Engineering", "memberCount": 24},
{"groupId": "group_b", "name": "Data Science", "memberCount": 9}
],
"nextPageToken": ""
}
```
## グループを取得
```
POST /api/v1/GetGroup
```
1 つのグループのモデル許可リスト、設定済みの ACU 上限、および有効な ACU 上限を取得します。**Teams Read-Only** 権限が必要です。存在しないグループ、チームをまたぐグループ、スコープ外のグループは `not_found` を返します。
```bash theme={null}
curl -X POST https:///api/v1/GetGroup \
-H "Content-Type: application/json" \
-d '{"service_key": "your_service_key", "group_id": "group_a"}'
```
```json theme={null}
{
"group": {
"groupId": "group_a",
"name": "Engineering",
"memberCount": 24,
"cascadeModelUids": ["model-uid-1", "model-uid-2"],
"commandModelUids": [],
"configuredCycleAcuLimit": 50,
"effectiveCycleAcuLimit": 50
}
}
```
## グループを作成
```
POST /api/v1/CreateGroup
```
有効なチーム内に、指定した `name` のグループを作成します。**Teams Update** 権限が必要です。グループスコープのキーでは、グループを作成できません。
```bash theme={null}
curl -X POST https:///api/v1/CreateGroup \
-H "Content-Type: application/json" \
-d '{"service_key": "your_service_key", "name": "Engineering"}'
```
レスポンスには、作成された `group` オブジェクトが含まれます。
## グループを更新
```
POST /api/v1/UpdateGroup
```
グループをアトミックに更新します。リクエストに含まれるフィールドのみ変更され、省略されたフィールドは変更されません。パッチ対象のフィールドがないリクエストは `invalid_argument` を返します。**Teams Update** が必要です。
更新するグループ。
新しいグループ名。
`{"model_uids": [...]}` — グループの Cascade モデル許可リストを置き換えます。空のリストを渡すと、グループの Cascade 制限が解除されます。グループの許可リストの組み合わせ方法については、[モデルのプロビジョニング](/ja/federal/model-provisioning)を参照してください。
`{"model_uids": [...]}` — グループの Command モデル許可リストを置き換えます。空のリストを渡すと、グループの Command 制限が解除されます。
請求サイクルごとのメンバーあたりのグループ ACU 上限を設定します。正の値である必要があります。`clear_cycle_acu_limit` とは同時に指定できません。
グループの ACU 上限をクリアし、チームまたはデフォルトの動作に戻します。このサービスキー API では、`set_cycle_acu_limit` には有限の正の値を指定する必要があります。グループごとのオーバーライドを削除するには、この明示的なクリア操作を使用してください。ポータルのグループ ACU 上限コントロールでは、`cycle_acu_limit: 0` をクリアリクエストとして受け付けます。
```bash theme={null}
curl -X POST https:///api/v1/UpdateGroup \
-H "Content-Type: application/json" \
-d '{
"service_key": "your_service_key",
"group_id": "group_a",
"cascade_models": {"model_uids": ["model-uid-1", "model-uid-2"]},
"set_cycle_acu_limit": 50
}'
```
レスポンスには、更新された `group` オブジェクトが含まれます。
## グループを削除
```
POST /api/v1/DeleteGroup
```
`group_id`で指定したグループを削除します。キーの有効なスコープにすでに存在しないグループを削除しても、正常にno-opとして処理されます。**Teams Update**が必要です。
```bash theme={null}
curl -X POST https:///api/v1/DeleteGroup \
-H "Content-Type: application/json" \
-d '{"service_key": "your_service_key", "group_id": "group_a"}'
```
## グループのメンバーを一覧表示
```
POST /api/v1/ListGroupMembers
```
グループの現在のメンバーを一覧表示します。**Teams Read-Only** が必要です。`page_size` / `page_token` をサポートしています。
```bash theme={null}
curl -X POST https:///api/v1/ListGroupMembers \
-H "Content-Type: application/json" \
-d '{"service_key": "your_service_key", "group_id": "group_a"}'
```
```json theme={null}
{
"members": [
{"userId": "user_abc", "email": "dev@agency.gov"}
],
"nextPageToken": ""
}
```
## グループにメンバーを追加
```
POST /api/v1/AddGroupMembers
```
メールアドレスで現在のチームのユーザーをグループに追加します (`user_emails`、1～1,000件) 。**Teams Update** が必要です。
* 冪等性: 既存のメンバーを追加しても、成功として扱われ、no-op です。
* メールアドレスは前後の空白が削除され、大文字・小文字を区別せずに重複が除去されます。
* オールオアナッシング: いずれかのメールアドレスが不明、または別のチームに属している場合、リクエスト全体が拒否され、何も書き込まれません。
```bash theme={null}
curl -X POST https:///api/v1/AddGroupMembers \
-H "Content-Type: application/json" \
-d '{
"service_key": "your_service_key",
"group_id": "group_a",
"user_emails": ["dev@agency.gov", "lead@agency.gov"]
}'
```
## グループからメンバーを削除
```
POST /api/v1/RemoveGroupMembers
```
メールアドレス (`user_emails`、1～1,000件) を指定してグループからユーザーを削除します。**Teams Update** が必要です。検証は「グループメンバーを追加」と同様にオールオアナッシングとなり、メンバーではない有効なユーザーを削除しても、成功として扱われ、no-op です。
```bash theme={null}
curl -X POST https:///api/v1/RemoveGroupMembers \
-H "Content-Type: application/json" \
-d '{
"service_key": "your_service_key",
"group_id": "group_a",
"user_emails": ["dev@agency.gov"]
}'
```