API de conciliación de uso facturada y no facturada diaria v2 (GA)

Se aplica a: Centro de partners (no disponible en Azure Government o Azure China 21Vianet)

Descripción de la arquitectura

La nueva API asincrónica ofrece importantes avances en la forma en que se controla el acceso a datos de facturación y conciliación. Este enfoque resuelve los desafíos asociados a los métodos sincrónicos tradicionales, como mantener conexiones de larga duración y procesar lotes de datos grandes. Estas son las principales ventajas y mecanismos de esta API:

Componentes claves

Protección del acceso con el patrón de clave de valet

El patrón de clave de valet proporciona acceso seguro y limitado a los datos de facturación. De forma similar a la forma en que una llave de valet permite a alguien conducir el coche sin tener acceso al tronco, este patrón garantiza un control de acceso pormenorizado. En lugar de compartir credenciales, un token de firma de acceso compartido (SAS) concede acceso limitado y limitado a recursos específicos. Este patrón reduce el riesgo de acceso no autorizado mediante la configuración de tiempos de expiración precisos y permisos de acceso.

Eficacia mejorada mediante el patrón asincrónico de solicitud-respuesta

Piense en ello como pedir en un restaurante ocupado. En lugar de esperar en el mostrador, recibe un zumbido y puede hacer otras cosas mientras su pedido está preparado. Cuando los datos estén listos, el sistema le notifica.

La naturaleza asincrónica de la API significa que realiza una solicitud y el sistema lo procesa en segundo plano. Esta solicitud-respuesta asincrónica usa eficazmente recursos, reduce la carga del servidor y minimiza los tiempos de espera y los errores comunes con la recuperación de datos sincrónica.

Flexibilidad en los permisos de acceso a datos

Los tokens de SAS ofrecen flexibilidad en la administración de permisos de acceso a datos. Puede generar tokens que concedan acceso a todos los atributos de los datos de conciliación de facturas facturadas o limitar el acceso a subconjuntos específicos. Esta granularidad permite a las organizaciones adaptar el acceso a los datos según las directivas internas y los requisitos normativos, lo que mejora la seguridad y el cumplimiento.

Flujo de trabajo simplificado y tiempos de procesamiento de datos mejorados

El patrón asincrónico de solicitud-respuesta simplifica el procesamiento de datos al permitir el acceso dinámico en lugar de lotes fijos de 2000 elementos de línea. Este enfoque conduce a resultados más rápidos y tiempos de procesamiento mejorados, lo que simplifica la integración de los datos de facturación y conciliación en los sistemas y flujos de trabajo existentes.

Ventajas

1. Ventajas de rendimiento

   En lugar de mantener conexiones de larga duración y procesar lotes fijos, el nuevo sistema le permite:

   • Realice una solicitud inicial rápida.
   • Reciba un token de acceso seguro.
   • Procese los datos a su propio ritmo.
   • Acceda exactamente a lo que necesita cuando lo necesite.

2. Mejoras de seguridad

   El patrón de clave de valet, implementado mediante tokens de SAS, proporciona:

   • Acceso limitado por tiempo.
   • Permisos restringidos.
   • Eliminación del uso compartido o almacenamiento de credenciales permanentes.
   • Control de acceso específico.

3. Ventajas arquitectónicas

   El patrón asincrónico de solicitud-respuesta actúa como un asistente personal que:

   • Toma la solicitud.
   • Controla la tarea en segundo plano.
   • Le notifica cuando todo está listo.

Adopción de API optimizadas para mejorar el rendimiento

La adopción de estas API optimizadas simplifica el flujo de trabajo y mejora el rendimiento general en la administración de datos. Mediante el control de acceso seguro y mecanismos de recuperación eficientes, se obtienen mejores resultados con menos esfuerzo, lo que da lugar a una mejora de la eficacia operativa.

En conclusión, la nueva API asincrónica para acceder a los datos de facturación y conciliación a través de blobs de Azure es una herramienta eficaz. Ofrece acceso seguro y eficaz a los datos financieros, optimización de flujos de trabajo, reducción de cargas de servidor y mejora de los tiempos de procesamiento, todo ello con alta seguridad y cumplimiento.

Solo puede usar estas API para la nube global pública de MS Graph por ahora. Aún no están disponibles para Azure Government o Azure China.

Permitir que la aplicación acceda a los datos de facturación de asociados

Para permitir que la aplicación acceda a los datos de facturación de asociados, siga este vínculo y familiarícese con los conceptos básicos de autenticación y autorización de para Microsoft Graph. Este paso es fundamental, ya que garantiza que la aplicación pueda acceder de forma segura a los datos necesarios.

Asignar permiso PartnerBilling.Read.All

Asigne el permiso "PartnerBilling.Read.All" mediante Azure Portal o el Centro de administración de Microsoft Entra. Estos pasos garantizan que la aplicación tenga el acceso necesario a los datos de facturación del asociado.

1. Registre la aplicación en la página principal de Microsoft Entra en la sección Registros de aplicaciones.
2. Conceda el permiso necesario en la página Aplicación de Microsoft Entra. En la sección Permisos de API, seleccione Agregar un permiso y elija el ámbito PartnerBilling.Read.All.

