Présentation de l’API Cost Management de Microsoft 365 Copilot

L’API Cost Management pour Microsoft 365 Copilot permet aux administrateurs de régir et d’observer la consommation par les locataires des crédits Copilot et AI par le biais de Microsoft Graph, basé à /copilot/costManagement. Le contrat est basé sur des unités et est libellé en crédit. Il couvre l’instantané du solde de crédit du locataire, la gestion des stratégies de dépenses, l’étendue de l’audience de groupe, les paramètres par service, les alertes de seuil de notification uniquement et leurs destinataires, les soldes de consommation par utilisateur, l’examen des demandes de crédit des utilisateurs et les rapports d’utilisation qui décomposent la consommation par utilisateur, groupe de sécurité, service régi et classe de financement.

L’API est libellée en crédit et exclut délibérément les prévisions d’achat. Il ne renvoie aucune devise, facture, prix ou montant de règlement.

Fonctionnalités clés

• Lisez l’instantané du solde de crédit à l’échelle du client, avec une ligne par mode de facturation.
• Créez, lisez, mettez à jour et supprimez des stratégies de dépenses qui limitent la consommation de crédits Copilot pour une audience.
• Étendre une stratégie à chaque utilisateur du client (allUsersSpendingPolicy) ou à des groupes sélectionnés (selectedGroupsSpendingPolicy).
• Gérez l’audience d’un groupe de stratégies à l’aide $ref de liens de référence.
• Configurez les paramètres par service qui régissent ou excluent des services d’IA individuels dans une stratégie.
• Configurez les alertes de seuil de notification uniquement et gérez leurs destinataires.
• Diagnostiquez le solde de consommation par service d’un utilisateur et comprenez pourquoi un utilisateur peut ou ne peut pas utiliser un service.
• Répertoriez, examinez, approuvez ou rejetez les demandes de crédits Copilot des utilisateurs, individuellement ou en bloc.
• Rapport de consommation pour une journée UTC terminée par utilisateur, groupe de sécurité et service gouverné, avec classement et pagination.
• Déclarez la consommation d’un mois civil par classe de financement (prépayée, paiement à l’utilisation, dépassement non facturé et non facturable).
• Lisez les détails bruts d’utilisation d’un utilisateur sur une fenêtre d’horodatage, ventilés par service et session.

Exemples de scénarios

• Un administrateur définit une limite de crédit mensuelle pour un groupe pilote et alerte les administrateurs lorsque l’utilisation atteint 80 %.
• Un administrateur ajoute ou supprime un service gouverné sur une stratégie existante.
• Un administrateur de support diagnostique la raison pour laquelle un utilisateur ne peut plus consommer un service en lisant le solde par service de cet utilisateur.
• Un lecteur FinOps répertorie les stratégies de dépenses activées du client et passe en revue leurs limites configurées.
• Un administrateur IA examine les demandes de crédit en attente pour Work IQ et les approuve en bloc.
• Un analyste FinOps divise la consommation d’hier par service pour voir où les crédits sont allés dans les expériences d’IA.
• Un administrateur de facturation clôture un mois en examinant sa consommation par classe de financement, y compris les dépassements non facturés.
• Un analyste FinOps ou un responsable d’unité commerciale classe les utilisateurs ou les groupes de sécurité les plus consommateurs pour une journée.
• Un administrateur de support inspecte les sessions d’utilisation brute d’un utilisateur sur une fenêtre de temps.

Personas et rôles

Les personas cibles incluent l’administrateur IA et l’administrateur de licence pour la gestion des stratégies ; le FinOps/Global Reader et l’administrateur de facturation pour les lectures ; et l’administrateur du support/support technique pour les diagnostics par utilisateur. Pour les rapports d’utilisation, les personas cibles incluent l’analyste FinOps et l’administrateur de facturation pour les rapports sur les services et le financement, ainsi que l’analyste FinOps et le responsable de l’unité commerciale (BU) pour le classement des utilisateurs et des groupes. La création d’une stratégie de dépenses nécessite également le rôle d’annuaire Administrateur de facturation ou Administrateur général au moment de l’exécution.

Les administrateurs de facturation, les administrateurs généraux, les administrateurs d’IA, les lecteurs généraux et les lecteurs d’IA peuvent lire les demandes de crédit. Les administrateurs généraux, les administrateurs de facturation et les administrateurs d’IA peuvent les approuver ou les rejeter.

Autorisations

Cette API utilise la famille d’autorisations CopilotCostManagement-* . La plupart des opérations prennent uniquement en charge les autorisations déléguées (compte professionnel ou scolaire). La lecture du solde de crédit client (getTenantCreditBalance) prend également en charge l’autorisation d’applicationCopilotCostManagement.Read.All, et les rapports d’utilisation du service et du financement prennent également en charge les autorisations d’application et CopilotCostManagement.Read.All de financementCopilotCostManagement-Reports.Read.All. Les comptes Microsoft personnels ne sont pas pris en charge. Choisissez l’autorisation de moindre privilège pour chaque opération.

Liste des API

Sémantique d’accès concurrentiel et de suppression

