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, Azure Germania o Azure Cina 21Vianet).
Le API asincrone offrono un modo più rapido e gestibile per accedere ai dati di fatturazione e riconciliazione tramite BLOB di Azure. Con queste API, non è necessario mantenere aperta la connessione per ore o scorrere i batch di 2.000 voci.
Abbiamo ottimizzato le nuove API di riconciliazione dell'utilizzo giornaliero per il commercio usando la chiave di registrazione e i modelli asincroni di richiesta-risposta . Quando si usano queste API, si riceve un token che è possibile usare per accedere a tutti gli attributi o a un subset dei dati di riconciliazione dell'utilizzo valutato giornaliero.
Nota
Le nuove API non sono ospitate nell'host API del Centro per i partner. Al contrario, è possibile trovarli in MS Graph in Usare l'API Microsoft Graph per esportare i dati di fatturazione dei partner - Microsoft Graph v1.0 | Microsoft Learn. Per accedere a queste API, fare riferimento ai dettagli seguenti.
È possibile usare queste API solo per il cloud pubblico/globale MS Graph. Non sono ancora disponibili per Azure per enti pubblici, Azure Germania o Azure Cina 21Vianet.
Nota
Se si usa la versione beta, è possibile che non si notino modifiche significative nella versione disponibile a livello generale. È consigliabile confrontare le due versioni per comprendere le differenze e gli aggiornamenti.
Importante
Il nuovo utilizzo giornaliero del commercio non include gli addebiti per questi prodotti:
- Prenotazione di Azure
- Piano di risparmio di Azure
- Office
- Dynamics
- Microsoft Power Apps
- Software perpetuo
- Sottoscrizione software
- Prodotto SaaS non Microsoft
Panoramica delle API
Per recuperare in modo asincrono i nuovi elementi di utilizzo giornaliero per il commercio , usare due endpoint API. È necessario eseguire le operazioni seguenti:
Endpoint dell'elemento di riga di utilizzo
Usare questa API per recuperare voci di utilizzo fatturate o non fatturate giornaliere. Si ottiene uno stato HTTP 202 e un URL nell'intestazione del percorso. 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 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
| 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 qui. Facoltativo. |
| billingPeriod | Vero | String | Usare "current" o "last" (uguale a "previous" nelle API V1) per ottenere un utilizzo valutato giornaliero per il mese corrente o l'ultimo mese di calendario o il periodo di fatturazione. Obbligatorio. |
| currencyCode | Vero | String | Codice valuta di fatturazione partner. Obbligatorio. |
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
Quando si usa l'API, in genere restituisce uno stato HTTP 202. Per visualizzare altri possibili stati in base alle richieste, vedere 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. |
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
| Attributo | Richiesto | Type | Descrizione |
|---|---|---|---|
| invoiceId | Vero | String | Identificatore univoco per ogni fattura. Obbligatorio. |
| attributeSet | Falso | String | Scegliere "full" per tutti gli attributi o "basic" per un set limitato. Il valore predefinito è "full". Vedere l'elenco degli attributi qui. Facoltativo. |
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.
| 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, l'URL del manifesto viene fornito nell'attributo "resourceLocation".
Ottenere lo stato dell'operazione
Recupera lo stato di una richiesta.
Richiesta API
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
Per richiedere intestazioni per l'API, vedere Affidabilità e supporto.
Testo della richiesta
N/D.
Stato della risposta
Oltre agli stati HTTP standard, l'API può restituire lo stato HTTP seguente:
| Codice | Descrizione |
|---|---|
| 410 - Via | Il collegamento al manifesto è attivo solo per una durata specifica impostata dal server. Dopo questo intervallo di tempo, è necessario inviare una nuova richiesta per accedere al manifesto. |
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. È possibile includere gli attributi seguenti: message (Obbligatorio): descrizione dettagliata dell'errore. codice (obbligatorio): 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 elementi di riga o dimensioni del file nel codice, perché questi valori 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 | 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 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
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. Usare Archiviazione di Azure SDK/strumento per scaricare e decomprimere il file BLOB. È in 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 ricevere 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 | Timeout o scadenza del collegamento del manifesto. 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. |
Confrontare le versioni beta e ga
Vedere la tabella di confronto per comprendere le differenze tra le versioni beta e le versioni disponibili a livello generale. Se si usa la versione beta, passare alla versione ga dovrebbe essere semplice.
| Informazioni importanti | Beta | Generalmente disponibile |
|---|---|---|
| Endpoint host API | https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/ |
https://graph.microsoft.com/v1.0/reports/partners/billing/usage/ |
| Metodo HTTP | POST | POST |
| Endpoint dell'API di utilizzo valutato giornaliero non fatturato | https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/unbilledusage |
https://graph.microsoft.com/v1.0/reports/partners/billing/usage/unbilled/export |
| Parametri di input per l'API di utilizzo giornaliero non fatturata | Per specificare i parametri nella richiesta API, includerli nella stringa di query dell'URL della richiesta. Ad esempio, per specificare i parametri period e currencyCode, aggiungere ?period=current¤cyCode=usd all'URL della richiesta. |
Per fornire input, includere un oggetto JSON nel corpo della richiesta. L'oggetto JSON deve contenere le proprietà seguenti: * currencyCode: codice di valuta per la fattura. Ad esempio, USD. * billingPeriod: periodo di fatturazione per la fattura. Ad esempio, corrente. Ecco un esempio di oggetto JSON che include le proprietà currencyCode e billingPeriod: <br>{<br> "currencyCode": "USD",<br> "billingPeriod": "current"<br>} |
| Endpoint dell'API per l'utilizzo fatturato giornaliero | https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billedusage/invoices/{InvoiceId} |
https://graph.microsoft.com/v1.0/reports/partners/billing/usage/billed/export |
| Parametri di input per l'API di utilizzo valutato giornaliera fatturata | Per specificare i parametri nella richiesta API, includere invoiceId nell'URL della richiesta. Inoltre, è possibile includere un parametro di frammento facoltativo nella stringa di query per recuperare il set completo di attributi. Ad esempio, per recuperare il set completo di attributi, aggiungere ?fragment=full all'URL della richiesta. |
Per fornire input, includere un oggetto JSON nel corpo della richiesta. L'oggetto JSON deve contenere le proprietà seguenti: * invoiceId: ID della fattura. Ad esempio, G00012345. * attributeSet: set di attributi da includere nella risposta. Ad esempio, pieno. Di seguito è riportato un esempio di oggetto JSON che include le proprietà invoiceId e attributeSet: {<br> "invoiceId": "G00012345",<br> "attributeSet": "full"<br>} |
| Risorsa manifesto | Usare un metodo GET /manifests/{id} separato per recuperare la risorsa manifesto. | Usare il metodo GET /operations/{Id} che restituisce la risorsa manifesto correlata in resourceLocation eliminando la necessità di una chiamata separata al metodo GET /manifests/{id}. |
| Modifiche allo schema del manifesto | ||
| "id": non disponibile | "id": identificatore univoco per la risorsa manifesto. | |
| "version": Disponibile | "version": rinominato in "schemaversion". | |
| "dataFormat": disponibile | "dataFormat": disponibile. | |
| "utcCretedDateTime": disponibile | "utcCretedDateTime": rinominato in "createdDateTime". | |
| "eTag": disponibile | "eTag": disponibile. | |
| "partnerTenantId": disponibile | "partnerTenantId": disponibile | |
| "rootFolder": disponibile | "rootFolder": rinominato in "rootDirectory". | |
| "rootFolderSAS": disponibile | "rootFolderSAS": rinominato in "sasToken". Ora fornisce un token e non include più il percorso della directory radice. Per accedere alla directory, usare invece la proprietà "rootDirectory". | |
| "partitionType": disponibile | "partitionType": disponibile. | |
| "blobCount": disponibile | "blobCount": disponibile. | |
| "sizeInBytes": disponibile | "sizeInBytes": non disponibile. | |
| "BLOB": disponibile | "BLOB": disponibile. | |
| "oggetto BLOB": disponibile | "oggetto BLOB": disponibile. | |
| "name": Disponibile | "name": disponibile. | |
| "partitionValue": disponibile | "partitionValue": disponibile. |
Attributi dell'elemento della riga di riconciliazione dell'utilizzo valutato giornaliero
Per confrontare gli attributi restituiti dall'API di riconciliazione dell'utilizzo valutato giornaliero per i set di attributi "completi" o "di base", vedere le informazioni seguenti.
| Attributo | Completa | Di base |
|---|---|---|
| PartnerId | yes | yes |
| PartnerName | yes | yes |
| CustomerId | yes | yes |
| CustomerName | yes | Sì |
| CustomerDomainName | yes | no |
| CustomerCountry | yes | no |
| MpnId | yes | no |
| Tier2MpnId | yes | no |
| InvoiceNumber | yes | yes |
| ProductId | yes | yes |
| SkuId | yes | yes |
| AvailabilityId | yes | no |
| SkuName | yes | yes |
| ProductName | yes | no |
| PublisherName | yes | yes |
| PublisherId | yes | no |
| SubscriptionDescription | yes | no |
| SubscriptionId | yes | yes |
| ChargeStartDate | yes | yes |
| ChargeEndDate | yes | yes |
| UsageDate | yes | yes |
| MeterType | yes | no |
| MeterCategory | yes | no |
| ID contatore | yes | no |
| MeterSubCategory | yes | no |
| MeterName | yes | no |
| MeterRegion | yes | no |
| Unità | yes | yes |
| ResourceLocation | yes | no |
| ConsumedService | yes | no |
| ResourceGroup | yes | no |
| ResourceURI | yes | yes |
| ChargeType | yes | yes |
| UnitPrice | yes | yes |
| Quantità | yes | yes |
| UnitType | yes | no |
| BillingPreTaxTotal | yes | yes |
| BillingCurrency | yes | yes |
| PricingPreTaxTotal | yes | yes |
| PricingCurrency | yes | yes |
| ServiceInfo1 | yes | no |
| ServiceInfo2 | yes | no |
| Tag | yes | no |
| AdditionalInfo | yes | no |
| EffectiveUnitPrice | yes | yes |
| PCToBCExchangeRate | yes | yes |
| EntitlementId | yes | yes |
| EntitlementDescription | yes | no |
| PartnerEarnedCreditPercentage | yes | no |
| CreditPercentage | yes | yes |
| CreditType | yes | yes |
| BenefitOrderID | yes | yes |
| BenefitID | yes | no |
| BenefitType | yes | yes |
Importante
Prendere nota di queste modifiche quando si passa all'API v2 dalla versione 1.
Il nome di ogni attributo inizia in lettere maiuscole.
unitOfMeasure è ora Unità. Il significato e il valore dell'attributo sono gli stessi.
resellerMpnId è ora Tier2MpnId. Il significato e il valore dell'attributo sono gli stessi.
Il nome e il valore di rateOfPartnerEarnedCredit sono stati modificati in PartnerEarnedCreditPercentage. Il nuovo nome e il valore dell'attributo riflettono la percentuale anziché la frazione. Ad esempio, 0,15 è ora 15.
rateOfCredit è ora CreditPercentage. Il significato e il valore dell'attributo sono stati modificati. Ad esempio, 1.00 è ora 100.
Codice di esempio
Per altre informazioni, vedere Esempi di API del Centro per i partner: Ottenere i dati di riconciliazione della fatturazione.
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