> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devinenterprise.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDK

> Python SDK を使用して、コマンドラインから分析データをクエリし、グループと ACU 上限を管理します。

<Info>
  このドキュメントは、Devin の連邦政府向け導入環境向けです。[Devin Docs に戻る](/ja/get-started/devin-intro)
</Info>

Python SDK (`windsurf_analytics.py`) は、[連邦政府向け API](/ja/federal/api/overview) のエンドポイント (使用量レポート、[ACU消費量](/ja/federal/api/acu-consumption)、[グループ管理](/ja/federal/api/group-management)、[ユーザーの ACU 上限](/ja/federal/api/acu-caps)) に対応するコマンドラインクライアントです。導入環境用のスクリプトを入手するには、Cognition の担当者にお問い合わせください。

<div id="requirements">
  ## 要件
</div>

* Python 3
* `requests` ライブラリ: `pip install requests`

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

すべてのコマンドで、次の共通フラグを使用できます。

| フラグ             | 説明                                                                |
| --------------- | ----------------------------------------------------------------- |
| `--service-key` | 認証用のサービスキー。`WINDSURF_SERVICE_KEY` 環境変数で設定することもできます。               |
| `--api-url`     | デプロイメントの API サーバーのベース URL (`https://<your-server>`) 。HTTPS が必要です。 |

サービスキーのロールには、各コマンドで必要な権限が付与されている必要があります。詳しくは[権限表](/ja/federal/api/overview#required-permissions)を参照してください。すべての Analytics コマンドには、Analytics API にアクセスできるチームティアも必要です。

<div id="commands">
  ## コマンド
</div>

| コマンド                   | エンドポイント                                    | 必要な権限           |
| ---------------------- | ------------------------------------------ | --------------- |
| `usage` (デフォルト)        | `/UserPageAnalytics` + `/CascadeAnalytics` | Teams Read-Only |
| `acu-consumption`      | `/Analytics`                               | Analytics Read  |
| `list-groups`          | `/ListGroups`                              | Teams Read-Only |
| `get-group`            | `/GetGroup`                                | Teams Read-Only |
| `create-group`         | `/CreateGroup`                             | Teams Update    |
| `update-group`         | `/UpdateGroup`                             | Teams Update    |
| `delete-group`         | `/DeleteGroup`                             | Teams Update    |
| `list-group-members`   | `/ListGroupMembers`                        | Teams Read-Only |
| `add-group-members`    | `/AddGroupMembers`                         | Teams Update    |
| `remove-group-members` | `/RemoveGroupMembers`                      | Teams Update    |
| `get-user-acu-cap`     | `/GetUserAcuCap`                           | Teams Read-Only |
| `update-user-acu-cap`  | `/UpdateUserAcuCap`                        | Teams Update    |

コマンドを指定せずにスクリプトを実行すると (元の呼び出し方法) 、`usage` レポートが実行されます。

<div id="output-and-errors">
  ## 出力とエラー
</div>

すべてのコマンドはJSONを標準出力に出力します。ページネーションされた結果 (ACU消費量のユーザー行、`list-groups`、`list-group-members`) は最終ページまで自動的に取得され、単一のレスポンスに統合されます。APIエラーは標準エラー出力に`code: message`の形式で出力され、スクリプトは終了ステータス`1`で終了します。

<div id="examples">
  ## 使用例
</div>

<div id="per-user-usage-report">
  ### ユーザー別の使用量レポート
</div>

```bash theme={null}
python windsurf_analytics.py \
    --service-key YOUR_SERVICE_KEY \
    --api-url https://your-server.com \
    --start 2025-01-01T00:00:00Z \
    --end 2025-03-31T23:59:59Z
```

<div id="acu-consumption">
  ### ACU消費量
</div>

```bash theme={null}
# 現在の請求サイクルのチームACU合計とユーザーごとの行
python windsurf_analytics.py acu-consumption \
    --api-url https://your-server.com \
    --current-cycle --include-team-total --team-user-rows

# グループ別の過去の内訳（期間は最大90日）、
# 特定の1グループについてはユーザーごとの行も出力
python windsurf_analytics.py acu-consumption \
    --api-url https://your-server.com \
    --start 2025-01-01T00:00:00Z --end 2025-03-31T23:59:59Z \
    --group-id GROUP_A_ID --group-user-rows GROUP_A_ID
```

`acu-consumption` フラグ: `--current-cycle` または `--start`/`--end` で対象期間を指定します。`--include-team-total`、繰り返し指定可能な `--group-id` (最大 100 個) 、および相互排他的な `--team-user-rows` / `--group-user-rows GROUP_ID` で取得するデータを指定します。`--page-size` でリクエストあたりのページサイズを調整します (ページはすべて取得されます) 。データ選択フラグを少なくとも 1 つ指定する必要があります。グループスコープのキーでは、割り当てられたグループのみを選択でき、チーム合計やチームユーザー行をリクエストすることはできません。

<div id="group-management">
  ### グループ管理
</div>

```bash theme={null}
# グループの一覧表示と単一グループの取得
python windsurf_analytics.py list-groups --api-url https://your-server.com
python windsurf_analytics.py get-group --api-url https://your-server.com \
    --group-id GROUP_ID

# グループを作成し、モデルとACU上限を設定する
python windsurf_analytics.py create-group --api-url https://your-server.com \
    --name Engineering
python windsurf_analytics.py update-group --api-url https://your-server.com \
    --group-id GROUP_ID \
    --cascade-models MODEL_UID_1,MODEL_UID_2 \
    --set-cycle-acu-limit 50

# グループのモデル制限やACU上限を解除する。サービスAPIではグループ上限の
# 設定時に正の値が必要なため、解除は別の操作として行う。
python windsurf_analytics.py update-group --api-url https://your-server.com \
    --group-id GROUP_ID --clear-cascade-models --clear-cycle-acu-limit

# メンバーシップの管理（カンマ区切りのメールアドレス、最大1000件）
python windsurf_analytics.py add-group-members --api-url https://your-server.com \
    --group-id GROUP_ID --emails dev@agency.gov,lead@agency.gov
python windsurf_analytics.py remove-group-members --api-url https://your-server.com \
    --group-id GROUP_ID --emails dev@agency.gov

# グループを削除する（べき等）
python windsurf_analytics.py delete-group --api-url https://your-server.com \
    --group-id GROUP_ID
```

<div id="user-acu-caps">
  ### ユーザーごとのACU上限
</div>

```bash theme={null}
# ユーザーの設定値と実効の上限を取得する（--email または --user-id で指定）
python windsurf_analytics.py get-user-acu-cap --api-url https://your-server.com \
    --email dev@agency.gov

# 上限を設定する（0 を指定するとそのユーザーをブロック）、またはオーバーライドを解除する
python windsurf_analytics.py update-user-acu-cap --api-url https://your-server.com \
    --email dev@agency.gov --set-cycle-acu-limit 25
python windsurf_analytics.py update-user-acu-cap --api-url https://your-server.com \
    --email dev@agency.gov --clear-cycle-acu-limit
```