Introducción a la API de administración de costes de Microsoft 365 Copilot

Importante

Las API de la /beta versión están sujetas a cambios. No se admite el uso de estas API en aplicaciones de producción.

La API de administración de costos de Microsoft 365 Copilot permite a los administradores controlar y observar el consumo de inquilinos de créditos de Copilot e IA a través de Microsoft Graph, con raíz en /copilot/costManagement. El contrato es consciente de la unidad y está denominado en crédito. Abarca la instantánea del saldo de crédito del inquilino, la administración de la directiva de gastos, el ámbito de audiencia de grupo, la configuración por servicio, las alertas de umbral solo de notificación y sus destinatarios, y los saldos de consumo por usuario.

La API está denominada en crédito y excluye deliberadamente la moneda calificada, las facturas, los precios y las previsiones de compra.

Principales funcionalidades

  • Lea la instantánea del saldo de crédito de todo el inquilino, con una fila por método de facturación.
  • Crear, leer, actualizar y eliminar directivas de gasto que limiten el consumo de créditos de Copilot para una audiencia.
  • Ámbito de una directiva para todos los usuarios del inquilino (allUsersSpendingPolicy) o para grupos seleccionados (selectedGroupsSpendingPolicy).
  • Administrar la audiencia del grupo de una directiva mediante $ref vínculos de referencia.
  • Configure las opciones por servicio que rigen o excluyen los servicios de IA individuales dentro de una directiva.
  • Configure alertas de umbral solo de notificación y administre sus destinatarios.
  • Diagnosticar el equilibrio de consumo por servicio de un usuario y comprender por qué un usuario puede o no consumir un servicio.

Escenarios de ejemplo

  • Un administrador establece un límite de crédito mensual para un grupo piloto y alerta a los administradores cuando el uso alcanza el 80 por ciento.
  • Un administrador agrega o quita un servicio gobernado en una directiva existente.
  • Un administrador de soporte técnico diagnostica por qué un usuario ya no puede consumir un servicio leyendo el saldo por servicio de ese usuario.
  • Un lector de FinOps enumera las directivas de gasto habilitadas del inquilino y revisa sus límites configurados.

Personas y roles

Las personas objetivo incluyen el administrador de IA y el administrador de licencias para la gestión de políticas; FinOps/Global Reader y Billing Administrator para lecturas; y el administrador de soporte técnico o del departamento de soporte técnico para los diagnósticos por usuario. La creación de una directiva de gastos también requiere el rol de directorio Administrador de facturación o Administrador global en tiempo de ejecución.

Permissions

Esta API utiliza la familia de CopilotCostManagement-* permisos. La mayoría de las operaciones solo admiten permisos delegados (cuenta profesional o educativa); el saldo de crédito del inquilino leído (getTenantCreditBalance) también admite el permiso de aplicación CopilotCostManagement.Read.All . No se admiten cuentas personales de Microsoft. Elija el permiso con privilegios mínimos para cada operación.

Permiso Operaciones
CopilotCostManagement.Read.All Lea la instantánea del saldo de crédito del inquilino.
CopilotCostManagement-Policy.Read.All Lee las directivas de gasto, la configuración por servicio, los umbrales de alerta y los destinatarios.
CopilotCostManagement-Policy.ReadWrite.All Crear, actualizar y eliminar directivas, configuraciones de servicio, alertas y destinatarios.
CopilotCostManagement-Assignment.Read.All Lea la audiencia del grupo de una directiva.
CopilotCostManagement-Assignment.ReadWrite.All Agregar y quitar el público de grupo de una directiva.
CopilotCostManagement-UserData.Read.All Leer los diagnósticos de saldo de un usuario designado, incluidos el consumo y los datos seleccionados spendingPolicyId.

Lista de API

