API di riconciliazione fatturata v2 (GA)
Si applica a: Centro per i partner (non disponibile nel cloud sovrano)
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, ridurre il carico del server e migliorare i tempi di elaborazione dei dati.
La nuova API di riconciliazione delle fatture fatturate per il commercio usa tecniche avanzate come la chiave di registrazione e i modelli asincroni di richiesta-risposta . Il modello di chiave di controllo supporta l'accesso sicuro alle risorse senza condividere le credenziali, mentre il modello asincrono request-reply consente una comunicazione efficiente tra i sistemi.
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. Questo token migliora la sicurezza concedendo l'accesso a tempo limitato e offre flessibilità nella gestione delle autorizzazioni di accesso ai dati.
Adottando le API ottimizzate, è possibile ottenere risultati più rapidi con meno sforzo, semplificare l'accesso ai dati e migliorare l'efficienza complessiva. Adottare questi strumenti per semplificare il flusso di lavoro e gestire le autorizzazioni in modo più efficace.
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.
Consentire all'app di accedere in modo sicuro ai dati di fatturazione dei partner
Per consentire all'app di accedere ai dati di fatturazione dei partner, seguire questo collegamento e acquisire familiarità con le nozioni di base sull'autenticazione e sull'autorizzazione per Microsoft Graph. Questo passaggio è fondamentale perché garantisce che l'app possa accedere in modo sicuro ai dati necessari.
Registrare l'app e assegnare l'autorizzazione PartnerBilling.Read.All
È possibile assegnare l'autorizzazione "PartnerBilling.Read.All" usando il portale di Azure o l'interfaccia di amministrazione di Microsoft Entra. Completando questi passaggi, si garantisce che l'app abbia l'accesso necessario ai dati di fatturazione dei partner. Ecco come fare:
- Registrare l'app nella home page di Microsoft Entra nella sezione Registrazioni app.
- Concedere l'autorizzazione necessaria passando alla pagina dell'app Microsoft Entra. Nella sezione Autorizzazioni API selezionare Aggiungi un'autorizzazione e scegliere l'ambito PartnerBilling.Read.All.
Informazioni sugli endpoint principali dell'API
Per aiutarti a recuperare in modo asincrono le voci di riconciliazione delle fatture commerciali fatturate in modo asincrono, offriamo due endpoint API chiave. Questi endpoint consentono di gestire in modo efficiente il processo di riconciliazione delle fatture. Seguire questa guida semplificata per iniziare rapidamente.
Usare l'endpoint di riconciliazione della fattura fatturata
Prima di tutto, usare questa API per recuperare le nuove voci di riconciliazione fatturate 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.
Usare l'endpoint di 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.
Esaminare il diagramma di sequenza
Ecco un diagramma di sequenza che illustra i passaggi per scaricare nuovi dati di riconciliazione delle fatture commerciali.
Seguire la sequenza di azioni dell'utente per recuperare i dati di riconciliazione delle fatture emesse
Ecco la sequenza di azioni dell'utente per recuperare i dati di riconciliazione delle fatture:
- Inviare una richiesta POST
- Controllare lo stato della richiesta
- Scarica le voci di riconciliazione fatturate dall'archiviazione oggetti blob di Azure
Inviare una richiesta POST
Inviare una richiesta POST all'endpoint API.
Ottenere le voci di riconciliazione fatturate
Ottieni le voci delle righe di riconciliazione della fattura.
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. Se non specificato, "full" è il valore predefinito. Controlla l'elenco degli attributi in questa sezione. 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. Seguendo queste linee guida, si garantisce affidabilità e supporto per l'applicazione. L'attenzione ai dettagli in questo passaggio è fondamentale per un'integrazione senza interruzioni e prestazioni ottimali.
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 tue richieste. Questi stati sono elencati nella sezione Stati di risposta API Standard.
| Codice | Descrizione |
|---|---|
| 202 – Accettato | La richiesta è stata accettata. Per controllare lo stato della richiesta, eseguire una query sull'URL fornito nell'intestazione del percorso. |
Controllare lo stato della richiesta
Per tenere traccia dello stato di una richiesta, assicurarsi di ricevere una risposta HTTP 200, che è un codice di stato standard che indica "riuscito" o "fallito". In caso di esito positivo, l'URL del manifest si trova 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
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 delle richiesta | Vero | String | Identificatore 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. Seguendo queste linee guida, si garantisce affidabilità e supporto per l'applicazione. L'attenzione ai dettagli in questo passaggio è fondamentale per un'integrazione senza interruzioni e prestazioni ottimali.
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:
| 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 | Richiesto | Descrizione |
|---|---|---|
| id | Vero | Identificatore univoco per ogni risposta Obbligatorio. |
| stato | Vero |
Valori e azioni: obbligatorio. non avviato: attendere la durata specificata nell'intestazione "Retry-After", quindi effettuare una nuova chiamata per controllare lo stato. attivo: attendere la durata specificata 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 | Informazioni dettagliate su eventuali errori, forniti in formato JSON. Facoltativo. Attributi inclusi: message: Descrizione dell'errore. code: tipo di errore. |
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. Viene generato un nuovo valore ogni volta che viene apportata una modifica alle informazioni di fatturazione. |
| partnerTenantId | ID Microsoft Entra 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. Evitare di codificare il numero di elementi o le dimensioni dei file, poiché potrebbero 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 e partitionValue |
| name | Nome del BLOB. |
| partitionValue | Partizione che contiene il file. La partizione di grandi dimensioni è suddivisa in più file in base a determinati criteri, ad esempio le dimensioni del file o il numero di record, 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": "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"
}
\]
}
}
Scaricare le voci di riconciliazione della fatturazione dall'archivio BLOB di Azure
In primo luogo, è necessario ottenere il token SAS (firma di accesso condiviso) e la posizione dell'archiviazione BLOB. È possibile trovare questi dettagli nelle proprietà sasToken e rootDirectory della risposta dell'API del payload del manifest. Quindi, per scaricare e decomprimere il file blob, usare il Azure Storage SDK/strumento. È nel formato JSONLines .
Suggerimento
Assicurati di consultare il codice di esempio . Illustra come scaricare e decomprimere il file BLOB di Azure nel database locale.
Stati di risposta API standard
È possibile ottenere gli stati HTTP seguenti 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 | L'autenticazione è necessaria prima di effettuare la prima chiamata. Eseguire l'autenticazione con il servizio API partner. |
| 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 le relative dipendenze non possono soddisfare la richiesta al momento. Riprovare. |
| 5000 - Nessun dato disponibile | Il sistema non dispone di dati per i parametri di input forniti. |
Attributi della voce di riconciliazione fatturata
Per confrontare gli attributi restituiti dall'API di riconciliazione delle fatture per i set di attributi "full" o "basic", fare riferimento a questa tabella. Per altre informazioni su questi attributi e sui relativi significati, vedere Usare il file di riconciliazione.
| Attributo | Completo | 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 |
Importante
Prendere nota di queste modifiche quando si passa dall'API v1 alla versione 2.
- Ogni nome di attributo inizia ora con un lettera maiuscola per mantenere la coerenza con il file e migliorare la leggibilità.
Ottenere il codice di esempio dell'API
Per usare questa API, vedere il collegamento seguente, che include il codice di esempio C#.
esempi di API per ottenere i dati di riconciliazione della fatturazione dal Centro per i partner.