重要
/beta バージョンの API は変更される可能性があります。 実稼働アプリケーションでこれらの API を使用することは、サポートされていません。
Microsoft 365 Copilot Cost Management API を使用すると、管理者は、/copilot/costManagement に根ざした Microsoft Graph を通じて、Copilot および AI クレジットのテナント消費を管理および監視できます。 契約はユニット対応でクレジット建てです。 テナント クレジット残高のスナップショット、支出ポリシーの管理、グループの対象ユーザーのスコープ設定、サービスごとの設定、通知のみのしきい値アラートとその受信者、およびユーザーごとの消費残高について説明します。
この API はクレジット建てで、評価通貨、請求書、価格、購入予測を意図的に除外しています。
主な機能
- 課金方法ごとに 1 行のテナント全体のクレジット残高スナップショットを読み取ります。
- 対象ユーザーの Copilot クレジットの使用に制限する支出ポリシーを作成、読み取り、更新、削除します。
- ポリシーのスコープを、テナント内のすべてのユーザー (
allUsersSpendingPolicy) または選択したグループ (selectedGroupsSpendingPolicy) に設定します。 -
$ref参照リンクを使用してポリシーのグループ対象ユーザーを管理します。 - ポリシー内の個々の AI サービスを管理または除外するサービスごとの設定を構成します。
- 通知のみのしきい値アラートを構成し、受信者を管理します。
- ユーザーのサービスごとの消費残高を診断し、ユーザーがサービスを使用できる、または使用できない理由を理解します。
シナリオ例
- 管理者は、パイロット グループの月単位のクレジット上限を設定し、使用量が 80% に達すると管理者に警告します。
- 管理者が既存のポリシーで管理対象サービスを追加または削除します。
- サポート管理者は、サービスごとのユーザー残高を読み取って、ユーザーがサービスを利用できなくなった理由を診断します。
- FinOps リーダーは、テナントの有効な支出ポリシーを一覧表示し、構成された制限を確認します。
ペルソナとロール
対象ペルソナには、ポリシー管理用の AI 管理者とライセンス管理者が含まれます。読み取り用の FinOps/グローバル閲覧者および課金管理者。ユーザーごとの診断のサポート/ヘルプデスク管理者。 支出ポリシーを作成するには、実行時に課金管理者またはグローバル管理者ディレクトリ ロールも必要です。
アクセス許可
この API では、 CopilotCostManagement-* アクセス許可ファミリが使用されます。 ほとんどの操作では、委任された (職場または学校のアカウント) アクセス許可のみがサポートされます。テナント クレジット残高の読み取り (getTenantCreditBalance) は、 CopilotCostManagement.Read.All アプリケーションのアクセス許可もサポートします。 個人用の Microsoft アカウントはサポートされていません。 各操作の最低特権アクセス許可を選択します。
| アクセス許可 | 運用 |
|---|---|
CopilotCostManagement.Read.All |
テナント クレジット残高のスナップショットを読み取ります。 |
CopilotCostManagement-Policy.Read.All |
支出ポリシー、サービスごとの設定、アラートのしきい値、および受信者を読み取ります。 |
CopilotCostManagement-Policy.ReadWrite.All |
ポリシー、サービス設定、アラート、受信者を作成、更新、削除します。 |
CopilotCostManagement-Assignment.Read.All |
ポリシーのグループ対象ユーザーを読み取ります。 |
CopilotCostManagement-Assignment.ReadWrite.All |
ポリシーのグループ対象ユーザーを追加および削除します。 |
CopilotCostManagement-UserData.Read.All |
消費量や選択したspendingPolicyIdを含む、指定したユーザーの残高診断を読み取ります。 |
API リスト
| 操作 | HTTP メソッド | 説明 |
|---|---|---|
| テナント クレジット残高を取得する | GET /copilot/costManagement/getTenantCreditBalance |
テナント全体のクレジット残高スナップショットを取得します。 |
| spendingPolicies を一覧表示する | GET /copilot/costManagement/spendingPolicies |
支出ポリシーのリストを取得します。 |
| spendingPolicy の作成 | POST /copilot/costManagement/spendingPolicies |
新しい支出ポリシーを作成します。 |
| spendingPolicy を取得する | GET /copilot/costManagement/spendingPolicies/{id} |
支出ポリシーを取得します。 |
| spendingPolicy を更新する | PATCH /copilot/costManagement/spendingPolicies/{id} |
支出ポリシーを更新します。 |
| spendingPolicy の削除 | DELETE /copilot/costManagement/spendingPolicies/{id} |
支出ポリシーを削除します。 |
| assignedGroups の一覧表示 | GET /copilot/costManagement/spendingPolicies/{id}/microsoft.graph.selectedGroupsSpendingPolicy/assignedGroups |
ポリシーに割り当てられているグループを一覧表示します。 |
| assignedGroup の追加 | POST /copilot/costManagement/spendingPolicies/{id}/microsoft.graph.selectedGroupsSpendingPolicy/assignedGroups/$ref |
ポリシーにグループ参照を追加します。 |
| assignedGroup を削除する | DELETE /copilot/costManagement/spendingPolicies/{id}/microsoft.graph.selectedGroupsSpendingPolicy/assignedGroups/{groupId}/$ref |
グループ参照を削除します。 |
| spendingPolicyServiceSettings の一覧表示 | GET /copilot/costManagement/spendingPolicies/{id}/serviceSettings |
ポリシーのサービス設定を一覧表示します。 |
| spendingPolicyServiceSetting の作成 | POST /copilot/costManagement/spendingPolicies/{id}/serviceSettings |
ポリシーにサービスを追加します。 |
| get spendingPolicyServiceSetting | GET /copilot/costManagement/spendingPolicies/{id}/serviceSettings/{serviceId} |
サービス設定を取得します。 |
| spendingPolicyServiceSetting を更新する | PATCH /copilot/costManagement/spendingPolicies/{id}/serviceSettings/{serviceId} |
サービス設定を更新します。 |
| getCostManagementAlertSetting | GET /copilot/costManagement/spendingPolicies/{id}/emailThresholdSettings |
ポリシーのアラート構成を取得します。 |
| costManagementAlertSetting を更新する | PATCH /copilot/costManagement/spendingPolicies/{id}/emailThresholdSettings |
アラート構成を作成または更新します。 |
| costManagementAlertSetting を削除する | DELETE /copilot/costManagement/spendingPolicies/{id}/emailThresholdSettings |
アラート構成を削除します。 |
| 受信者を一覧表示する | GET /copilot/costManagement/spendingPolicies/{id}/emailThresholdSettings/recipients |
アラートの受信者を一覧表示します。 |
| 受信者の追加 | POST /copilot/costManagement/spendingPolicies/{id}/emailThresholdSettings/recipients/$ref |
アラートの受信者を追加します。 |
| 受信者の削除 | DELETE /copilot/costManagement/spendingPolicies/{id}/emailThresholdSettings/recipients/{userId}/$ref |
アラートの受信者を削除します。 |
| getManagementUserBalance | GET /copilot/costManagement/userBalances/{userId} |
ユーザーの消費残高を取得します。 |
| costManagementUserServiceBalances の一覧表示 | GET /copilot/costManagement/userBalances/{userId}/serviceBalances |
ユーザーのサービスごとの残高行を一覧表示します。 |
| getManagementUserServiceBalance | GET /copilot/costManagement/userBalances/{userId}/serviceBalances/{serviceId} |
ユーザーの 1 つのサービスの残高行を取得します。 |
同時実行と削除のセマンティクス
- 既存のポリシーとその子リソース (サービス設定と参照リンク) をミュートするには、親ポリシーの ETag に
If-Matchヘッダーを含めます。 サービス設定と参照リンクには独自の ETag がありません。 親ポリシーは同時実行を管理し、サービス設定でparentEtagとして表示されます。 ポリシーを作成すると、既存の ETag はなく、If-Matchは使用されません。 -
serviceSettingsコレクションはDELETEをサポートしていません。 サービスを削除するには、[state] を [disabled] に設定します。 エントリはその状態のままになります。 -
$refの追加と削除を使用して、assignedGroupsとrecipientsのリレーションシップを参照ナビゲーション プロパティとして管理します。
エラーの条件
エラー応答では、標準の OData error と innerError エンベロープが使用されます。
innerError.code はワークロード固有の条件を報告し、標準の OData error.codeは汎用条件を報告します。 行レベルのセキュリティは参照の前に実行されるため、スコープ外のテナント リソースは、403応答ではなく404応答を返します。
| 条件 | HTTP | エラー コード |
|---|---|---|
| 呼び出し元に必要なアクセス許可または修飾するディレクトリ ロールがありません | 403 | Authorization_RequestDenied |
| サポートされていないクエリ オプションまたは形式が正しくない要求 | 400 |
invalidRequest, unsupportedQuery |
| 最後に割り当てられたグループを削除すると、ポリシーには対象ユーザーが割り当てられていないままになります | 409 | lastAssignedGroup |
| 無効になっていない別のテナント全体のポリシーで、同じサービスが既に管理されています | 409 | allUsersServiceConflict |
| グループ スコープのポリシーは、割り当てられたグループと有効なサービスの両方を別の無効になっていないポリシーと共有します | 409 | groupServiceConflict |
| サービス設定のあるポリシーで最後に有効にしたサービスを無効にする | 409 | atLeastOneServiceRequired |
| アラートのしきい値が範囲外 (パーセンテージしきい値は整数 1 から 100 にする必要があります) | 400 | invalidAlertThreshold |
| 編集可能な状態ではないポリシーのフィールドにパッチを適用する | 400 | policyNotEditableWhilePending |
| 不明または無効なサービス ID | 400 | invalidService |
| 受信者がリンクされていない状態でアラートが有効になっている場合、またはアラートが有効になっているときに最後の受信者を削除した場合 | 400 | alertRecipientsRequired |
| アラートの受信者参照がテナント ディレクトリ内の実際のユーザーに解決されない | 400 | alertRecipientNotFound |
| PATCH でのサーバー管理フィールドの提供 | 400 | invalidRequest |
変更操作での古いIf-Match |
412 | preconditionFailed |
| 競合している同時状態の遷移 | 409 | invalidTransition |
| すべてのサービスでアップストリーム エバリュエーターが失敗したため、残高行を生成できませんでした | 503 | sourceUnavailable |
| API 調整 | 429 | tooManyRequests |