Nueva API de uso diario calificada por comercio v2 (beta)
Artigo
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.
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).
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).
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.
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".
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:
Puede obtener una colección de detalles del elemento de línea de factura (elemento de línea de facturación cerrado) de una factura especificada mediante las API del Centro de partners.
Puede obtener una colección de detalles de línea de consumo comercial no facturados para una factura especificada mediante las API del Centro de partners.
Puede obtener una colección de detalles de elementos de línea de conciliación no facturados para el período especificado mediante las API del Centro de partners.
Obtenga información sobre cómo obtener los elementos de línea de conciliación de uso clasificados diariamente mediante las API del Centro de partners, versión 2.
Aprende a usar la API de reconciliación de facturas emitidas para obtener partidas de facturación y conciliación de forma asincrónica mediante blobs de Azure.
