API de conciliación de uso facturada y no facturada diaria v2 (GA)
Se aplica a: Centro de partners (no disponible en Azure Government, Azure Alemania o Azure China 21Vianet).
Nuestras API asincrónicas ofrecen una manera más rápida y fácil de acceder a los datos de facturación y conciliación a través de blobs de Azure. Con estas API, no es necesario mantener abierta la conexión durante horas ni recorrer en bucle los lotes de 2000 elementos de línea.
Hemos optimizado nuestras nuevas API de conciliación de uso con clasificación diaria de comercio mediante la clave de valet y los patrones asincrónicos de solicitud-respuesta . Al usar estas API, recibirá un token que puede usar para acceder a todos los atributos o a un subconjunto de los datos de conciliación de uso clasificados diariamente.
Nota:
Las nuevas API no se hospedan en el host de api del Centro de partners. En su lugar, puede encontrarlos en MS Graph en Uso de Microsoft Graph API para exportar datos de facturación de asociados: Microsoft Graph v1.0 | Microsoft Learn. Para acceder a estas API, consulte los detalles siguientes.
Ahora solo puede usar estas API para la nube pública o global de MS Graph. Aún no están disponibles para Azure Government, Azure Alemania o Azure China 21Vianet.
Nota:
Si ha estado usando nuestra versión beta, es posible que no observe cambios significativos en la versión disponible con carácter general (GA). Se recomienda comparar las dos versiones para comprender las diferencias y las actualizaciones.
Importante
El nuevo uso diario del comercio no incluye los cargos por estos productos:
- Reserva de Azure
- Plan de ahorro de Azure
- Office
- Dynamics
- Microsoft Power Apps
- Software perpetuo
- Suscripción de software
- Producto SaaS que no es de Microsoft
Introducción a la API
Para recuperar nuevos elementos de línea de uso clasificados diariamente de comercio de forma asincrónica, use dos puntos de conexión de API. Este es el proceso:
Punto de conexión de elemento de línea de uso
Use esta API para recuperar elementos de línea de uso facturados o no facturados diariamente. Obtiene un estado HTTP 202 y una dirección URL en el encabezado de ubicación. Sondee esta dirección URL a intervalos regulares hasta que reciba un estado correcto con una dirección URL de manifiesto.
Punto de conexión de estado de la operación
Para obtener un estado correcto, siga llamando a esta API a intervalos regulares. Si los datos no están listos, la respuesta de la API incluye un encabezado Retry-After para indicarle cuánto tiempo debe esperar antes de volver a intentarlo. Una vez completada la operación, obtendrá un recurso de manifiesto con una carpeta de almacenamiento donde puede descargar los datos de uso. La respuesta divide los archivos en partes más pequeñas para optimizar el rendimiento y el paralelismo de E/S.
Diagrama de secuencia
Este es un diagrama de secuencia que muestra los pasos para descargar los datos de conciliación.
Secuencia de acciones del usuario
Para recuperar nuevos artículos de línea de conciliación de uso con clasificación diaria comercial, siga estos pasos:
Paso 1: Enviar solicitud
Envíe una solicitud POST al punto de conexión de API.
Obtención de elementos de línea de uso no facturados diarios
Obtenga nuevos artículos de línea de uso no facturados diariamente para el mes actual o el último mes natural o período de facturación.
Solicitud a la API
POST https://graph.microsoft.com/v1.0/reports/partners/billing/usage/unbilled/export
Accept: application/json
Content-Type: application/json
{
"currencyCode": "USD",
"billingPeriod": "current",
"attributeSet": "basic"
}
Cuerpo de la solicitud
| Atributo | Obligatorio | Type | Descripción |
|---|---|---|---|
| attributeSet | False | Cadena | Elija "full" para todos los atributos o "básico" para un conjunto limitado. El valor predeterminado es "full". (Consulte la lista de atributos aquí). Opcional. |
| billingPeriod | True | String | Use "current" o "last" (igual que "anterior" en las API V1) para obtener el uso de clasificación diaria para el mes actual o el último mes natural o período de facturación. Necesario. |
| currencyCode | True | String | Código de moneda de facturación de partners. Necesario. |
Encabezados de solicitud
Para solicitar encabezados para la API, consulte Confiabilidad y soporte técnico.
Respuesta de la API
HTTP/1.1 202 Accepted
Location: https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14
Cuando se usa la API, normalmente devuelve un estado HTTP 202. Para ver otros estados posibles en función de las solicitudes, consulte Estados de respuesta de API estándar.
| Código | Descripción |
|---|---|
| 202 – Aceptado | Se aceptó la solicitud. Para comprobar el estado de la solicitud, consulte la dirección URL proporcionada en el encabezado de ubicación. |
Obtención de elementos de línea de uso valorados diariamente facturados
Obtenga nuevos artículos de línea de uso facturados diariamente para una factura para el período de facturación cerrado.
Solicitud a la API
POST https://graph.microsoft.com/v1.0/reports/partners/billing/usage/billed/export
{
"invoiceId": "G00012345",
"attributeSet": "full"
}
Parámetros de consulta
N/D
Cuerpo de la solicitud
| Atributo | Obligatorio | Type | Descripción |
|---|---|---|---|
| invoiceId | True | String | Un identificador único para cada factura. Necesario. |
| attributeSet | False | Cadena | Elija "full" para todos los atributos o "básico" para un conjunto limitado. El valor predeterminado es "full". (Consulte la lista de atributos aquí). Opcional. |
Encabezado de solicitud
Encabezados de solicitud para la API. Para más información, consulte la confiabilidad y la compatibilidad.
Respuesta de la API
HTTP/1.1 202 Aceptado
Ubicación: https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14
Cuando se usa la API, normalmente devuelve un estado HTTP 202. Para ver otros estados posibles en función de las solicitudes, consulte Estados.
| Código | Descripción |
|---|---|
| 202 – Aceptado | Se aceptó la solicitud. Para comprobar el estado de la solicitud, consulte la dirección URL proporcionada en el encabezado de ubicación. |
Paso 2: Comprobar el estado de la solicitud
Para comprobar el estado de una solicitud, espere una respuesta HTTP 200 con un estado de "correcto" o "error". Si la solicitud se realiza correctamente, la dirección URL del manifiesto se proporciona en el atributo "resourceLocation".
Obtener el estado de la operación
Recupera el estado de una solicitud.
Solicitud a la API
Parámetros de solicitud
| Nombre | Incluir en | Obligatorio | Type | Descripción |
|---|---|---|---|---|
| operationId | URI de solicitud | True | String | Identificador único para comprobar el estado de la solicitud. Necesario. |
Encabezado de solicitud
Para solicitar encabezados para la API, consulte Confiabilidad y soporte técnico.
Cuerpo de la solicitud
N/D
Estado de respuesta
Además de los estados HTTP estándar, la API puede devolver el siguiente estado HTTP:
| Código | Descripción |
|---|---|
| 410 – Desaparecido | El vínculo de manifiesto solo está activo durante una duración específica establecida por el servidor. Una vez transcurrido este tiempo, debe enviar una nueva solicitud para acceder al manifiesto. |
Carga de respuesta
La carga de respuesta de la API incluye los siguientes atributos:
| Atributo | Obligatorio | Descripción |
|---|---|---|
| id | True | Un identificador único para cada respuesta. Necesario. |
| status | True | Valores y acciones (obligatorios): notstarted: espere el tiempo especificado en el encabezado "Retry-After" y, a continuación, realice otra llamada para comprobar el estado. running: espere el tiempo especificado en el encabezado "Retry-After" y, a continuación, realice otra llamada para comprobar el estado. correcto: los datos están listos. Recupere la carga del manifiesto mediante el URI especificado en resourceLocation. failed: la operación no se pudo realizar de forma permanente. Reinícielo. |
| createdDateTime | True | Hora a la que se realizó la solicitud. Necesario. |
| lastActionDateTime | True | Hora en que se cambió por última vez el estado. Necesario. |
| resourceLocation | False | Identificador URI de la carga del manifiesto. Opcional. |
| error | False | Si se produce un error en la operación, los detalles del error se proporcionan en formato JSON. Opcional. Es posible que se incluyan los siguientes atributos: message (Obligatorio): una descripción detallada del error. code (Obligatorio): tipo de error que se produjo. |
Objeto de ubicación de recursos
| Atributo | Descripción |
|---|---|
| id | Identificador único del manifiesto. |
| schemaVersion | Versión del esquema del manifiesto. |
| dataFormat | Formato del archivo de datos de facturación. compressedJSON: formato de datos donde cada blob es un archivo comprimido que contiene datos en formato de líneas JSON . Para recuperar los datos de cada blob, descomprima. |
| createdDateTime | Fecha y hora en que se creó el archivo de manifiesto. |
| eTag | Versión de los datos del manifiesto. Un cambio en la información de facturación genera un nuevo valor. |
| partnerTenantId | Identificador del inquilino del asociado. |
| rootDirectory | Directorio raíz del archivo. |
| sasToken | Token de SAS (firma de acceso compartido) que le permite leer todos los archivos del directorio. |
| partitionType | Divide los datos en varios blobs en función del atributo "partitionValue". El sistema divide las particiones que superan el número admitido. De forma predeterminada, los datos se particionan en función del número de elementos de línea del archivo. No establezca un número fijo de elementos de línea o tamaño de archivo en el código, ya que estos valores pueden cambiar. |
| blobCount | Número total de archivos para este identificador de inquilino del asociado. |
| blobs | Matriz JSON de objetos "blob" que contienen los detalles del archivo para el identificador de inquilino del asociado. |
| objeto de blob | Objeto que contiene los detalles siguientes: |
| nombre | Nombre del blob. |
| partitionValue | Partición que contiene el archivo. La partición grande se divide en varios archivos, con cada archivo que contiene el mismo "partitionValue". |
Solicitud a la API
GET <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>
Respuesta de la API
La respuesta recomienda esperar 10 segundos antes de intentarlo de nuevo al procesar datos.
HTTP/1.1 200 OK
Retry-After: 10
{
"id": "9ab9cb54-d07f-4f52-9ea6-a09d7de52c14",
"createdDateTime": "2022-06-1T10-01-03.4Z",
"lastActionDateTime": "2022-06-1T10-01-05Z",
"status": "running"
}
Solicitud a la API
(10 segundos después de la solicitud anterior...)
GET <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>
Respuesta de la API
La API devuelve el estado "correcto" y el URI de "resourceLocation".
HTTP/1.1 200 OK
Content-Type: application/json
{
"@odata.context": "https://graph.microsoft.com/v1.0/\$metadata#reports/partners/billing/operations/\$entity",
"@odata.type": "#microsoft.graph.partners.billing.exportSuccessOperation",
"id": "f2170b13-6a8e-47d6-b481-6988490dc0cb",
"createdDateTime": "2023-12-05T21:17:29Z",
"lastActionDateTime": "2023-12-05T21:18:00.8897902Z",
"status": "succeeded",
"resourceLocation": {
"id": "44e8500b-ab92-490e-8ac3-90500a1d3427",
"createdDateTime": "2023-11-06T19:58:47.513Z",
"schemaVersion": "2",
"dataFormat": "compressedJSON",
"partitionType": "default",
"eTag": "RwDrn7fbiTXy6UULE",
"partnerTenantId": "0e195b37-4574-4539-bc42-0e539b9684c0",
"rootDirectory": "https://adlsreconbuprodeastus201.blob.core.windows.net/path_id",
"sasToken": "{token}",
"blobCount": 1,
"blobs": \[
{
"name": "part-00123-5a93fa5d-749f-48bc-a372-9b021d93c3fa.c000.json.gz",
"partitionValue": "default"
}
\]
}
}
Paso 3: Descarga de elementos de línea de conciliación de uso clasificados diariamente de Azure Blob Storage
Obtenga el token de firma de acceso compartido (SAS) y la ubicación de almacenamiento de blobs desde las propiedades "sasToken" y "rootDirectory" de la respuesta de la API de carga del manifiesto. Use el SDK o la herramienta de Azure Storage para descargar y descomprimir el archivo de blob. Está en formato JSONLines .
Sugerencia
Consulte nuestro código de ejemplo para descargar y descomprimir el archivo de blob de Azure en la base de datos local.
Estados de respuesta de API estándar
Es posible que reciba estos estados HTTP de la respuesta de la API:
| Código | Descripción |
|---|---|
| 400: Solicitud incorrecta | Falta la solicitud o contiene datos incorrectos. Compruebe el cuerpo de la respuesta para obtener los detalles del error. |
| 401 - No autorizado | El autor de la llamada no está autenticado y debe autenticarse con el servicio de API de asociado antes de realizar la primera llamada. |
| 403 - Prohibido | No tiene la autorización necesaria para realizar la solicitud. |
| 404: No encontrado | Los recursos solicitados no están disponibles con los parámetros de entrada proporcionados. |
| 410 – Desaparecido | El vínculo de manifiesto agota el tiempo de espera o ha expirado. Envíe una nueva solicitud. |
| 500: Error interno del servidor | La API o una de sus dependencias no pueden cumplir la solicitud en este momento. Vuelva a intentarlo más tarde. |
Comparación de versiones beta y de disponibilidad general
Consulte la tabla de comparación para comprender las diferencias entre las versiones beta y de disponibilidad general (GA). Si usa la versión beta, cambiar a la versión de disponibilidad general debe ser sencillo.
| Información importante | Beta | Disponible en general |
|---|---|---|
| Punto de conexión de host de API | https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/ |
https://graph.microsoft.com/v1.0/reports/partners/billing/usage/ |
| HTTP method | POST | PUBLICAR |
| Punto de conexión de API de uso no facturado diario | https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/unbilledusage |
https://graph.microsoft.com/v1.0/reports/partners/billing/usage/unbilled/export |
| Parámetros de entrada para la API de uso diaria no facturada | Para especificar parámetros en la solicitud de API, inclúyelos en la cadena de consulta de la dirección URL de la solicitud. Por ejemplo, para especificar los parámetros period y currencyCode, anexe ?period=current¤cyCode=usd a la dirección URL de la solicitud. |
Para proporcionar entradas, incluya un objeto JSON en el cuerpo de la solicitud. El objeto JSON debe contener las siguientes propiedades: * currencyCode: el código de moneda de la factura. Por ejemplo, USD. * billingPeriod: período de facturación de la factura. Por ejemplo, actual. Este es un ejemplo de un objeto JSON que incluye las propiedades currencyCode y billingPeriod: <br>{<br> "currencyCode": "USD",<br> "billingPeriod": "current"<br>} |
| Punto de conexión de API de uso diario facturado | https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billedusage/invoices/{InvoiceId} |
https://graph.microsoft.com/v1.0/reports/partners/billing/usage/billed/export |
| Parámetros de entrada para la API de uso diaria facturada | Para especificar parámetros en la solicitud de API, incluya invoiceId en la dirección URL de la solicitud. Además, puede incluir un parámetro de fragmento opcional en la cadena de consulta para recuperar el conjunto completo de atributos. Por ejemplo, para recuperar el conjunto completo de atributos, anexe ?fragment=full a la dirección URL de la solicitud. |
Para proporcionar entradas, incluya un objeto JSON en el cuerpo de la solicitud. El objeto JSON debe contener las siguientes propiedades: * invoiceId: el identificador de la factura. Por ejemplo, G00012345. * attributeSet: conjunto de atributos que se van a incluir en la respuesta. Por ejemplo, lleno. Este es un ejemplo de un objeto JSON que incluye las propiedades invoiceId y attributeSet: {<br> "invoiceId": "G00012345",<br> "attributeSet": "full"<br>} |
| Recurso de manifiesto | Use un método GET /manifests/{id} independiente para recuperar el recurso de manifiesto. | Use el método GET /operations/{Id}, que devuelve el recurso de manifiesto relacionado en resourceLocation, lo que elimina la necesidad de una llamada independiente al método GET /manifests/{id}. |
| Cambios en el esquema del manifiesto | ||
| "id": No disponible | "id": identificador único para el recurso de manifiesto. | |
| "version": Disponible | "version": se ha cambiado el nombre a "schemaversion". | |
| "dataFormat": Disponible | "dataFormat": disponible. | |
| "utcCretedDateTime": disponible | "utcCretedDateTime": se ha cambiado el nombre a "createdDateTime". | |
| "eTag": Disponible | "eTag": Disponible. | |
| "partnerTenantId": disponible | "partnerTenantId": disponible | |
| "rootFolder": Disponible | "rootFolder": se ha cambiado el nombre a "rootDirectory". | |
| "rootFolderSAS": disponible | "rootFolderSAS": se ha cambiado el nombre a "sasToken". Ahora proporciona un token y ya no incluye la ruta de acceso del directorio raíz. Para acceder al directorio, use la propiedad "rootDirectory" en su lugar. | |
| "partitionType": Disponible | "partitionType": disponible. | |
| "blobCount": disponible | "blobCount": disponible. | |
| "sizeInBytes": Disponible | "sizeInBytes": no disponible. | |
| "blobs": disponible | "blobs": disponible. | |
| "blob object": disponible | "blob object": disponible. | |
| "name": Disponible | "name": Disponible. | |
| "partitionValue": Disponible | "partitionValue": disponible. |
Atributos de elemento de línea de conciliación de uso clasificados diariamente
Para comparar los atributos devueltos por la API de conciliación de uso calificada diariamente para los conjuntos de atributos "completos" o "básicos", consulte la siguiente información.
| Attribute | Completo | Basic |
|---|---|---|
| PartnerId | sí | sí |
| PartnerName | sí | sí |
| CustomerId | sí | sí |
| CustomerName | sí | Sí |
| CustomerDomainName | sí | no |
| CustomerCountry | sí | no |
| MpnId | sí | no |
| Tier2MpnId | sí | no |
| InvoiceNumber | sí | sí |
| ProductId | sí | sí |
| SkuId | sí | sí |
| AvailabilityId | sí | no |
| SkuName | sí | sí |
| ProductName | sí | no |
| PublisherName | sí | sí |
| PublisherId | sí | no |
| SubscriptionDescription | sí | no |
| SubscriptionId | sí | sí |
| ChargeStartDate | sí | sí |
| ChargeEndDate | sí | sí |
| UsageDate | sí | sí |
| MeterType | sí | no |
| MeterCategory | sí | no |
| MeterId | sí | no |
| MeterSubCategory | sí | no |
| MeterName | sí | no |
| MeterRegion | sí | no |
| Unidad | sí | sí |
| ResourceLocation | sí | no |
| ConsumedService | sí | no |
| ResourceGroup | sí | no |
| ResourceURI | sí | sí |
| ChargeType | sí | sí |
| UnitPrice | sí | sí |
| Cantidad | sí | sí |
| UnitType | sí | no |
| BillingPreTaxTotal | sí | sí |
| BillingCurrency | sí | sí |
| PricingPreTaxTotal | sí | sí |
| PricingCurrency | sí | sí |
| ServiceInfo1 | sí | no |
| ServiceInfo2 | sí | no |
| Etiquetas | sí | no |
| AdditionalInfo | sí | no |
| EffectiveUnitPrice | sí | sí |
| PCToBCExchangeRate | sí | sí |
| EntitlementId | sí | sí |
| EntitlementDescription | sí | no |
| PartnerEarnedCreditPercentage | sí | no |
| CreditPercentage | sí | sí |
| CreditType | sí | sí |
| BenefitOrderID | sí | sí |
| BenefitID | sí | no |
| BenefitType | sí | sí |
Importante
Tome nota de estos cambios al pasar a api v2 de v1.
El nombre de cada atributo se inicia en mayúsculas.
unitOfMeasure ahora es Unit. El significado y el valor del atributo son los mismos.
resellerMpnId ahora es Tier2MpnId. El significado y el valor del atributo son los mismos.
El nombre y el valor de rateOfPartnerEarnedCredit han cambiado a PartnerEarnedCreditPercentage. El nuevo nombre y el valor del atributo reflejan el porcentaje en lugar de la fracción. Por ejemplo, 0.15 es ahora 15.
rateOfCredit es ahora CreditPercentage. El significado y el valor del atributo han cambiado. Por ejemplo, la versión 1.00 ahora es 100.
Código de ejemplo
Para más información, consulte Ejemplos de API del Centro de partners: Obtención de datos de conciliación de facturación.
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de