API di riconciliazione dell'utilizzo con fatturazione e non fatturata giornaliera v2 (GA)

Si applica a: Centro per i partner (non disponibile in Azure per enti pubblici o Azure Cina 21Vianet).

La nuova API asincrona offre un modo più rapido ed efficiente per accedere ai dati di fatturazione e riconciliazione tramite BLOB di Azure. Anziché mantenere aperta una connessione per ore o elaborare batch di 2.000 voci, è ora possibile semplificare il flusso di lavoro.

Le nuove API di riconciliazione dell'utilizzo giornaliero quotidiano usano tecniche avanzate come la chiave di controllo e i modelli asincroni di richiesta-risposta . Queste API forniscono un token di firma di accesso condiviso (SAS) che è possibile usare per accedere a tutti gli attributi o a un subset dei dati di riconciliazione dell'utilizzo valutato giornaliero.

Le API usano tecniche ottimizzate per migliorare l'efficienza, in modo da ottenere risultati più veloci con meno sforzo. Adottare queste API per semplificare l'accesso ai dati e migliorare l'efficienza complessiva.

È possibile usare queste API solo per il cloud pubblico/globale MS Graph. Non sono ancora disponibili per Azure per enti pubblici o Azure Cina 21Vianet.

Panoramica delle API

Per aiutarti a recuperare in modo asincrono i nuovi elementi di utilizzo fatturati ogni giorno, offriamo due endpoint API chiave. Ecco una guida semplificata per iniziare:

Endpoint dell'elemento di riga di utilizzo

Prima di tutto, usare questa API per recuperare le voci di utilizzo giornaliere valutate per il commercio . Quando si effettua una richiesta, si riceve uno stato HTTP 202 e un'intestazione di posizione con un URL. Eseguire regolarmente il polling di questo URL fino a ottenere lo stato di esito positivo e l'URL del manifesto.

Endpoint dello stato dell'operazione

Continuare quindi a controllare lo stato dell'operazione chiamando questa API a intervalli regolari. Se i dati non sono pronti, la risposta include un'intestazione Retry-After che indica quanto tempo attendere prima di riprovare. Al termine dell'operazione, si riceve una risorsa manifesto con un collegamento alla cartella di archiviazione per scaricare i dati di utilizzo. La risposta segmenta i file per migliorare la velocità effettiva e consentire il parallelismo di I/O.

Seguendo questa procedura, è possibile gestire in modo efficiente il processo di riconciliazione della fattura.

Diagramma sequenza

Ecco un diagramma di sequenza che mostra i passaggi per scaricare i dati di riconciliazione.

Sequenza di azioni utente

Per recuperare i nuovi elementi di riconciliazione dell'utilizzo giornaliero, seguire questa procedura:

Passaggio 1: Inviare una richiesta

Inviare una richiesta POST all'endpoint API.

Ottenere voci di utilizzo giornaliero non fatturate

Ottieni nuove voci di utilizzo giornaliere non fatturate giornaliere per il mese corrente o l'ultimo mese di calendario o periodo di fatturazione.

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

}

Testo della richiesta

Intestazioni delle richieste

Per richiedere intestazioni per l'API, vedere Affidabilità e supporto.

Risposta dell'API

HTTP/1.1 202 Accepted  
Location: https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14

L'API risponde in genere con uno stato HTTP 202. È anche possibile riscontrare altri stati a seconda delle richieste. Questi stati sono elencati nella sezione Stati di risposta API Standard.

Ottenere le voci di utilizzo valutate giornaliere fatturate

Ottenere le nuove voci di utilizzo fatturate giornaliere fatturate per una fattura per il periodo di fatturazione chiuso.

Richiesta API

POST https://graph.microsoft.com/v1.0/reports/partners/billing/usage/billed/export

{  
"invoiceId": "G00012345",  
"attributeSet": "full"  
}

Parametri di query

N/D

Testo della richiesta

Intestazione della richiesta

Intestazioni di richiesta per l'API. Per altre informazioni, vedere l'affidabilità e il supporto.

Risposta dell'API

HTTP/1.1 202 Accettato
Posizione: https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14

Quando si usa l'API, in genere restituisce uno stato HTTP 202. Per altri possibili stati in base alle richieste, vedere Stati.

Passaggio 2: Controllare lo stato della richiesta

Per tenere traccia dello stato di una richiesta, assicurarsi di ricevere una risposta HTTP 200 che indica "succeeded" o "failed". In caso di esito positivo, l'URL del manifesto viene trovato nell'attributo "resourceLocation". Questo attributo fornisce un endpoint per l'accesso alle informazioni necessarie.

Ottenere lo stato dell'operazione

Recupera lo stato di una richiesta.

Richiesta API

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

Parametri della richiesta

Intestazione della richiesta

Per richiedere intestazioni per l'API, vedere Affidabilità e supporto.

Testo della richiesta

N/D.

Stato della risposta

Oltre agli stati HTTP standard elencati negli stati di risposta api standard, l'API può restituire anche lo stato HTTP seguente:

Payload della risposta

Il payload della risposta API include gli attributi seguenti:

Oggetto percorso risorsa

Richiesta API

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

Risposta dell'API

La risposta consiglia di attendere 10 secondi prima di riprovare durante l'elaborazione dei dati.

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

Richiesta API

(10 secondi dopo la richiesta precedente...)

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

Risposta dell'API

L'API restituisce lo stato "succeeded" e l'URI per "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"

            }

        \]

    }

}

Passaggio 3: Scaricare gli elementi della riga di riconciliazione dell'utilizzo valutato giornaliero dall'archiviazione BLOB di Azure

Prima di tutto, è necessario ottenere il token di firma di accesso condiviso e il percorso di archiviazione BLOB. Questi dettagli sono disponibili nelle proprietà "sasToken" e "rootDirectory" della risposta dell'API del payload del manifesto. Quindi, per scaricare e decomprimere il file BLOB, usare lo strumento/SDK Archiviazione di Azure. È nel formato JSONLines .

Stati di risposta API standard

È possibile ricevere questi stati HTTP dalla risposta dell'API:

Confrontare le versioni beta e ga

Vedere la tabella di confronto per visualizzare le differenze tra le versioni beta e le versioni disponibili a livello generale. Se attualmente si usa la versione beta, la transizione alla versione ga è semplice e semplice.

Attributi dell'elemento della riga di riconciliazione dell'utilizzo valutato giornaliero

Per confrontare gli attributi restituiti dall'API di riconciliazione fatturata per i set di attributi "full" o "basic", vedere la tabella seguente. Per altre informazioni su questi attributi, vedere questa documentazione.

Codice di esempio

Per usare questa API, vedere il collegamento seguente, che include il codice di esempio C#.

Esempi di API del Centro per i partner: ottenere i dati di riconciliazione della fatturazione.