Nueva API de uso diario calificada por comercio v2 (beta)
Se aplica a: Centro de partners | Centro de partners operado por 21Vianet | Centro de partners para Microsoft Cloud for US Government
Use estas API para obtener nuevos datos de uso facturados y no facturados diariamente de forma asincrónica.
Nota:
Esta API quedará en desuso pronto. Para garantizar operaciones sin problemas, se recomienda migrar a la versión de disponibilidad general. Estos son los detalles que debe planear con antelación:
Objetivo: recuperar los elementos de línea de uso valorados diariamente facturados para los períodos de facturación desde septiembre de 2022 antes del 21 de enero de 2025.
Acción: use esta API, pero migre a disponibilidad general v2 lo antes posible.
Objetivo: recuperar los elementos de línea de uso valorados diariamente facturados para los períodos de facturación desde el 21 de enero de 2025 .
Acción: use solo api v2 GA.
Objetivo: recuperar elementos de línea de uso no facturados diarios para los períodos de facturación actuales y anteriores antes del 21 de enero de 2025.
Acción: use esta API, pero migre a disponibilidad general v2 lo antes posible.
Objetivo: recuperar elementos de línea de uso no facturados diarios para los períodos de facturación actuales y anteriores del 21 de enero de 2025.
Acción: use solo api v2 GA.
Para una transición sin problemas a las nuevas API, siga este vínculo: API de conciliación de uso facturada y no facturada diaria v2 (GA).
Gracias por su atención y esperamos su éxito continuo con nuestras API de facturación.
Nota:
Puede acceder a los elementos de línea de uso no facturados diariamente a través de la API o el portal del Centro de partners. Para garantizar la precisión de los datos, permita hasta 24 horas para la disponibilidad. Dependiendo de su ubicación y cuando los medidores notifiquen el uso, puede haber más retrasos.
Priorizamos la entrega del tiempo de los datos de uso valorados diariamente en primer lugar. En ocasiones, es posible que no vea los datos de uso no facturados diarios más recientes hasta que estén disponibles los datos de uso facturados del mes anterior. Una vez que reciba los datos de uso facturados, podrá recuperar todos los datos de uso no facturados actualizados desde el inicio del mes.
Su comprensión y paciencia se aprecian a medida que nos esforzamos por proporcionar la información más precisa y oportuna posible.
Importante
Los datos de uso clasificados diariamente no incluyen 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 o Marketplace
Introducción a la API
La API asincrónica es un método innovador para acceder rápidamente a los datos de facturación y conciliación en fragmentos administrables. Elimina la necesidad de mantener una conexión abierta durante horas y recorrer millones de transacciones de forma iterativa.
Usamos patrones asincrónicos de clave de valet y solicitud-respuesta para optimizar nuestras API de facturación y conciliación para ofrecer los resultados de forma asincrónica. Las respuestas de API proporcionan un token para acceder a los datos de conciliación con todos los atributos o un subconjunto.
Puede descargar los datos de uso de forma asincrónica mediante tres pasos nuevos (puntos de conexión de API). Para más información, lea las secciones siguientes:
Punto de conexión de elemento de línea de uso
Use esta API para acceder a los elementos de línea de consumo facturados o no facturados. Devuelve un estado HTTP 202 y un encabezado de ubicación con la dirección URL, que debe sondear 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
Hasta que reciba el estado correcto, siga sondeando esta API a intervalos regulares. Si los datos solicitados no están disponibles, la respuesta de la API incluye un encabezado Retry-After que indica cuánto tiempo debe esperar antes de enviar otra solicitud.
Punto de conexión de manifiesto
Este punto de conexión proporciona una carpeta de almacenamiento desde la que se pueden descargar los datos de facturación reales. La respuesta divide o divide los archivos para optimizar el rendimiento y el paralelismo de E/S.
Diagrama de secuencia
En el diagrama se muestran los pasos necesarios para descargar los datos de conciliación.
Secuencia de acciones del usuario
Siga estos pasos para recuperar los datos de conciliación.
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
Obtiene elementos de línea de uso no facturados para el mes actual o el último calendario.
Solicitud a la API
POST https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/unbilledusage?fragment={fragment}&period={period}?currencyCode={currencyCode}
Parámetros de solicitud
| Nombre | In | Obligatorio | Tipo | Descripción |
|---|---|---|---|---|
| fragmento | Consultar | False | Cadena | Elija "full" para obtener una respuesta completa o "básica" para un subconjunto de atributos. El valor predeterminado es "full". Consulte la lista de atributos de este artículo. |
| period | Consultar | True | String | Use "current" o "last" para obtener el uso del mes actual o del último calendario. El valor "last" es el mismo que "anterior" en las API V1 existentes. |
| currencyCode | Consultar | True | String | Código de moneda de facturación de partners. |
Parámetros de solicitud en desuso
La versión más reciente de la API no requiere los siguientes parámetros de URI:
| Nombre | Descripción |
|---|---|
| Proveedor | N/A. (Devuelve todo el uso del plan de Azure y es equivalente a la "única vez" de las API V1 existentes). |
| hasPartnerEarnedCredit | N/A. (devuelve todos los datos, independientemente de PEC). |
| Size | N/A. |
| Desplazamiento | N/A. |
| seekOperation | N/A. |
Encabezado de solicitud
Consulte la lista de encabezados de solicitud para la API en este artículo.
Cuerpo de la solicitud
N/A.
Respuesta de la API
HTTP/1.1 202 Accepted Operation-Location: https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingoperations/811bb8f0-8aca-4807-897c-c15ce50820d6
LA API devuelve el estado HTTP 202. En función de la solicitud, la API puede devolver otro estado estándar.
| Nombre | Descripción |
|---|---|
| 202 - Aceptado | Se acepta la solicitud. Consulte la dirección URL del encabezado operation-location para el estado de la solicitud. |
Obtener elementos de línea de uso facturados
Obtenga los elementos de línea de uso facturados clasificados para el período de facturación cerrado.
Solicitud a la API
POST https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billedusage/invoices/{invoiceId}?fragment={fragment}
Parámetros de solicitud
| Nombre | In | Obligatorio | Tipo | Descripción |
|---|---|---|---|---|
| invoiceId | Ruta de acceso | True | String | Número de factura del Centro de partners. |
| Fragmento | Consultar | False | Cadena | Elija "full" para obtener una respuesta completa o "básica" para un subconjunto de atributos. El valor predeterminado es "full". Consulte la lista de atributos de este artículo. |
Parámetros de solicitud en desuso
La versión más reciente de la API no requiere los siguientes parámetros de URI:
| Nombre | Descripción |
|---|---|
| Proveedor | N/A. (Devuelve todo el uso del plan de Azure y es equivalente a la "única vez" de las API V1 existentes). |
| hasPartnerEarnedCredit | N/A. (devuelve todos los datos, independientemente de PEC). |
| Size | N/A. |
| Desplazamiento | N/A. |
| seekOperation | N/A. |
Encabezado de solicitud
Consulte la lista de encabezados de solicitud para la API en este artículo.
Cuerpo de la solicitud
N/A.
Respuesta de la API
HTTP/1.1 202 Accepted Operation-Location: https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingoperations/06d01983-07bf-4448-83b4-1e83ab1d4640
LA API devuelve "HTTP 202 Accepted". En función de la API de solicitud, puede devolver otro estado estándar.
| Nombre | Descripción |
|---|---|
| 202 - Aceptado | Se acepta la solicitud. Compruebe el estado de la solicitud sondeando la dirección URL del encabezado operation-location. |
Paso 2: Comprobar el estado de la solicitud
Espere a que http 200 tenga un estado de terminal correcto o con errores. La dirección URL del manifiesto es "resourceLocation" en el estado correcto.
Obtener el estado de la operación
Obtiene el estado de una solicitud de datos de conciliación.
Solicitud a la API
GET https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingoperations/06d01983-07bf-4448-83b4-1e63ab1d3640
Parámetros de solicitud
| Nombre | In | Obligatorio | Tipo | Descripción |
|---|---|---|---|---|
| operationId | Ruta de acceso | True | String | El identificador de la operación. |
Encabezado de solicitud
Consulte la lista de encabezados de solicitud para la API en este artículo.
Cuerpo de la solicitud
N/A.
Estado de respuesta
Además del estado HTTP estándar de este artículo, la API puede devolver este estado HTTP:
| Nombre | Descripción |
|---|---|
| 410 Ya no existe | Cada vínculo de operación está activo durante una cantidad especificada de tiempo controlado por el servidor. Una vez transcurrido el tiempo transcurrido, el cliente debe enviar una nueva solicitud. |
Carga de respuesta
La carga de respuesta de la API devuelve los atributos siguientes:
| Nombre | Opcionales | Descripción |
|---|---|---|
| createdDateTime | false | Tiempo de solicitud. |
| lastActionDateTime | false | Hora de cambio de estado. |
| resourceLocation | true | Identificador URI de carga del manifiesto. |
| status | false | Valores y acciones posibles. |
| Valor | Acción del cliente |
|---|---|
| notstarted | Realice otra llamada para comprobar el estado después de esperar el tiempo especificado en el encabezado "Retry-After". |
| en ejecución | Realice otra llamada para comprobar el estado después de esperar el tiempo especificado en el encabezado "Retry-After". |
| succeeded | El estado final de la operación, que indica que los datos están listos. Recupere la carga del manifiesto mediante el URI especificado en resourceLocation. |
| con errores | Estado terminal, que indica un error permanente. Reinicie la operación. |
Para el atributo de error:
| Nombre | Opcionales | Descripción |
|---|---|---|
| error | true | Detalles del error proporcionados en formato JSON si se produce un error en el estado de la operación. |
| Nombre | Opcionales | Descripción |
|---|---|---|
| message | false | Describe el error en detalle. |
| code | false | Indica el tipo de error que se produjo. |
Solicitud a la API
GET https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingoperations/06d01983-07bf-4447-83b4-1e83ab1d3640
Respuesta de la API
La respuesta sugiere esperar 10 segundos antes de volver a intentarlo al procesar datos.
HTTP/1.1 200 OK
Retry-After: 10
{
"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://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingoperations/06d01983-07bf-4447-83b4-1e83ab1d3640
Respuesta de la API
La API devuelve el estado "correcto" y el URI "resourceLocation".
HTTP/1.1 200 OK
Content-Type: application/json
{
"createdDateTime": "2022-06-1T10-01-03.4Z",
"lastActionDateTime": "2022-06-1T10-01-13Z",
"status": "succeeded",
"resourceLocation": "https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingmanifests/e03e1882-ff59-4c09-882f-74e60b4d7743"
}
Paso 3: Obtención de la carga del manifiesto
El autor de la llamada realiza una solicitud GET a la dirección URL del manifiesto para obtener más información sobre dónde se almacenan los datos de conciliación en blobs de Azure.
Obtención del manifiesto
Recupera el manifiesto que tiene información sobre la ubicación de Almacenamiento de Azure de los datos de conciliación.
Solicitud a la API
GET https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingmanifests/{manifestId}
Parámetros de solicitud
| Nombre | In | Obligatorio | Tipo | Descripción |
|---|---|---|---|---|
| manifestId | Ruta de acceso | True | String | Identificador del manifiesto. |
Encabezado de solicitud
Consulte la [lista de encabezados de solicitud para la API] en este artículo.
Cuerpo de la solicitud
N/A.
Estado de respuesta
Además del estado HTTP estándar, la API puede devolver este estado HTTP:
| Nombre | Descripción |
|---|---|
| 410 Ya no existe | Cada vínculo de manifiesto está activo durante una cantidad especificada de tiempo controlado por el servidor. Una vez transcurrido el tiempo transcurrido, el cliente debe enviar una nueva solicitud. |
Carga de respuesta
La respuesta de la API devuelve los atributos siguientes:
| Nombre | Descripción |
|---|---|
| Versión | Versión del esquema del manifiesto. |
| dataFormat | Formato de archivo de datos de facturación. Valores posibles comprimidosJSONLines: cada blob es un archivo comprimido y los datos del archivo están en formato de líneas JSON. Para acceder a los datos, descomprima el archivo. |
| utcCreatedDateTime | Tiempo de creación del archivo de manifiesto. |
| eTag | Versión de datos del manifiesto. Un cambio en la información de facturación genera un nuevo valor de eTag. |
| partnerTenantId | Id. de inquilino del asociado. |
| rootFolder | Directorio raíz del archivo. |
| rootFolderSAS | Token de SAS para acceder al archivo. |
| partitionType | Esta propiedad divide los datos. Si una partición determinada tiene más del número admitido, los datos se dividen en varios archivos correspondientes a "partitionValue". De forma predeterminada, el sistema particiona los datos 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 porque el principio de partición podría cambiar. |
| blobCount | Recuento total de archivos para este identificador de inquilino del asociado. |
| sizeInBytes | Total de bytes en todos los archivos. |
| blobs | Matriz JSON de objetos "blob" que tienen los detalles de todos los archivos para el identificador de inquilino del asociado. |
| Blob (objeto) | |
| Nombre | Nombre del blob. |
| sizeInBytes | Tamaño de blob en bytes. |
| partitionValue | Partición que contiene el archivo. Una partición grande se dividirá en varios archivos, cada uno con el mismo "partitionValue". |
Carga de manifiesto de ejemplo
{
"version": "1",
"dataFormat": "compressedJSONLines",
"utcCretedDateTime": "2022-04-29T22:40:57.1853571Z",
"eTag": "0x5B168C7B6E589D2",
"partnerTenantId": "14f593ad-1edc-474d-aaa0-83abbf9638da",
"rootFolder": "https://{billing.blob.core.windows.net}/{folder_path}",
"rootFolderSAS": "\*\*\*",
"partitionType": "ItemCount",
"blobCount": 3,
"sizeInBytes": 2000,
"blobs": [
{
"name": "{blobName1.json.gz}",
"sizeinBytes": 500,
"partitionValue": "1"
},
{
"name": "{blobName2.json.gz}",
"sizeinBytes": 1000,
"partitionValue": "2"
},
{
"name": "{blobName3.json.gz}",
"sizeinBytes": 500,
"partitionValue": "3"
}
]
}
Paso 4: Descarga de datos de conciliación de uso desde la ubicación de almacenamiento
Obtenga el token de SAS y la ubicación del almacenamiento de blobs de las propiedades "rootFolderSAS" y "rootFolder" 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 de líneas JSON .
Encabezados de solicitud de API estándar
Todas las API aceptan los siguientes encabezados:
| Nombre | Obligatorio | Tipo | Descripción |
|---|---|---|---|
| Autorización | True | String | Token de portador de autorización. |
| ms-correlationid | False | Cadena | Un rastreador de solicitudes interno. Cada solicitud genera un nuevo rastreador (GUID). |
| ms-cv | False | Cadena | Un rastreador de solicitudes interno. |
| ms-requestid | False | Cadena | Identificador de idempotency de solicitud. |
Estados de respuesta de API estándar
A continuación se muestran los estados HTTP de la respuesta de la API:
| Nombre | Descripción |
|---|---|
| 400 - Solicitud incorrecta | Faltaban datos o eran incorrectos. Los detalles del error se incluyen en el cuerpo de la respuesta. |
| 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 Prohibida | El autor de la llamada no está autorizado para realizar la solicitud. |
| 500 Error interno del servidor | La API o una de sus dependencias no pueden cumplir la solicitud. Vuelva a intentarlo más tarde. |
| 404 No encontrado | Recurso no disponible con parámetros de entrada. |
| 410 Ya no existe | El vínculo de manifiesto agota el tiempo de espera o transcurrido. Envíe una nueva solicitud. |
Atributos de datos de uso
La respuesta de la API de uso facturada o no facturada con el parámetro de solicitud "completo" o "básico" devuelve los siguientes atributos:
| Atributo | "full" | "básico" |
|---|---|---|
| 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í |