• Pour muter une stratégie existante et ses ressources enfants (paramètres de service et liens de référence), incluez un If-Match en-tête avec l’ETag de la stratégie parente. Les paramètres de service et les liens de référence ne disposent pas de leur propre ETag. La stratégie parente gère l’accès concurrentiel et s’affiche comme parentEtag sur un paramètre de service. Lorsque vous créez une stratégie, elle n’a pas d’ETag existant et n’utilise If-Matchpas .
• La serviceSettings collection ne prend pas en charge DELETE. Définie state sur disabled pour supprimer un service. L’entrée reste dans cet état.
• Gérez les assignedGroups relations et recipients en tant que propriétés de navigation de référence avec $ref ajouter et supprimer.
• Les demandes de crédit portent leur propre ETag fort, retourné comme @odata.etag et dans l’en-tête de réponse ETag . La mise à jour de creditRequest nécessite un If-Match en-tête ; l’action batchRecordDecisions prend une valeur par élément etag à la place.
• Une décision de demande de crédit qui correspond à l’état actuel est une non-op qui conserve l’ETag, decisionByet les horodatages. L’ETag est toujours vérifié, donc une décision du même État avec un ETag obsolète échoue avec preconditionFailed.
• Les demandes de crédit ne peuvent pas être créées ou supprimées via l’API. Les utilisateurs les créent en dehors de Microsoft Graph et le service les conserve conformément à sa stratégie de rétention.

Rapport d’utilisation, sélecteurs d’heure et pagination

Les rapports d’utilisation résident sous /copilot/costManagement/usageReports. Chaque demande de rapport d’utilisation nécessite un sélecteur de temps, fourni en tant que paramètres de requête. Les demandes sans les sélecteurs requis sont rejetées avec une 400 unsupportedQuery réponse.

Les sélecteurs non valides sont rejetés, mais non limités. Les plages de jours actuels, futurs et de plusieurs jours des rapports terminés UTC renvoient une 400 réponse, tout comme les fenêtres d’horodatage qui ne respectent pas actuellement les limites de fenêtre d’horodatage dans la table. La validation n’applique pas un fichier plus ancien autorisé startDate ou month.

• Pagination. Les enregistrements d’utilisation des utilisateurs, des groupes et des services, ainsi que les sessions d’utilisation des utilisateurs, utilisent la pagination gérée par le serveur avec $skiptoken; $skip n’est pas pris en charge. Suivez l’URL complète @odata.nextLink inchangée. La suite conserve les sélecteurs, le filtre et l’ordre d’origine, mais il ne s’agit pas d’un instantané ponctuel. Les pages ultérieures lisent les données actives, de sorte que des lignes peuvent se répéter ou être manquées entre les pages. Une nextLink personne dont les dates diffèrent de la demande initiale est rejetée avec une 400 réponse. Dans les enregistrements d’utilisation de l’utilisateur, du groupe et du service, $top accepte un nombre entier compris entre 1 et 100, la valeur par défaut étant 10, et les valeurs en dehors de cette plage sont rejetées et non plafonnées. Les sessions d’utilisation utilisateur ont une taille de page par défaut distincte de 20 et un maximum de 100. Les enregistrements d’utilisation du financement et les services d’utilisation des utilisateurs ne sont pas paginés.
• Filtrage. Les enregistrements d’utilisation de l’utilisateur, du groupe et du service sont pris en charge $filter sur userId, groupIdet serviceId respectivement, en utilisant uniquement l’opérateur eq . D’autres opérateurs, comme in, ne sont pas pris en charge.
• Commande. Ne prend en charge que .consumedQuantity$orderby Les liens sont rompus en interne et le classement sur la clé de dimension n’est pas pris en charge.
• Unités. Chaque quantité porte un unit, actuellement copilotCredit. Aucune devise, facture, prix ou montant de règlement n’est retourné.
• Transformé versus brut. userUsageRecords Renvoie la consommation traitée pour un jour UTC terminé que vous pouvez classer parmi les utilisateurs. userUsageDetails Renvoie l’utilisation brute et facturable d’un utilisateur avec indicateur sur une fenêtre d’horodatage, avec des ventilations de services et de sessions. Les deux mesures, y compris leurs sessionCount valeurs, ne sont pas garanties égales.
• Parents illisibles. GET /copilot/costManagement/usageReports Renvoie une 404 réponse et ne transporte aucune donnée. GET /copilot/costManagement/usageReports/userUsageDetails n’est pas listable ; lire les détails par ID utilisateur à la place.

Conditions d’erreur

Les réponses d’erreur utilisent l’OData error standard et innerError l’enveloppe. Il innerError.code signale les conditions spécifiques à la charge de travail, tandis que l’OData error.code standard signale les conditions génériques. La sécurité au niveau des lignes s’exécute avant la recherche, de sorte qu’une ressource client hors étendue retourne une 404 réponse au lieu d’une 403 réponse.

L’action batchRecordDecisions renvoie des échecs par élément dans une 200 OK réponse, et non pas sous forme d’erreurs HTTP.

Contenu connexe

• type de ressource spendingPolicy
• costManagementUserBalance type de ressource
• type de ressource creditRequest
• costManagementUsageReportRoot type de ressource
• costManagementUserUsageRecord type de ressource