组管理 - Devin Docs

本文档适用于 Devin 联邦部署。返回 Devin 文档

以编程方式管理组：创建、读取、更新和删除组，管理其成员资格，并配置其模型可用性和 ACU 上限。这些端点仅适用于多租户联邦部署。所有端点均接受 JSON POST 请求。每个请求正文均包含 service_key；有关身份验证、作用域、分页和错误的信息，请参阅 API 概览。读取端点需要 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

列出服务密钥可查看的组。团队作用域的密钥会列出团队中的所有组；组作用域的密钥仅列出分配给它们的组。需要 Teams Read-Only 权限。支持 page_size / page_token。

curl -X POST https://<your-server>/api/v1/ListGroups \
  -H "Content-Type: application/json" \
  -d '{"service_key": "your_service_key"}'

{
  "groups": [
    {"groupId": "group_a", "name": "Engineering", "memberCount": 24},
    {"groupId": "group_b", "name": "Data Science", "memberCount": 9}
  ],
  "nextPageToken": ""
}

获取组

POST /api/v1/GetGroup

读取一个组，包括其模型允许列表、配置的和实际生效的 ACU 上限。需要 Teams Read-Only 权限。不存在、跨团队或超出作用域的组会返回 not_found。

curl -X POST https://<your-server>/api/v1/GetGroup \
  -H "Content-Type: application/json" \
  -d '{"service_key": "your_service_key", "group_id": "group_a"}'

{
  "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 权限。具有组作用域的密钥无法创建组。

curl -X POST https://<your-server>/api/v1/CreateGroup \
  -H "Content-Type: application/json" \
  -d '{"service_key": "your_service_key", "name": "Engineering"}'

响应中包含已创建的 组 对象。

更新组

POST /api/v1/UpdateGroup

以原子方式更新组。仅会更改请求中提供的字段；未提供的字段保持不变。不包含任何更新字段的请求将返回 invalid_argument。需要 Teams Update 权限。

string

必填

要更新的组。

string

新的组名称。

object

{"model_uids": [...]} — 替换该组的 Cascade 模型允许列表。传入空列表将清除该组的 Cascade 限制。有关组允许列表如何组合，请参阅模型预配。

object

{"model_uids": [...]} — 替换该组的 Command 模型允许列表。传入空列表将清除该组的 Command 限制。

number

设置该组中每位成员每个账单周期的 ACU 上限。必须为正数。不能与 clear_cycle_acu_limit 同时使用。

boolean

清除该组的 ACU 上限，恢复为团队或默认行为。在此服务密钥 API 中，set_cycle_acu_limit 必须为有限的正数；请使用此显式清除操作移除组级覆盖设置。门户中的组 ACU 限制控件接受 cycle_acu_limit: 0 作为清除请求。

curl -X POST https://<your-server>/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
  }'

响应中包含更新后的 组 对象。

删除组

POST /api/v1/DeleteGroup

通过 group_id 删除组。删除已不在密钥可用作用域内的组将成功完成，但不会执行任何操作。需要 Teams Update。

curl -X POST https://<your-server>/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。

curl -X POST https://<your-server>/api/v1/ListGroupMembers \
  -H "Content-Type: application/json" \
  -d '{"service_key": "your_service_key", "group_id": "group_a"}'

{
  "members": [
    {"userId": "user_abc", "email": "dev@agency.gov"}
  ],
  "nextPageToken": ""
}

添加组成员

POST /api/v1/AddGroupMembers

通过电子邮件将当前团队的用户添加到组 (user_emails，1–1,000 个条目) 。需要 Teams Update。

幂等：添加已存在的成员会成功，但不执行任何操作。
电子邮件地址会去除首尾空格，并按不区分大小写的方式去重。
全有或全无：如果任一电子邮件地址不存在或属于其他团队，整个请求都会被拒绝，且不会写入任何内容。

curl -X POST https://<your-server>/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 权限。与添加组成员一样，验证遵循全有或全无原则；移除有效但不属于该组的用户会成功执行，但不会产生任何实际操作。

curl -X POST https://<your-server>/api/v1/RemoveGroupMembers \
  -H "Content-Type: application/json" \
  -d '{
    "service_key": "your_service_key",
    "group_id": "group_a",
    "user_emails": ["dev@agency.gov"]
  }'

​列出组

​获取组

​创建组

​更新组

​删除组

​列出组成员

​添加组成员

​移除组成员

列出组

获取组

创建组

更新组

删除组

列出组成员

添加组成员

移除组成员