API di riconciliazione fatturata v2 (GA)
Si applica a: Centro per i partner (non disponibile nel cloud sovrano)
L'API asincrona offre un modo più rapido e gestibile per accedere ai dati di fatturazione e riconciliazione tramite BLOB di Azure. Con questa API non è necessario mantenere aperta una connessione per ore o scorrere i batch di 2.000 voci alla volta.
Abbiamo ottimizzato la nuova API di riconciliazione delle fatture fatturate per il commercio usando la chiave di registrazione e i modelli asincroni di richiesta-risposta . Questa API fornisce un token di firma di accesso condiviso che è possibile usare per accedere a tutti gli attributi o a un subset dei dati di riconciliazione fatturati fatturati.
Nota
La nuova API non è ospitata nell'host API del Centro per i partner. Al contrario, è possibile trovarla in MS Graph in Usare l'API Microsoft Graph per esportare i dati di fatturazione dei partner - Microsoft Graph v1.0. Per accedere a questa API, fare riferimento ai dettagli seguenti.
È possibile usare questa API solo per il cloud pubblico/globale ms Graph ora. Non è ancora disponibile per Azure per enti pubblici, Azure Germania o Azure Cina 21Vianet.
Panoramica delle API
Per recuperare in modo asincrono i nuovi dati di riconciliazione delle fatture commerciali fatturati, usare due endpoint API. È necessario eseguire le operazioni seguenti:
Endpoint di riconciliazione fatturata
Usare questa API per recuperare le nuove voci di riconciliazione fatturate per il commercio . L'API restituisce uno stato HTTP 202 e un'intestazione di posizione contenente un URL. Eseguire il polling dell'URL a intervalli regolari fino a quando non viene visualizzato lo stato di esito positivo con un URL del manifesto.
Endpoint dello stato dell'operazione
Per ottenere uno stato di esito positivo, continuare a chiamare questa API a intervalli regolari. Se i dati non sono pronti, la risposta dell'API include un'intestazione Retry-After per indicare quanto tempo attendere prima di riprovare. Al termine dell'operazione, si ottiene una risorsa manifesto con una cartella di archiviazione in cui è possibile scaricare i dati di utilizzo. La risposta suddivide i file in parti più piccole per ottimizzare la velocità effettiva e il parallelismo di I/O.
Diagramma sequenza
Ecco un diagramma di sequenza che illustra i passaggi per scaricare nuovi dati di riconciliazione delle fatture commerciali.
Sequenza di azioni utente
Per recuperare i dati di riconciliazione fatturati, seguire questa procedura:
Passaggio 1: Inviare una richiesta
Inviare una richiesta POST all'endpoint API.
Ottenere le voci di riconciliazione fatturate
Richiesta API
POST https://graph.microsoft.com/v1.0/reports/partners/billing/reconciliation/billed/export
Accept: application/json
Content-Type: application/json
{
"invoiceId": "G016907411",
"attributeSet": "basic"
}
Parametri di query
N/D
Testo della richiesta
| Attributo | Richiesto | Type | Descrizione |
|---|---|---|---|
| attributeSet | Falso | String | Scegliere "full" per tutti gli attributi o "basic" per un set limitato. Il valore predefinito è "full". Vedere l'elenco degli attributi in questo articolo. Facoltativo. |
| invoiceId | Vero | String | Identificatore univoco per ogni fattura. Obbligatorio. |
Intestazioni delle richieste
Intestazioni di richiesta per l'API usando i passaggi elencati in Procedure consigliate per l'uso di Microsoft Graph.
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. Altri possibili stati, in base alle richieste, sono elencati negli stati di risposta dell'API Standard in questo articolo.
| Codice | Descrizione |
|---|---|
| 202 – Accettato | La richiesta è stata accettata. Per controllare lo stato della richiesta, eseguire una query sull'URL fornito nell'intestazione del percorso. |
Passaggio 2: Controllare lo stato della richiesta
Per controllare lo stato di una richiesta, attendere una risposta HTTP 200 con lo stato "succeeded" o "failed". Se la richiesta ha esito positivo, si ottiene l'URL del manifesto nell'attributo "resourceLocation".
Ottenere lo stato dell'operazione
Recupera lo stato di una richiesta.
Richiesta API
GET <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>
Parametri della richiesta
| Nome | Includi in | Richiesto | Type | Descrizione |
|---|---|---|---|---|
| operationId | URI della richiesta | Vero | String | ID univoco per controllare lo stato della richiesta. Obbligatorio. |
Intestazione della richiesta
Intestazioni di richiesta per l'API usando i passaggi elencati in Procedure consigliate per l'uso di Microsoft Graph.
Testo della richiesta
N/D.
Stato della risposta
Oltre agli stati HTTP standard elencati in Stati di risposta API Standard in questo articolo, l'API può restituire lo stato HTTP seguente:
| Codice | Descrizione |
|---|---|
| 410 - Via | Il collegamento al manifesto scade dopo un periodo di tempo impostato. Per ottenere di nuovo il collegamento al manifesto, inviare una nuova richiesta. |
Payload della risposta
Il payload della risposta API include gli attributi seguenti:
| Attributo | Obbligatorio | Descrizione |
|---|---|---|
| id | Vero | ID univoco per ogni risposta Obbligatorio. |
| stato | Vero | Valori e azioni: obbligatorio. notstarted: attendere l'ora specificata nell'intestazione "Retry-After", quindi effettuare un'altra chiamata per controllare lo stato. running: attendere il tempo specificato nell'intestazione "Retry-After", quindi effettuare un'altra chiamata per controllare lo stato. succeeded: i dati sono pronti. Recuperare il payload del manifesto usando l'URI specificato in resourceLocation. failed: l'operazione non è riuscita in modo permanente. Riavviarlo. |
| createdDateTime | Vero | Ora in cui è stata effettuata la richiesta. Obbligatorio. |
| lastActionDateTime | Vero | Ora dell'ultima modifica dello stato. Obbligatorio. |
| resourceLocation | Falso | URI per il payload del manifesto. Facoltativo. |
| Errore | Falso | Se l'operazione non riesce, i dettagli dell'errore vengono forniti in formato JSON. Facoltativo. Sono inclusi gli attributi seguenti: message: descrizione dettagliata dell'errore. code: tipo di errore che si è verificato. |
Oggetto percorso risorsa
| Attributo | Descrizione |
|---|---|
| id | Identificatore univoco per il manifesto. |
| schemaVersion | Versione dello schema del manifesto. |
| dataFormat | Formato del file di dati di fatturazione. compressedJSON: formato di dati in cui ogni BLOB è un file compresso che contiene dati in formato righe JSON . Per recuperare i dati da ogni BLOB, decomprimerli. |
| createdDateTime | Data e ora di creazione del file manifesto. |
| eTag | Versione dei dati del manifesto. Una modifica nelle informazioni di fatturazione genera un nuovo valore. |
| partnerTenantId | ID del tenant del partner. |
| rootDirectory | Directory radice del file. |
| sasToken | Token di firma di accesso condiviso (firma di accesso condiviso) che consente di leggere tutti i file nella directory. |
| partitionType | Divide i dati in più BLOB in base all'attributo partitionValue . Il sistema suddivide le partizioni che superano il numero supportato. Per impostazione predefinita, i dati vengono partizionati in base al numero di elementi di riga nel file. Non impostare un numero fisso di voci o dimensioni del file nel codice, perché questi valori possono cambiare. |
| blobCount | Numero totale di file per questo ID tenant partner. |
| blob | Matrice JSON di oggetti "BLOB" che contengono i dettagli del file per l'ID tenant del partner. |
| oggetto BLOB | Oggetto contenente i dettagli seguenti: name: nome del BLOB. partitionValue: partizione che contiene il file. La partizione di grandi dimensioni è suddivisa in più file, con ogni file contenente lo stesso "partitionValue". |
| name | Nome del BLOB. |
| partitionValue | Partizione che contiene il file. La partizione di grandi dimensioni è suddivisa in più file, con ogni file contenente lo stesso "partitionValue". |
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 quando i dati sono ancora in fase di elaborazione.
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 i dati di riconciliazione fatturati dall'archivio BLOB di Azure
Ottenere il token di firma di accesso condiviso e il percorso di archiviazione BLOB dalle proprietà "sasToken" e "rootDirectory" la risposta dell'API del payload del manifesto. Archiviazione di Azure SDK/strumento per scaricare e decomprimere il file BLOB. È nel formato JSONLines .
Suggerimento
Vedere il codice di esempio per scaricare e decomprimere il file BLOB di Azure nel database locale.
Stati di risposta API standard
È possibile ottenere questi stati HTTP dalla risposta dell'API:
| Codice | Descrizione |
|---|---|
| 400 - Richiesta non valida | La richiesta è mancante o contiene dati non corretti. Controllare il corpo della risposta per i dettagli dell'errore. |
| 401 - Non autorizzato | Il chiamante non è autenticato ed è necessario eseguire l'autenticazione con il servizio API partner prima di effettuare la prima chiamata. |
| 403 - Accesso negato | Non si dispone dell'autorizzazione necessaria per effettuare la richiesta. |
| 404 - Non trovato | Le risorse richieste non sono disponibili con i parametri di input forniti. |
| 410 - Via | Il collegamento al manifesto non è più valido o attivo. Inviare una nuova richiesta. |
| 500 - Errore interno del server | L'API o una delle relative dipendenze non può soddisfare la richiesta al momento. Riprovare. |
| 5000 - Nessun dato disponibile | Il sistema non dispone di dati per i parametri di input forniti. |
Attributi dei dati di riconciliazione delle fatture fatturati
Per confrontare gli attributi restituiti dall'API di riconciliazione fatturata per i set di attributi "full" o "basic", vedere la tabella seguente.
| Attributo | Completa | Di base |
|---|---|---|
| PartnerId | yes | yes |
| CustomerId | yes | yes |
| CustomerName | yes | yes |
| CustomerDomainName | yes | no |
| CustomerCountry | yes | no |
| InvoiceNumber | yes | yes |
| MpnId | yes | no |
| Tier2MpnId | yes | yes |
| OrderId | yes | yes |
| DataOrdine | yes | yes |
| ProductId | yes | yes |
| SkuId | yes | yes |
| AvailabilityId | yes | yes |
| SkuName | yes | no |
| ProductName | yes | yes |
| ChargeType | yes | yes |
| UnitPrice | yes | yes |
| Quantità | yes | no |
| Subtotale | yes | yes |
| TaxTotal | yes | yes |
| Totale | yes | yes |
| Valuta | yes | yes |
| PriceAdjustmentDescription | yes | yes |
| PublisherName | yes | yes |
| PublisherId | yes | no |
| SubscriptionDescription | yes | no |
| SubscriptionId | yes | yes |
| ChargeStartDate | yes | yes |
| ChargeEndDate | yes | yes |
| TermAndBillingCycle | yes | yes |
| EffectiveUnitPrice | yes | yes |
| UnitType | yes | no |
| AlternateId | yes | no |
| BillableQuantity | yes | yes |
| BillingFrequency | yes | no |
| PricingCurrency | yes | yes |
| PCToBCExchangeRate | yes | yes |
| PCToBCExchangeRateDate | yes | no |
| MeterDescription | yes | no |
| ReservationOrderId | yes | yes |
| CreditReasonCode | yes | yes |
| SubscriptionStartDate | yes | yes |
| SubscriptionEndDate | yes | yes |
| ReferenceId | yes | yes |
| ProductQualifiers | yes | no |
| PromotionId | yes | yes |
| ProductCategory | yes | yes |
Codice di esempio
Per indicazioni sull'uso dell'API, vedere il collegamento seguente che include codice di esempio in C#.
Commenti e suggerimenti
Presto disponibile: Nel corso del 2024 verranno gradualmente disattivati i problemi di GitHub come meccanismo di feedback per il contenuto e ciò verrà sostituito con un nuovo sistema di feedback. Per altre informazioni, vedere https://aka.ms/ContentUserFeedback.
Invia e visualizza il feedback per