Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
Wichtig
APIs unter der /beta Version können sich ändern. Die Verwendung dieser APIs in Produktionsanwendungen wird nicht unterstützt.
Mit der Microsoft 365 Copilot Cost Management-API können Administratoren den Mandantenverbrauch von Copilot- und KI-Guthaben über Microsoft Graph steuern und beobachten./copilot/costManagement Der Vertrag ist einheitenorientiert und kreditbezogen. Es umfasst die Momentaufnahme des Mandantenguthabens, die Verwaltung von Ausgabenrichtlinien, das Definieren des Bereichs der Gruppenzielgruppen, Einstellungen pro Dienst, Schwellenwertwarnungen nur über Benachrichtigungen und deren Empfänger sowie Verbrauchsguthaben pro Benutzer.
Die API ist kreditbezogen und schließt bewusst bewertete Währungen, Rechnungen, Preise und Kaufprognosen aus.
Wichtige Funktionen
- Lesen der mandantenweiten Momentaufnahme des Guthabens mit einer Zeile pro Abrechnungsmethode.
- Erstellen, Lesen, Aktualisieren und Löschen von Ausgabenrichtlinien, die den Verbrauch von Copilot-Gutschriften für eine Zielgruppe begrenzen.
- Beschränken Sie eine Richtlinie auf jeden Benutzer im Mandanten (
allUsersSpendingPolicy) oder auf ausgewählte Gruppen (selectedGroupsSpendingPolicy). - Verwalten Sie die Gruppenbenutzergruppe einer Richtlinie über
$refReferenzlinks. - Konfigurieren Sie Einstellungen pro Dienst, die einzelne KI-Dienste innerhalb einer Richtlinie steuern oder ausschließen.
- Konfigurieren Sie Schwellenwertwarnungen nur über Benachrichtigungen und verwalten Sie deren Empfänger.
- Diagnostizieren Sie die Verbrauchsbilanz pro Dienst eines Benutzers und verstehen Sie, warum ein Benutzer einen Dienst nutzen kann oder nicht.
Beispielszenarien
- Ein Administrator legt eine monatliche Kreditobergrenze für eine Pilotgruppe fest und benachrichtigt die Administratoren, wenn die Nutzung 80 Prozent erreicht.
- Ein Administrator fügt einer vorhandenen Richtlinie einen gesteuerten Dienst hinzu oder entfernt ihn.
- Ein Supportadministrator diagnostiziert, warum ein Benutzer einen Dienst nicht mehr nutzen kann, indem er den Saldo pro Dienst dieses Benutzers liest.
- Ein FinOps-Reader listet die aktivierten Ausgabenrichtlinien des Mandanten auf und überprüft die konfigurierten Limits.
Funktionspersonas und Rollen
Zu den Zielpersonas gehören der KI-Administrator und der Lizenzadministrator für die Richtlinienverwaltung; der FinOps/Global Reader and Billing Administrator für Lesevorgänge; und dem Support-/Helpdeskadministrator für benutzerspezifische Diagnosen. Zum Erstellen einer Ausgabenrichtlinie ist zur Laufzeit auch die Verzeichnisrolle Abrechnungsadministrator oder Globaler Administrator erforderlich.
Berechtigungen
Diese API verwendet die CopilotCostManagement-* Berechtigungsfamilie. Die meisten Vorgänge unterstützen nur delegierte Berechtigungen (Geschäfts-, Schul- oder Unikonto). Das gelesene Mandantenguthaben (getTenantCreditBalance) unterstützt auch die CopilotCostManagement.Read.All Anwendungsberechtigung. Persönliche Microsoft-Konten werden nicht unterstützt. Wählen Sie für jeden Vorgang die Berechtigung mit den geringsten Berechtigungen aus.
| Permission | Vorgänge |
|---|---|
CopilotCostManagement.Read.All |
Lesen Sie die Momentaufnahme des Mandantenguthabens. |
CopilotCostManagement-Policy.Read.All |
Lesen Sie Ausgabenrichtlinien, Einstellungen pro Dienst, Warnungsschwellenwerte und Empfänger. |
CopilotCostManagement-Policy.ReadWrite.All |
Erstellen, Aktualisieren und Löschen von Richtlinien, Diensteinstellungen, Warnungen und Empfängern. |
CopilotCostManagement-Assignment.Read.All |
Lesen der Gruppenzielgruppe einer Richtlinie. |
CopilotCostManagement-Assignment.ReadWrite.All |
Hinzufügen und Entfernen der Gruppenzielgruppe einer Richtlinie. |
CopilotCostManagement-UserData.Read.All |
Lesen Sie die Saldo-Diagnose eines benannten Benutzers, einschließlich Verbrauch und ausgewählter spendingPolicyId. |
API-Liste
| Vorgang | HTTP-Methode | Beschreibung |
|---|---|---|
| Abrufen des Mandantenguthabens | GET /copilot/costManagement/getTenantCreditBalance |
Rufen Sie die mandantenweite Momentaufnahme des Guthabens ab. |
| Auflisten von Ausgabenrichtlinien | GET /copilot/costManagement/spendingPolicies |
Rufen Sie eine Liste der Ausgabenrichtlinien ab. |
| Erstellen einer Ausgabenrichtlinie | POST /copilot/costManagement/spendingPolicies |
Erstellen Sie eine neue Ausgabenrichtlinie. |
| Abrufen von expenditureingPolicy | GET /copilot/costManagement/spendingPolicies/{id} |
Abrufen einer Ausgabenrichtlinie. |
| Update spendingPolicy | PATCH /copilot/costManagement/spendingPolicies/{id} |
Aktualisieren einer Ausgabenrichtlinie. |
| Ausgabenrichtlinie löschen | DELETE /copilot/costManagement/spendingPolicies/{id} |
Löschen einer Ausgabenrichtlinie. |
| Listen Sie assignedGroups auf | GET /copilot/costManagement/spendingPolicies/{id}/microsoft.graph.selectedGroupsSpendingPolicy/assignedGroups |
Listen Sie die Gruppen auf, die einer Richtlinie zugewiesen sind. |
| Zugewiesene Gruppe hinzufügen | POST /copilot/costManagement/spendingPolicies/{id}/microsoft.graph.selectedGroupsSpendingPolicy/assignedGroups/$ref |
Hinzufügen eines Gruppenverweises zu einer Richtlinie. |
| Entfernen der zugewiesenen Gruppe | DELETE /copilot/costManagement/spendingPolicies/{id}/microsoft.graph.selectedGroupsSpendingPolicy/assignedGroups/{groupId}/$ref |
Entfernen eines Gruppenverweises. |
| Auflisten von AusgabenPolicyServiceSettings | GET /copilot/costManagement/spendingPolicies/{id}/serviceSettings |
Auflisten der Diensteinstellungen einer Richtlinie. |
| Erstellen von "spendingPolicyServiceSetting" | POST /copilot/costManagement/spendingPolicies/{id}/serviceSettings |
Hinzufügen eines Diensts zu einer Richtlinie. |
| Abrufen von "spendingPolicyServiceSetting" | GET /copilot/costManagement/spendingPolicies/{id}/serviceSettings/{serviceId} |
Rufen Sie eine Diensteinstellung ab. |
| Update spendingPolicyServiceSetting | PATCH /copilot/costManagement/spendingPolicies/{id}/serviceSettings/{serviceId} |
Aktualisieren einer Diensteinstellung. |
| Get costManagementAlertSetting | GET /copilot/costManagement/spendingPolicies/{id}/emailThresholdSettings |
Abrufen der Warnungskonfiguration einer Richtlinie. |
| Aktualisieren costManagementAlertSetting | PATCH /copilot/costManagement/spendingPolicies/{id}/emailThresholdSettings |
Erstellen oder Aktualisieren der Warnungskonfiguration. |
| Löschen costManagementAlertSetting | DELETE /copilot/costManagement/spendingPolicies/{id}/emailThresholdSettings |
Löschen Sie die Warnungskonfiguration. |
| Empfänger auflisten | GET /copilot/costManagement/spendingPolicies/{id}/emailThresholdSettings/recipients |
Auflisten der Warnungsempfänger. |
| Empfänger hinzufügen | POST /copilot/costManagement/spendingPolicies/{id}/emailThresholdSettings/recipients/$ref |
Fügen Sie einen Warnungsempfänger hinzu. |
| Empfänger entfernen | DELETE /copilot/costManagement/spendingPolicies/{id}/emailThresholdSettings/recipients/{userId}/$ref |
Entfernen eines Warnungsempfängers. |
| Get costManagementUserBalance | GET /copilot/costManagement/userBalances/{userId} |
Rufen Sie den Verbrauchssaldo eines Benutzers ab. |
| List costManagementUserServiceBalances | GET /copilot/costManagement/userBalances/{userId}/serviceBalances |
Listen Sie die Saldozeilen pro Dienst eines Benutzers auf. |
| Get costManagementUserServiceBalance | GET /copilot/costManagement/userBalances/{userId}/serviceBalances/{serviceId} |
Rufen Sie die Saldozeile eines Diensts für einen Benutzer ab. |
Parallelität und Entfernungssemantik
- Um eine vorhandene Richtlinie und ihre untergeordneten Ressourcen (Diensteinstellungen und Referenzlinks) zu ändern, fügen Sie einen
If-MatchHeader mit dem ETag der übergeordneten Richtlinie ein. Diensteinstellungen und Referenzlinks haben keine eigenen ETag. Die übergeordnete Richtlinie verwaltet die Parallelität und wird wieparentEtagin einer Diensteinstellung angezeigt. Wenn Sie eine Richtlinie erstellen, verfügt sie über kein vorhandenes ETag und verwendetIf-Matchnicht . - Die
serviceSettingsSammlung unterstütztDELETEnicht . Legen Sie diese Einstellungstateaufdisabledfest, um einen Dienst zu entfernen. Der Eintrag verbleibt in diesem Status. - Verwalten Sie die
assignedGroupsund-Beziehungenrecipientsals Referenznavigationseigenschaften mit$refHinzufügen und Entfernen.
Fehlerbedingungen
Fehlerantworten verwenden die Standard-OData error und innerError Hüllkurve. Das meldet innerError.code workloadspezifische Bedingungen, während das Standard-OData error.code generische Bedingungen meldet. Die Sicherheit auf Zeilenebene wird vor der Suche ausgeführt, sodass eine Mandantenressource, die sich außerhalb des Gültigkeitsbereichs befindet, eine 404 Antwort anstatt einer 403 Antwort zurückgibt.
| Bedingung | HTTP | Fehlercode |
|---|---|---|
| Dem Aufrufer fehlt die erforderliche Berechtigung oder eine qualifizierende Verzeichnisrolle | 403 | Authorization_RequestDenied |
| Nicht unterstützte Abfrageoption oder falsch formatierte Anforderung | 400 |
invalidRequest, unsupportedQuery |
| Wenn die zuletzt zugewiesene Gruppe entfernt wird, bleibt die Richtlinie ohne zugewiesene Zielgruppe | 409 | lastAssignedGroup |
| Eine andere, nicht deaktivierte mandantenweite Richtlinie regelt bereits denselben Dienst | 409 | allUsersServiceConflict |
| Eine gruppenbezogene Richtlinie gibt sowohl eine zugewiesene Gruppe als auch einen aktivierten Dienst für eine andere nicht deaktivierte Richtlinie gleich | 409 | groupServiceConflict |
| Deaktivieren des zuletzt aktivierten Diensts in einer Richtlinie, die Diensteinstellungen aufweist | 409 | atLeastOneServiceRequired |
| Warnungsschwellenwert außerhalb des zulässigen Bereichs (prozentuale Schwellenwerte müssen eine ganze Zahl von 1 bis 100 sein) | 400 | invalidAlertThreshold |
| PATCHen eines Felds in einer Richtlinie, die sich nicht in einem bearbeitbaren Zustand befindet | 400 | policyNotEditableWhilePending |
| Unbekannte oder ungültige Dienst-ID | 400 | invalidService |
| Warnfunktionen sind ohne Empfängerlink aktiviert oder entfernen des letzten Empfängers, während die Alarmierung aktiviert ist | 400 | alertRecipientsRequired |
| Warnungsempfängerverweis wird nicht in einen realen Benutzer im Mandantenverzeichnis aufgelöst | 400 | alertRecipientNotFound |
| Bereitstellen eines vom Server verwalteten Feldes auf PATCH | 400 | invalidRequest |
Veraltet If-Match bei einem Mutationsvorgang |
412 | preconditionFailed |
| Widersprüchlicher gleichzeitiger Statusübergang | 409 | invalidTransition |
| Upstream-Auswertung ist für jeden Dienst fehlgeschlagen, sodass keine Saldozeile erstellt werden konnte | 503 | sourceUnavailable |
| API-Drosselung | 429 | tooManyRequests |