> ## 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 分析、组管理和 ACU 限额的服务密钥 API。

<Info>
  本文档适用于 Devin 的联邦部署。[返回 Devin 文档](/zh/get-started/devin-intro)
</Info>

联邦 Enterprise Admin 可通过服务密钥 API 以编程方式查询 ACU 用量，并管理[组](/zh/federal/groups)、[模型可用性](/zh/federal/model-provisioning)和 [ACU 限额](/zh/federal/acu-limits)。[Python SDK](/zh/federal/api/python-sdk) 封装了本节所述的所有端点。

组管理和 ACU 上限端点仅适用于自托管的多租户联邦部署，不会在商业部署中提供。分析端点 (`/Analytics`、`/UserPageAnalytics` 和 `/CascadeAnalytics`) 还会检查部署的分析访问层级；没有分析访问权限的团队将收到 `permission_denied`。

***

<div id="base-url">
  ## 基础 URL
</div>

所有请求均以 JSON `POST` 请求的形式发送至你的部署的 API 服务器：

```
https://<your-server>/api/v1/<Method>
```

将 `<your-server>` 替换为你的联邦部署的 API 域名。

<div id="authentication">
  ## 身份验证
</div>

每个请求都需在请求正文中包含**服务密钥**进行身份验证：

```json theme={null}
{
  "service_key": "your_service_key_here"
}
```

要创建服务密钥，请以团队管理员身份登录联邦门户，前往 **设置 → 服务密钥**，然后创建一个具备所要调用端点所需权限的密钥。

<Warning>请妥善保管服务密钥。切勿将其暴露在客户端代码中，也不要将其提交到代码仓库。</Warning>

<div id="required-permissions">
  ### 所需权限
</div>

| 端点                                                                                                      | 所需权限            |
| ------------------------------------------------------------------------------------------------------- | --------------- |
| [旧版用量报告](/zh/federal/api/python-sdk#per-user-usage-report) (`/UserPageAnalytics` 和 `/CascadeAnalytics`) | Teams Read-Only |
| [ACU 用量](/zh/federal/api/acu-consumption) (`/Analytics`)                                                | Analytics Read  |
| [列出组](/zh/federal/api/group-management#list-groups) (`/ListGroups`)                                     | Teams Read-Only |
| [获取组](/zh/federal/api/group-management#get-group) (`/GetGroup`)                                         | Teams Read-Only |
| [创建组](/zh/federal/api/group-management#create-group) (`/CreateGroup`)                                   | Teams Update    |
| [更新组](/zh/federal/api/group-management#update-group) (`/UpdateGroup`)                                   | Teams Update    |
| [删除组](/zh/federal/api/group-management#delete-group) (`/DeleteGroup`)                                   | Teams Update    |
| [列出组成员](/zh/federal/api/group-management#list-group-members) (`/ListGroupMembers`)                      | Teams Read-Only |
| [添加组成员](/zh/federal/api/group-management#add-group-members) (`/AddGroupMembers`)                        | Teams Update    |
| [移除组成员](/zh/federal/api/group-management#remove-group-members) (`/RemoveGroupMembers`)                  | Teams Update    |
| [获取用户 ACU 上限](/zh/federal/api/acu-caps#get-a-users-acu-cap) (`/GetUserAcuCap`)                          | Teams Read-Only |
| [更新用户 ACU 上限](/zh/federal/api/acu-caps#set-or-clear-a-users-acu-cap) (`/UpdateUserAcuCap`)              | Teams Update    |

<div id="team-scoped-and-group-scoped-keys">
  ### 团队级和组级密钥
</div>

服务密钥在创建时会确定其作用域：

* **团队级密钥**可以查询团队级数据，并管理团队中的所有组。
* **组级密钥**仅限用于其所属的组。它们可以读取该组的 ACU 汇总值和用户记录，仅列出和读取该组，并且只能读取或更新该组当前成员的 ACU 上限。它们无法读取团队级汇总值或用户记录、查看其他组，也无法创建组。

<div id="pagination">
  ## 分页
</div>

列出组、组成员及用户级 ACU 行的操作均支持分页：

* `page_size` — 可选；默认值为 100，最大值为 1,000。省略该参数或传入 `0` 均会使用默认值。
* `next_page_token` — 存在更多结果时返回。在其他请求参数完全相同 (包括相同的 `page_size`) 的情况下，将其作为 `page_token` 传回以获取下一页。

页令牌经过加密，且内容不可见。它们会在 24 小时后过期。ACU 消耗令牌与端点、团队、作用域、周期、所选组和页面大小绑定。组列表和成员列表令牌与端点、团队、作用域和页面大小绑定。在不同页面间更改任何绑定值都会返回 `invalid_argument` 错误。

<div id="errors">
  ## 错误
</div>

错误以包含代码和消息的 JSON 格式返回：

```json theme={null}
{
  "code": "permission_denied",
  "message": "service key role is missing the required permission"
}
```

| 代码                    | 含义                                                           |
| --------------------- | ------------------------------------------------------------ |
| `unauthenticated`     | 服务密钥缺失、无效或已过期。                                               |
| `permission_denied`   | 服务密钥所关联的角色不具备必填权限。                                           |
| `invalid_argument`    | 请求格式不正确，例如时间段无效、混用类型化查询和自定义分析查询、更新内容为空，或页面令牌已过期或不匹配。         |
| `not_found`           | 资源不存在、属于其他团队，或不在服务密钥的作用域内。无法区分跨团队或超出作用域的资源与不存在的资源。           |
| `failed_precondition` | 请求有效，但无法在当前状态下完成，例如为未使用 ACU 计费的团队设置 ACU 上限，或选择存在歧义的用户电子邮件地址。 |
| `already_exists`      | 所请求的组名称已被该团队使用。                                              |
| `internal`            | 服务无法完成该请求。                                                   |