Operación Método HTTP Description
Obtener el saldo de crédito del inquilino GET /copilot/costManagement/getTenantCreditBalance Obtenga la instantánea del saldo de crédito de todo el inquilino.
Enumerar directivas de gasto GET /copilot/costManagement/spendingPolicies Obtener una lista de directivas de gasto.
Crear directiva de gasto POST /copilot/costManagement/spendingPolicies Cree una nueva directiva de gastos.
Obtener SpendingPolicy GET /copilot/costManagement/spendingPolicies/{id} Recuperar una directiva de gastos.
Actualizar la directiva de gasto PATCH /copilot/costManagement/spendingPolicies/{id} Actualizar una directiva de gastos.
Eliminar directiva de gasto DELETE /copilot/costManagement/spendingPolicies/{id} Eliminar una directiva de gastos.
Lista de grupos asignados GET /copilot/costManagement/spendingPolicies/{id}/microsoft.graph.selectedGroupsSpendingPolicy/assignedGroups Enumerar los grupos asignados a una directiva.
Agregar AssignedGroup POST /copilot/costManagement/spendingPolicies/{id}/microsoft.graph.selectedGroupsSpendingPolicy/assignedGroups/$ref Agregar una referencia de grupo a una directiva.
Quitar assignedGroup DELETE /copilot/costManagement/spendingPolicies/{id}/microsoft.graph.selectedGroupsSpendingPolicy/assignedGroups/{groupId}/$ref Quitar una referencia de grupo.
List spendingPolicyServiceSettings GET /copilot/costManagement/spendingPolicies/{id}/serviceSettings Enumerar la configuración de servicio de una directiva.
Crear spendingPolicyServiceSetting POST /copilot/costManagement/spendingPolicies/{id}/serviceSettings Agregar un servicio a una directiva.
Get spendingPolicyServiceSetting GET /copilot/costManagement/spendingPolicies/{id}/serviceSettings/{serviceId} Recuperar una configuración de servicio.
Update spendingPolicyServiceSetting PATCH /copilot/costManagement/spendingPolicies/{id}/serviceSettings/{serviceId} Actualizar una configuración de servicio.
Obtener costManagementAlertSetting GET /copilot/costManagement/spendingPolicies/{id}/emailThresholdSettings Recuperar la configuración de alertas de una directiva.
Update costManagementAlertSetting PATCH /copilot/costManagement/spendingPolicies/{id}/emailThresholdSettings Crear o actualizar la configuración de alerta.
Eliminar costManagementAlertSetting DELETE /copilot/costManagement/spendingPolicies/{id}/emailThresholdSettings Elimine la configuración de alerta.
Enumerar destinatarios GET /copilot/costManagement/spendingPolicies/{id}/emailThresholdSettings/recipients Enumerar los destinatarios de la alerta.
Agregar destinatario POST /copilot/costManagement/spendingPolicies/{id}/emailThresholdSettings/recipients/$ref Agregue un destinatario de alerta.
Quitar destinatario DELETE /copilot/costManagement/spendingPolicies/{id}/emailThresholdSettings/recipients/{userId}/$ref Quitar un destinatario de la alerta.
Obtener costManagementUserBalance GET /copilot/costManagement/userBalances/{userId} Recuperar el saldo de consumo de un usuario.
List costManagementUserServiceBalances GET /copilot/costManagement/userBalances/{userId}/serviceBalances Enumerar las filas de saldo por servicio de un usuario.
Obtener costManagementUserServiceBalance GET /copilot/costManagement/userBalances/{userId}/serviceBalances/{serviceId} Recuperar la fila de saldo de un servicio para un usuario.

Simultaneidad y semántica de eliminación

  • Para mutar una directiva existente y sus recursos secundarios (configuración de servicio y vínculos de referencia), incluya un If-Match encabezado con el ETag de la directiva principal. La configuración del servicio y los vínculos de referencia no tienen su propia ETag. La directiva principal administra la simultaneidad y aparece como parentEtag una configuración de servicio. Cuando se crea una directiva, no existe ETag y no usa If-Match.
  • La serviceSettings colección no es compatible con DELETE. Establézcalo state en disabled para quitar un servicio. La entrada permanece en ese estado.
  • Administre las relaciones como recipients propiedades de assignedGroups navegación de referencia con $ref agregar y quitar.

Condiciones de error

Las respuestas de error usan el OData error y innerError el sobre estándar. Informa innerError.code de las condiciones específicas de la carga de trabajo, mientras que el OData error.code estándar informa de condiciones genéricas. La seguridad de nivel de fila se ejecuta antes de la búsqueda, por lo que un recurso de inquilino fuera del ámbito devuelve una 404 respuesta en lugar de una 403 respuesta.

Condición HTTP Código de error
El autor de la llamada carece del permiso necesario o de un rol de directorio cualificado 403 Authorization_RequestDenied
Opción de consulta no admitida o solicitud con formato incorrecto 400 invalidRequest, unsupportedQuery
Quitar el último grupo asignado dejaría la directiva sin público asignado 409 lastAssignedGroup
Otra directiva de todo el inquilino no deshabilitada ya rige el mismo servicio 409 allUsersServiceConflict
Una directiva de ámbito de grupo comparte un grupo asignado y un servicio habilitado con otra directiva no deshabilitada 409 groupServiceConflict
Deshabilitar el último servicio habilitado en una directiva que tiene configuración de servicio 409 atLeastOneServiceRequired
Valor del umbral de alerta fuera del intervalo (los umbrales de porcentaje deben ser un entero del 1 al 100) 400 invalidAlertThreshold
Aplicar revisiones a cualquier campo de una directiva que no esté en un estado editable 400 policyNotEditableWhilePending
Id. de servicio desconocido o no válido 400 invalidService
Alertas habilitadas sin destinatario vinculado o eliminar el último destinatario mientras la alerta está habilitada 400 alertRecipientsRequired
La referencia del destinatario de la alerta no se resuelve en un usuario real del directorio de inquilinos 400 alertRecipientNotFound
Proporcionar un campo administrado por el servidor en PATCH 400 invalidRequest
Obsolescencia If-Match en una operación mutante 412 preconditionFailed
Transición de estado simultáneo en conflicto 409 invalidTransition
El evaluador ascendente falló en cada servicio, por lo que no se pudo producir ninguna fila de saldo 503 sourceUnavailable
Limitación de API 429 tooManyRequests

Contenido relacionado

  • Se actualizó por última vez el