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.

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.

Usiamo i modelli di richiesta/risposta asincrona per ottimizzare le API di fatturazione e riconciliazione per fornire i risultati in modo asincrono. Le risposte API forniscono 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). Per altre informazioni, leggere le sezioni seguenti:

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 include un'intestazione Retry-After che indica quanto tempo 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 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

Parametri della richiesta deprecati

La versione più recente dell'API non richiede i parametri URI seguenti:

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.

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

Parametri della richiesta deprecati

La versione più recente dell'API non richiede i parametri URI seguenti:

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.

Passaggio 2: Controllare lo stato della richiesta

Attendere un HTTP 200 con stato del terminale riuscito o non riuscito. L'URL del manifesto è "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

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 questo stato HTTP:

Payload della risposta

Il payload della risposta API restituisce gli attributi seguenti:

Per l'attributo error:

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

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 questo stato HTTP:

Payload della risposta

La risposta dell'API restituisce gli attributi seguenti:

Payload del manifesto di esempio

{
"version": "1",
"dataFormat": "compressedJSONLines",
"utcCretedDateTime": "2022-04-29T22:40:57.1853571Z",
"eTag": "0x5B168C7B6E589D2",
"partnerTenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
"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:

Stati di risposta API standard

Di seguito sono riportati gli stati HTTP della risposta dell'API:

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: