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. Use la versión de disponibilidad general en su lugar. Consulte los detalles siguientes para obtener más información.
Solo puede usar esta API para el uso diario facturado clasificado hasta el 30 de septiembre de 2024. Consulte los detalles para seleccionar la versión correcta de la API y planear con antelación.
- Vaya a disponibilidad general v2 lo antes posible. Hasta entonces, use esta API para obtener elementos de línea de uso clasificados diariamente para nuevas facturas comerciales para períodosde facturación desde septiembre de 2022.
- Use solo la DISPONIBILIDAD general de la API v2 del 1 de octubre de 2024 para obtener elementos de línea de uso clasificados diariamente para las nuevas facturas comerciales para los períodosde facturación desde septiembre de 2022.
Esta API solo se puede usar para el uso de clasificación diaria no facturada hasta el 30 de septiembre de 2024. Consulte los detalles para seleccionar la versión correcta de la API y planear con antelación.
- Vaya a disponibilidad general v2 lo antes posible. Hasta entonces, use esta API para obtener nuevos artículos de línea de uso no facturados diariamente para los períodos de facturación actuales y anteriores.
- Use solo la DISPONIBILIDAD general de la API v2 del 1 de octubre de 2024 para obtener nuevos elementos de línea de uso no facturados diariamente para los períodos de facturación actuales y anteriores.
Para acceder a las nuevas API de disponibilidad general v2, consulte este vínculo:
API de conciliación de uso facturada y no facturada diaria v2 (GA)
Nota:
Puede recuperar los elementos de línea de uso no facturados diarios a través de la API o el portal del Centro de partners. Los datos pueden tardar hasta 24 horas en estar disponibles. Sin embargo, puede haber más retrasos en función de su ubicación y cuando los medidores notifiquen el uso.
A veces, es posible que no vea los datos de uso no facturados más recientes hasta que se entreguen los datos de uso facturados del mes anterior. Esto se hace para asegurarse de que los datos de uso facturados se entregan dentro del tiempo acordado. Una vez que reciba los datos de uso facturados, debería poder recuperar todos los datos de uso no facturados actualizados desde el inicio del mes.
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
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.
Hemos usado los patrones de clave de acceso limitado y solicitud-respuesta asincrónica para optimizar nuestras API de facturación y conciliación para proporcionar los resultados de forma asincrónica. Las respuestas de API proporcionarán 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 lo siguiente:
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. Devolverá 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 incluirá 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 siguiente se muestran los pasos necesarios para descargar los datos de conciliación.
Secuencia de acciones del usuario
Siga los pasos que se indican a continuación 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 |
|---|---|---|---|---|
| fragment | 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/D (Devuelve todo el uso del plan de Azure y es equivalente a la "única vez" de las API V1 existentes). |
| hasPartnerEarnedCredit | N/D (devuelve todos los datos, independientemente de PEC). |
| Size | N/D |
| Contrapartida | N/D |
| seekOperation | N/D |
Encabezado de solicitud
Consulte la lista de encabezados de solicitud para la API en este artículo.
Cuerpo de la solicitud
N/D
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/D (Devuelve todo el uso del plan de Azure y es equivalente a la "única vez" de las API V1 existentes). |
| hasPartnerEarnedCredit | N/D (devuelve todos los datos, independientemente de PEC). |
| Size | N/D |
| Contrapartida | N/D |
| seekOperation | N/D |
Encabezado de solicitud
Consulte la lista de encabezados de solicitud para la API en este artículo.
Cuerpo de la solicitud
N/D
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 será "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/D
Estado de respuesta
Además del estado HTTP estándar de este artículo, la API puede devolver el siguiente 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, 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/D
Estado de respuesta
Además del estado HTTP estándar, la API puede devolver el siguiente 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, 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. Descomprima el archivo para acceder a los datos. |
| 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 dividirán en varios archivos correspondientes a "partitionValue". Los datos se particionan por el número de elementos de línea del archivo de forma predeterminada. No establezca un número fijo de elementos de línea o tamaño de archivo en el código porque podrían 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 ha agotado el tiempo de espera o ha 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í |
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente las Cuestiones de GitHub como mecanismo de retroalimentación para el contenido y lo sustituiremos por un nuevo sistema de retroalimentación. Para más información, consulta: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de