Comprender las diferencias entre las versiones beta y ga

Si ha estado usando nuestra versión beta, es probable que encuentre la transición a la versión de disponibilidad general (GA) fluida e intuitiva. Para ayudarle a comprender las actualizaciones y mejoras, se recomienda comparar las versiones beta y GA. Comprender estas actualizaciones le ayudará a maximizar las nuevas características y mejoras disponibles en la versión de disponibilidad general.

Descripción y uso de los puntos de conexión de API

Para ayudarle a recuperar los nuevos artículos de línea de uso diario facturados diariamente de forma asincrónica, ofrecemos dos puntos de conexión clave de API. Siga esta guía simplificada para empezar a trabajar rápidamente.

Uso del punto de conexión de elemento de línea

En primer lugar, use esta API para capturar nuevos elementos de línea de uso clasificados diariamente por el comercio . Al realizar una solicitud, recibirá un estado HTTP 202 y un encabezado de ubicación con una dirección URL. Sondee esta dirección URL con regularidad hasta que obtenga un estado correcto y una dirección URL de manifiesto.

Uso del punto de conexión de estado de la operación

Siguiendo estos pasos, puede administrar eficazmente el proceso de conciliación de facturas.

Siga comprobando el estado de la operación llamando a esta API a intervalos regulares. Si los datos no están listos, la respuesta incluye un encabezado Retry-After que indica cuánto tiempo debe esperar antes de volver a intentarlo. Una vez completada la operación, recibirá un recurso de manifiesto con un vínculo de carpeta de almacenamiento para descargar los datos de uso. La respuesta segmenta los archivos para mejorar el rendimiento y permitir el paralelismo de E/S.

Revisión del diagrama de secuencia de datos de conciliación

Este es un diagrama de secuencia que muestra los pasos para descargar los datos de conciliación.

Siga la secuencia de acciones del usuario.

Estos son los pasos de secuencia de acciones del usuario para recuperar nuevo comercio elementos de línea de conciliación de uso clasificados diariamente:

• Enviar una solicitud
• Comprobar el estado de la solicitud
• Descarga de elementos de línea de conciliación desde Azure Blob Storage

Enviar una 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

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

Normalmente, la API responde con un estado HTTP 202. También puede encontrar otros estados en función de las solicitudes. Estos estados se enumeran en la sección Estados de respuesta de api estándar .

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

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 otros estados posibles según sus peticiones, consulte los estados.

Comprobación del estado de la solicitud

Para realizar un seguimiento del estado de una solicitud, asegúrese de recibir una respuesta HTTP 200 que es un código de estado estándar que indica "correcto" o "error" Si se ejecuta correctamente, encontrará la dirección URL del manifiesto en el atributo "resourceLocation". Este atributo proporciona un punto de conexión para acceder a la información necesaria.

Obtener el estado de la operación

Recupera el estado de una solicitud.

Solicitud a la API

OBTENER https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14

Parámetros de solicitud

Encabezado de solicitud

Para solicitar encabezados para la API, consulte Confiabilidad y soporte técnico.

Cuerpo de la solicitud

N/A.

Estado de respuesta

Además de los estados HTTP estándar enumerados en los estados de respuesta de la API estándar, la API también puede devolver el siguiente estado HTTP:

Carga de respuesta

La carga de respuesta de la API incluye los siguientes atributos:

Objeto de ubicación de recursos

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": "aaaabbbb-0000-cccc-1111-dddd2222eeee",

        "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"

            }

        \]

    }

}

Descarga de elementos de línea de conciliación desde Azure Blob Storage

En primer lugar, debe obtener el token de firma de acceso compartido (SAS) y la ubicación de Blob Storage (combine el directorio raíz y el nombre del blob). Puede encontrar estos detalles en las sasTokenpropiedades , rootDirectoryy blobs de la respuesta de la API de carga de manifiesto.

Para continuar, siga estos pasos:

1. Descargue el archivo de blob mediante el SDK o la herramienta de Azure Storage.
2. Descomprima el archivo, que está en formato JSONLines .

Descripción de los estados de respuesta de la API estándar

Es posible que reciba estos estados HTTP de la respuesta de la API:

Comparación de versiones beta y de disponibilidad general

Consulte la tabla de comparación siguiente para ver las diferencias entre las versiones beta y las versiones de disponibilidad general (GA). Si actualmente usa la versión beta, es probable que la transición a la versión de disponibilidad general sea sencilla y fácil.

Comparación de atributos básicos y completos de conciliación de uso con clasificación diaria

Consulte esta tabla para comparar los atributos devueltos por la API de conciliación de uso tanto facturada como no facturada para los conjuntos de atributos "completos" o "básicos". Para obtener más información sobre estos atributos y sus significados, consulte los campos de Archivo de conciliación de uso clasificado diariamente.

Código de ejemplo

Si necesita ayuda para migrar a esta API, consulte el vínculo que incluye código de ejemplo de C#.

Ejemplos de API del Centro de partners: obtener datos de conciliación de facturación.

Contenido relacionado

• Microsoft Graph API para exportar datos de facturación de asociados
• SDK o herramienta de Azure Storage