Nuova API di utilizzo giornaliero per il commercio v2 (beta)
Si applica a: Centro per i partner | Centro per i partner gestito da 21Vianet | Centro per i partner per Microsoft Cloud per il governo degli Stati Uniti
Usare queste API per ottenere nuovi dati di utilizzo fatturati e non fatturati ogni giorno in modo asincrono.
Nota
Questa API sarà deprecata. Usare invece la versione ga. Per altre informazioni, vedere i dettagli seguenti.
È possibile usare questa API solo per l'utilizzo giornaliero fatturato valutato fino al 30 settembre 2024. Vedere i dettagli per selezionare la versione corretta dell'API e pianificare in anticipo.
- Passare alla versione 2 disponibile a livello generale il prima possibile. Fino ad allora, usare questa API per ottenere voci di utilizzo valutate giornaliere per le nuove fatture commerciali per i periodi di fatturazione di settembre 2022.
- Usare solo l'API v2 GA dal 1° ottobre 2024 per ottenere voci di utilizzo giornaliere per le nuove fatture commerciali per i periodi di fatturazione di settembre 2022.
È possibile usare questa API solo per l'utilizzo giornaliero non fatturato fino al 30 settembre 2024. Vedere i dettagli per selezionare la versione corretta dell'API e pianificare in anticipo.
- Passare alla versione 2 disponibile a livello generale il prima possibile. Fino a allora usare questa API per ottenere nuove voci di utilizzo giornaliere non fatturate giornaliere per i periodi di fatturazione correnti e precedenti.
- Usare solo l'API v2 GA dal 1° ottobre 2024 per ottenere nuove voci di utilizzo giornaliere non fatturate giornaliere per i periodi di fatturazione correnti e precedenti.
Per accedere alle nuove API ga v2, vedere questo collegamento:
API di riconciliazione dell'utilizzo con fatturazione e non fatturata giornaliera v2 (GA)
Nota
È possibile recuperare gli elementi di riga di utilizzo non fatturati giornalieri tramite l'API o il portale del Centro per i partner. La disponibilità dei dati può richiedere fino a 24 ore. Tuttavia, potrebbero verificarsi ulteriori ritardi a seconda della posizione e quando i contatori segnalano l'utilizzo.
In alcuni casi, è possibile che non vengano visualizzati i dati di utilizzo non fatturati più recenti fino a quando non vengono recapitati i dati di utilizzo fatturati per il mese precedente. Questa operazione viene eseguita per garantire che i dati di utilizzo fatturati vengano recapitati entro il tempo concordato. Dopo aver ricevuto i dati di utilizzo fatturati, dovrebbe essere possibile recuperare tutti i dati di utilizzo non fatturati aggiornati dall'inizio del mese.
Importante
I dati di utilizzo valutati giornalieri non includono 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
L'API asincrona è un nuovo metodo per accedere rapidamente ai dati di fatturazione e riconciliazione in blocchi gestibili. Elimina la necessità di mantenere una connessione aperta per ore e scorrere in modo iterativo milioni di transazioni.
Sono stati usati modelli di richiesta/risposta asincrona per ottimizzare le API di fatturazione e riconciliazione per fornire i risultati in modo asincrono. Le risposte API forniranno un token per accedere ai dati di riconciliazione con tutti gli attributi o un subset.
È possibile scaricare i dati di utilizzo in modo asincrono usando tre nuovi passaggi (endpoint API). Altre informazioni sono disponibili in:
Endpoint dell'elemento di riga di utilizzo
Usare questa API per accedere alle voci di utilizzo fatturate o non fatturate. Restituisce uno stato HTTP 202 e un'intestazione di posizione con l'URL, che è necessario eseguire il polling a intervalli regolari fino a quando non si riceve uno stato di esito positivo con un URL manifesto.
Endpoint dello stato dell'operazione
Finché non si riceve lo stato di esito positivo, continuare a eseguire il polling di questa API a intervalli regolari. Se i dati richiesti non sono disponibili, la risposta dell'API includerà un'intestazione Retry-After che indica per quanto tempo è necessario attendere prima di inviare un'altra richiesta.
Endpoint del manifesto
Questo endpoint fornisce una cartella di archiviazione da cui è possibile scaricare i dati di fatturazione effettivi. La risposta suddivide o partiziona i file per ottimizzare la velocità effettiva e il parallelismo di I/O.
Diagramma sequenza
Il diagramma seguente illustra i passaggi necessari per scaricare i dati di riconciliazione.
Sequenza di azioni utente
Seguire questa procedura per recuperare i dati di riconciliazione.
Passaggio 1: Inviare una richiesta
Inviare una richiesta POST all'endpoint API.
Ottenere voci di utilizzo non fatturate
Ottiene le voci di utilizzo non fatturate per il mese corrente o dell'ultimo mese di calendario.
Richiesta API
POST https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/unbilledusage?fragment={fragment}&period={period}?currencyCode={currencyCode}
Parametri della richiesta
| Nome | In | Obbligatorio | Type | Descrizione |
|---|---|---|---|---|
| fragment | Query | Falso | String | Scegliere "full" per una risposta completa o "basic" per un subset di attributi. Il valore predefinito è "full". Vedere l'elenco degli attributi in questo articolo. |
| period | Query | Vero | String | Usare "current" o "last" per ottenere l'utilizzo per il mese corrente o dell'ultimo calendario. Il valore "last" è uguale a "precedente" nelle API V1 esistenti. |
| currencyCode | Query | Vero | String | Codice valuta di fatturazione partner. |
Parametri della richiesta deprecati
La versione più recente dell'API non richiede i parametri URI seguenti:
| Nome | Descrizione |
|---|---|
| Provider | N/D. Restituisce tutto l'utilizzo del piano di Azure ed è equivalente alla "onetime" delle API V1 esistenti. |
| hasPartnerEarnedCredit | N/D. (restituisce tutti i dati, indipendentemente dalla pec). |
| Dimensione | N/D. |
| Contropartita | N/D. |
| seekOperation | N/D. |
Intestazione della richiesta
Vedere l'elenco delle intestazioni di richiesta per l'API in questo articolo.
Testo della richiesta
N/D.
Risposta dell'API
HTTP/1.1 202 Accepted Operation-Location: https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingoperations/811bb8f0-8aca-4807-897c-c15ce50820d6
L'API restituisce lo stato HTTP 202. In base alla richiesta, l'API può restituire altri stati standard.
| Nome | Descrizione |
|---|---|
| 202 - Accettato | La richiesta viene accettata. Eseguire una query sull'URL dell'intestazione operation-location per lo stato della richiesta. |
Ottenere voci di utilizzo fatturate
Ottiene le voci di utilizzo valutate per il periodo di fatturazione chiuso.
Richiesta API
POST https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billedusage/invoices/{invoiceId}?fragment={fragment}
Parametri della richiesta
| Nome | In | Obbligatorio | Type | Descrizione |
|---|---|---|---|---|
| invoiceId | Percorso | Vero | String | Numero di fattura del Centro per i partner. |
| Frammento | Query | Falso | String | Scegliere "full" per una risposta completa o "basic" per un subset di attributi. Il valore predefinito è "full". Vedere l'elenco degli attributi in questo articolo. |
Parametri della richiesta deprecati
La versione più recente dell'API non richiede i parametri URI seguenti:
| Nome | Descrizione |
|---|---|
| Provider | N/D. Restituisce tutto l'utilizzo del piano di Azure ed è equivalente alla "onetime" delle API V1 esistenti. |
| hasPartnerEarnedCredit | N/D. (restituisce tutti i dati, indipendentemente dalla pec). |
| Dimensione | N/D. |
| Contropartita | N/D. |
| seekOperation | N/D. |
Intestazione della richiesta
Vedere l'elenco delle intestazioni di richiesta per l'API in questo articolo.
Testo della richiesta
N/D.
Risposta dell'API
HTTP/1.1 202 Accepted Operation-Location: https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingoperations/06d01983-07bf-4448-83b4-1e83ab1d4640
L'API restituisce "HTTP 202 Accepted". In base all'API della richiesta, è possibile restituire altri stati standard.
| Nome | Descrizione |
|---|---|
| 202 - Accettato | La richiesta viene accettata. Controllare lo stato della richiesta eseguendo il polling dell'URL dell'intestazione operation-location. |
Passaggio 2: Controllare lo stato della richiesta
Attendere un HTTP 200 con stato del terminale riuscito o non riuscito. L'URL del manifesto sarà "resourceLocation" nello stato di esito positivo.
Ottenere lo stato dell'operazione
Ottiene lo stato di una richiesta di dati di riconciliazione.
Richiesta API
GET https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingoperations/06d01983-07bf-4448-83b4-1e63ab1d3640
Parametri della richiesta
| Nome | In | Obbligatorio | Type | Descrizione |
|---|---|---|---|---|
| operationId | Percorso | Vero | String | ID operazione. |
Intestazione della richiesta
Vedere l'elenco delle intestazioni di richiesta per l'API in questo articolo.
Testo della richiesta
N/D.
Stato della risposta
Oltre allo stato HTTP standard in questo articolo, l'API può restituire lo stato HTTP seguente:
| Nome | Descrizione |
|---|---|
| 410 - Non disponibile | Ogni collegamento di operazione è attivo per una quantità specificata di tempo controllato dal server. Al termine del tempo, il client deve inviare una nuova richiesta. |
Payload della risposta
Il payload della risposta API restituisce gli attributi seguenti:
| Nome | Facoltativo | Descrizione |
|---|---|---|
| createdDateTime | false | Tempo richiesta. |
| lastActionDateTime | false | Ora di modifica dello stato. |
| resourceLocation | true | URI del payload del manifesto. |
| stato | false | Valori e azioni possibili. |
| Valore | Azione client |
|---|---|
| notstarted | Effettuare un'altra chiamata per controllare lo stato dopo l'attesa del tempo specificato nell'intestazione "Retry-After". |
| in esecuzione | Effettuare un'altra chiamata per controllare lo stato dopo l'attesa del tempo specificato nell'intestazione "Retry-After". |
| succeeded | Stato finale dell'operazione, che indica che i dati sono pronti. Recuperare il payload del manifesto usando l'URI specificato in resourceLocation. |
| failed | Stato terminale, che indica un errore permanente. Riavviare l'operazione. |
Per l'attributo error:
| Nome | Facoltativo | Descrizione |
|---|---|---|
| Errore | true | Dettagli dell'errore forniti in formato JSON se lo stato dell'operazione non è riuscito. |
| Nome | Facoltativo | Descrizione |
|---|---|---|
| messaggio | false | Descrive l'errore in dettaglio |
| codice | false | Indica il tipo di errore che si è verificato |
Richiesta API
GET https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingoperations/06d01983-07bf-4447-83b4-1e83ab1d3640
Risposta dell'API
La risposta suggerisce l'attesa di 10 secondi prima di riprovare durante l'elaborazione dei dati.
HTTP/1.1 200 OK
Retry-After: 10
{
"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://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingoperations/06d01983-07bf-4447-83b4-1e83ab1d3640
Risposta dell'API
L'API restituisce lo stato "succeeded" e l'URI "resourceLocation".
HTTP/1.1 200 OK
Content-Type: application/json
{
"createdDateTime": "2022-06-1T10-01-03.4Z",
"lastActionDateTime": "2022-06-1T10-01-13Z",
"status": "succeeded",
"resourceLocation": "https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingmanifests/e03e1882-ff59-4c09-882f-74e60b4d7743"
}
Passaggio 3: Ottenere il payload del manifesto
Il chiamante effettua una richiesta GET all'URL del manifesto per altre informazioni sulla posizione in cui vengono archiviati i dati di riconciliazione nei BLOB di Azure.
Recupero del manifesto
Recupera il manifesto con informazioni sulla posizione di archiviazione di Azure dei dati di riconciliazione.
Richiesta API
GET https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingmanifests/{manifestId}
Parametri della richiesta
| Nome | In | Obbligatorio | Type | Descrizione |
|---|---|---|---|---|
| manifestId | Percorso | Vero | String | ID manifesto. |
Intestazione della richiesta
Vedere l'[elenco di intestazioni di richiesta per l'API] in questo articolo.
Testo della richiesta
N/D.
Stato della risposta
Oltre allo stato HTTP standard, l'API può restituire il seguente stato HTTP:
| Nome | Descrizione |
|---|---|
| 410 - Non disponibile | Ogni collegamento al manifesto è attivo per una quantità specificata di tempo controllato dal server. Al termine del tempo, il client deve inviare una nuova richiesta. |
Payload della risposta
La risposta dell'API restituisce gli attributi seguenti:
| Nome | Descrizione |
|---|---|
| Versione | Versione dello schema del manifesto. |
| Dataformat | Formato del file di dati di fatturazione. Valori possibili compressiJSONLines: ogni BLOB è un file compresso e i dati nel file sono in formato di righe JSON. Decomprimere il file per accedere ai dati. |
| utcCreatedDateTime | Ora di creazione del file manifesto. |
| eTag | Versione dei dati del manifesto. Una modifica nelle informazioni di fatturazione genera un nuovo valore eTag. |
| partnerTenantId | ID tenant partner. |
| rootFolder | Directory radice del file. |
| rootFolderSAS | Token di firma di accesso condiviso per l'accesso al file. |
| partitionType | Questa proprietà divide i dati. Se una determinata partizione ha più del numero supportato, i dati verranno suddivisi in più file corrispondenti a "partitionValue". I dati vengono partizionati in base al numero di voci nel file per impostazione predefinita. Non impostare un numero fisso di elementi di riga o dimensioni del file nel codice perché potrebbero cambiare. |
| blobCount | Numero totale di file per questo ID tenant partner. |
| sizeInBytes | Byte totali in tutti i file. |
| blob | Matrice JSON di oggetti "BLOB" con i dettagli di tutti i file per l'ID tenant partner. |
| Oggetto BLOB | |
| Nome | Nome del BLOB. |
| sizeInBytes | Dimensioni del BLOB in byte. |
| partitionValue | Partizione che contiene il file. Una partizione di grandi dimensioni verrà suddivisa in più file, ognuno con lo stesso "partitionValue". |
Payload del manifesto di esempio
{
"version": "1",
"dataFormat": "compressedJSONLines",
"utcCretedDateTime": "2022-04-29T22:40:57.1853571Z",
"eTag": "0x5B168C7B6E589D2",
"partnerTenantId": "14f593ad-1edc-474d-aaa0-83abbf9638da",
"rootFolder": "https://{billing.blob.core.windows.net}/{folder_path}",
"rootFolderSAS": "\*\*\*",
"partitionType": "ItemCount",
"blobCount": 3,
"sizeInBytes": 2000,
"blobs": [
{
"name": "{blobName1.json.gz}",
"sizeinBytes": 500,
"partitionValue": "1"
},
{
"name": "{blobName2.json.gz}",
"sizeinBytes": 1000,
"partitionValue": "2"
},
{
"name": "{blobName3.json.gz}",
"sizeinBytes": 500,
"partitionValue": "3"
}
]
}
Passaggio 4: Scaricare i dati di riconciliazione dell'utilizzo dalla posizione di archiviazione
Ottenere il token di firma di accesso condiviso e il percorso di archiviazione BLOB dalle proprietà "rootFolderSAS" e "rootFolder" la risposta dell'API del payload del manifesto. Usare Archiviazione di Azure SDK/strumento per scaricare e decomprimere il file BLOB. È in formato di righe JSON .
Intestazioni di richiesta API standard
Tutte le API accettano le intestazioni seguenti:
| Nome | Obbligatorio | Type | Descrizione |
|---|---|---|---|
| Autorizzazione | Vero | String | Token di connessione dell'autorizzazione. |
| ms-correlationid | Falso | String | Strumento di rilevamento delle richieste interno. Ogni richiesta genera un nuovo tracker (GUID). |
| ms-cv | Falso | String | Strumento di rilevamento delle richieste interno. |
| ms-requestid | Falso | String | ID di idempotenza della richiesta. |
Stati di risposta API standard
Di seguito sono riportati gli stati HTTP della risposta dell'API:
| Nome | Descrizione |
|---|---|
| 400 Richiesta non valida | Dati mancanti o non corretti. I dettagli dell'errore sono inclusi nel corpo della risposta. |
| 401 - Non autorizzato | Il chiamante non è autenticato e deve eseguire l'autenticazione con il servizio API partner prima di effettuare la prima chiamata. |
| 403 Negato | Il chiamante non è autorizzato a effettuare la richiesta. |
| 500 Errore interno del server | L'API o una delle relative dipendenze non è in grado di soddisfare la richiesta. Riprova più tardi. |
| 404 Not Found | Risorsa non disponibile con i parametri di input. |
| 410 - Non disponibile | Timeout o scadenza del collegamento al manifesto. Inviare una nuova richiesta. |
Attributi dei dati di utilizzo
La risposta dell'API di utilizzo fatturata o non fatturata con il parametro di richiesta "completo" o "basic" restituisce gli attributi seguenti:
| Attributo | "full" | "basic" |
|---|---|---|
| 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 |
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