Python SDK - Devin Docs

このドキュメントは、Devin の連邦政府向け導入環境向けです。Devin Docs に戻る

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

要件

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

認証

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

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

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

コマンド

コマンド	エンドポイント	必要な権限
`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 レポートが実行されます。

出力とエラー

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

使用例

ユーザー別の使用量レポート

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

ACU消費量

# 現在の請求サイクルのチーム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 つ指定する必要があります。グループスコープのキーでは、割り当てられたグループのみを選択でき、チーム合計やチームユーザー行をリクエストすることはできません。

グループ管理

# グループの一覧表示と単一グループの取得
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

ユーザーごとのACU上限

# ユーザーの設定値と実効の上限を取得する（--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

​要件

​認証

​コマンド

​出力とエラー

​使用例

​ユーザー別の使用量レポート

​ACU消費量

​グループ管理

​ユーザーごとのACU上限

要件

認証

コマンド

出力とエラー

使用例

ユーザー別の使用量レポート

ACU消費量

グループ管理

ユーザーごとのACU上限