> ## 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 ドキュメントに戻る](/ja/get-started/devin-intro)
</Info>

連邦 Enterprise 管理者は、サービスキー API を使用して、ACU消費量をプログラムからクエリし、[グループ](/ja/federal/groups)、[モデルの利用可否](/ja/federal/model-provisioning)、[ACU 制限](/ja/federal/acu-limits)を管理できます。[Python SDK](/ja/federal/api/python-sdk) は、このセクションで説明するすべてのエンドポイントをラップしています。

グループ管理および ACU 上限のエンドポイントは、セルフホスト型のマルチテナント連邦政府向け導入環境でのみ利用できます。商用デプロイメントでは提供されていません。分析エンドポイント (`/Analytics`、`/UserPageAnalytics`、`/CascadeAnalytics`) では、デプロイメントの分析アクセスティアも確認されます。分析へのアクセス権がないチームには、`permission_denied` が返されます。

***

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

すべてのリクエストは、デプロイメントの API サーバーに対する JSON `POST` リクエストです。

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

`<your-server>` を、連邦政府向け導入環境の API ドメインに置き換えます。

<div id="authentication">
  ## 認証
</div>

すべてのリクエストは、リクエストボディに含まれる**サービスキー**を使用して認証します。

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

サービスキーを作成するには、チーム管理者として連邦ポータルにログインし、**Settings → Service Keys** に移動します。次に、呼び出す予定のエンドポイントに必要な権限を持つキーを作成します。

<Warning>サービスキーは安全に保管してください。クライアントサイドのコードに公開したり、リポジトリにコミットしたりしないでください。</Warning>

<div id="required-permissions">
  ### 必要な権限
</div>

| エンドポイント                                                                                                      | 必要な権限           |
| ------------------------------------------------------------------------------------------------------------ | --------------- |
| [レガシー使用量レポート](/ja/federal/api/python-sdk#per-user-usage-report) (`/UserPageAnalytics` と `/CascadeAnalytics`) | Teams Read-Only |
| [ACU消費量](/ja/federal/api/acu-consumption) (`/Analytics`)                                                     | Analytics Read  |
| [グループ一覧の取得](/ja/federal/api/group-management#list-groups) (`/ListGroups`)                                    | Teams Read-Only |
| [グループの取得](/ja/federal/api/group-management#get-group) (`/GetGroup`)                                          | Teams Read-Only |
| [グループの作成](/ja/federal/api/group-management#create-group) (`/CreateGroup`)                                    | Teams Update    |
| [グループの更新](/ja/federal/api/group-management#update-group) (`/UpdateGroup`)                                    | Teams Update    |
| [グループの削除](/ja/federal/api/group-management#delete-group) (`/DeleteGroup`)                                    | Teams Update    |
| [グループメンバー一覧の取得](/ja/federal/api/group-management#list-group-members) (`/ListGroupMembers`)                   | Teams Read-Only |
| [グループメンバーの追加](/ja/federal/api/group-management#add-group-members) (`/AddGroupMembers`)                       | Teams Update    |
| [グループメンバーの削除](/ja/federal/api/group-management#remove-group-members) (`/RemoveGroupMembers`)                 | Teams Update    |
| [ユーザーのACU上限の取得](/ja/federal/api/acu-caps#get-a-users-acu-cap) (`/GetUserAcuCap`)                             | Teams Read-Only |
| [ユーザーのACU上限の更新](/ja/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`            | サービスはリクエストを完了できませんでした。                                                                         |