API di fatturazione a consumo del Marketplace

  • Articolo

Le API di fatturazione a consumo devono essere usate quando l'editore crea dimensioni di misurazione personalizzate per pubblicare un'offerta nel Centro per i partner. L'integrazione con le API di fatturazione a consumo è necessaria per qualsiasi offerta acquistata con uno o più piani con dimensioni personalizzate per generare eventi di utilizzo.

Importante

È necessario tenere traccia dell'utilizzo nel codice e inviare solo gli eventi di utilizzo a Microsoft per l'utilizzo superiore alla tariffa di base.

Per altre informazioni sulla creazione di dimensioni di misurazione personalizzate per SaaS, vedere Fatturazione a consumo SaaS.

Per altre informazioni sulla creazione di dimensioni di misurazione personalizzate per un'offerta di app Azure lication con un piano di app gestita, vedere Configurare i dettagli di configurazione dell'offerta dell'applicazione Azure.

Applicazione della nota TLS 1.2

La versione 1.2 di TLS viene applicata come versione minima per le comunicazioni HTTPS. Assicurarsi di usare questa versione di TLS nel codice. TLS versione 1.0 e 1.1 sono deprecati e i tentativi di connessione verranno rifiutati.

Evento di utilizzo singolo di fatturazione a consumo

L'API evento di utilizzo deve essere chiamata dal server di pubblicazione per generare eventi di utilizzo su una risorsa attiva (sottoscritta) per il piano acquistato dal cliente specifico. L'evento di utilizzo viene generato separatamente per ogni dimensione personalizzata del piano definito dall'editore durante la pubblicazione dell'offerta.

È possibile generare un solo evento di utilizzo per ogni ora di un giorno di calendario per risorsa e dimensione. Se più unità vengono utilizzate in un'ora, accumulare tutte le unità utilizzate nell'ora e quindi generarla in un singolo evento. Gli eventi di utilizzo possono essere generati solo per le ultime 24 ore. Se si genera un evento di utilizzo in qualsiasi momento tra le 8:00 e le 8:59:59 (e viene accettato) e si invia un evento aggiuntivo per lo stesso giorno tra le 8:00 e le 8:59:59, verrà rifiutato come duplicato.

PUBBLICAZIONE: https://marketplaceapi.microsoft.com/api/usageEvent?api-version=<ApiVersion>

Parametri di query:

Parametro Elemento consigliato
ApiVersion Usare 2018-08-31.

Intestazioni della richiesta:

Tipo di contenuto Utilizzare application/json
x-ms-requestid Valore stringa univoco per tenere traccia della richiesta dal client, preferibilmente un GUID. Se il valore non viene fornito, ne verrà generato e fornito uno nelle intestazioni della risposta.
x-ms-correlationid Valore stringa univoco per l'operazione sul client. Questo parametro mette in correlazione tutti gli eventi dell'operazione del client con gli eventi sul lato server. Se il valore non viene fornito, ne verrà generato e fornito uno nelle intestazioni della risposta.
authorization Token di accesso univoco che identifica l'ISV che effettua questa chiamata API. Il formato è "Bearer <access_token>" quando il valore del token viene recuperato dal server di pubblicazione come illustrato per

Esempio di corpo della richiesta:

{
  "resourceId": <guid>, // unique identifier of the resource against which usage is emitted. 
  "quantity": 5.0, // how many units were consumed for the date and hour specified in effectiveStartTime, must be greater than 0 or a double integer
  "dimension": "dim1", // custom dimension identifier
  "effectiveStartTime": "2018-12-01T08:30:14", // time in UTC when the usage event occurred, from now and until 24 hours back
  "planId": "plan1", // id of the plan purchased for the offer
}

Per i piani di app gestite di app Azure lication, resourceId è l'app resource group Idgestita . Uno script di esempio per recuperarlo è disponibile quando si usa il token delle identità gestite da Azure.

Per le offerte SaaS, il valore di resourceId è l'ID della sottoscrizione SaaS. Per altre informazioni sulle sottoscrizioni SaaS, vedere l'elenco delle sottoscrizioni.

Risposte

Codice: 200
OK. L'emissione di utilizzo è stata accettata e registrata sul lato Microsoft per ulteriori elaborazioni e fatturazione.

Esempio di payload della risposta:

{
  "usageEventId": <guid>, // unique identifier associated with the usage event in Microsoft records
  "status": "Accepted" // this is the only value in case of single usage event
  "messageTime": "2020-01-12T13:19:35.3458658Z", // time in UTC this event was accepted
  "resourceId": <guid>, // unique identifier of the resource against which usage is emitted. For SaaS it's the subscriptionId.
  "quantity": 5.0, // amount of emitted units as recorded by Microsoft
  "dimension": "dim1", // custom dimension identifier
  "effectiveStartTime": "2018-12-01T08:30:14", // time in UTC when the usage event occurred, as sent by the ISV
  "planId": "plan1", // id of the plan purchased for the offer
}

Codice: 400
Richiesta non valida.

  • Dati di richiesta mancanti o non validi forniti.
  • effectiveStartTime è più di 24 ore in passato. Evento scaduto.
  • La sottoscrizione SaaS non è in stato Sottoscritto.

Esempio di payload della risposta:

{
  "message": "One or more errors have occurred.",
  "target": "usageEventRequest",
  "details": [
    {
      "message": "The resourceId is required.",
      "target": "ResourceId",
      "code": "BadArgument"
    }
  ],
  "code": "BadArgument"
}

Codice: 403

Non consentito. Il token di autorizzazione non viene fornito, non è valido o è scaduto. Oppure la richiesta sta tentando di accedere a una sottoscrizione per un'offerta pubblicata con un ID app Microsoft Entra diverso da quello usato per creare il token di autorizzazione.

Codice: 409
Conflitto. Un evento di utilizzo è già stato segnalato correttamente per l'ID risorsa specificato, la data di utilizzo effettiva e l'ora.

Esempio di payload della risposta:

{
  "additionalInfo": {
    "acceptedMessage": {
      "usageEventId": "<guid>", //unique identifier associated with the usage event in Microsoft records
      "status": "Duplicate",
      "messageTime": "2020-01-12T13:19:35.3458658Z",
      "resourceId": "<guid>", //unique identifier of the resource against which usage is emitted.
      "quantity": 1.0,
      "dimension": "dim1",
      "effectiveStartTime": "2020-01-12T11:03:28.14Z",
      "planId": "plan1"
    }
  },
  "message": "This usage event already exist.",
  "code": "Conflict"
}

Evento di utilizzo batch di fatturazione a consumo

L'API per gli eventi di utilizzo batch consente di generare eventi di utilizzo per più risorse acquistate contemporaneamente. Consente inoltre di generare diversi eventi di utilizzo per la stessa risorsa purché siano per ore di calendario diverse. Il numero massimo di eventi in un singolo batch è 25.

POSThttps://marketplaceapi.microsoft.com/api/batchUsageEvent?api-version=<ApiVersion>:

Parametri di query:

Parametro Elemento consigliato
ApiVersion Usare 2018-08-31.

Intestazioni della richiesta:

Tipo di contenuto Utilizzare application/json
x-ms-requestid Valore stringa univoco per tenere traccia della richiesta dal client, preferibilmente un GUID. Se il valore non viene specificato, ne verrà generato e inserito uno nelle intestazioni della risposta.
x-ms-correlationid Valore stringa univoco per l'operazione sul client. Questo parametro mette in correlazione tutti gli eventi dell'operazione del client con gli eventi sul lato server. Se il valore non viene specificato, ne verrà generato e inserito uno nelle intestazioni della risposta.
authorization Token di accesso univoco che identifica l'ISV che effettua questa chiamata API. Il formato è Bearer <access_token> quando il valore del token viene recuperato dal server di pubblicazione come illustrato per

Nota

Nel corpo della richiesta l'identificatore di risorsa ha significati diversi per l'app SaaS e per l'app gestita di Azure che genera un contatore personalizzato. L'identificatore della risorsa per l'app SaaS è resourceID. L'identificatore della risorsa per i piani di app gestite di app Azure lication è resourceUri. Per altre informazioni sugli identificatori di risorsa, vedere Fatturazione a consumo di Azure Marketplace- Selezione dell'ID corretto durante l'invio di eventi di utilizzo.

Per le offerte SaaS, il valore di resourceId è l'ID della sottoscrizione SaaS. Per altre informazioni sulle sottoscrizioni SaaS, vedere l'elenco delle sottoscrizioni.

Esempio di corpo della richiesta per le app SaaS:

{
  "request": [ // list of usage events for the same or different resources of the publisher
    { // first event
      "resourceId": "<guid1>", // Unique identifier of the resource against which usage is emitted. 
      "quantity": 5.0, // how many units were consumed for the date and hour specified in effectiveStartTime, must be greater than 0 or a double integer
      "dimension": "dim1", //Custom dimension identifier
      "effectiveStartTime": "2018-12-01T08:30:14",//Time in UTC when the usage event occurred, from now and until 24 hours back
      "planId": "plan1", // id of the plan purchased for the offer
    },
    { // next event
      "resourceId": "<guid2>", 
      "quantity": 39.0, 
      "dimension": "email", 
      "effectiveStartTime": "2018-11-01T23:33:10
      "planId": "gold", // id of the plan purchased for the offer
    }
  ]
}

Per app Azure piani di app gestite, resourceUri è l'applicazione resourceUsageIdgestita . Uno script di esempio per recuperarlo è disponibile quando si usa il token delle identità gestite da Azure.

Esempio di corpo della richiesta per le app gestite app Azure lication:

{
  "request": [ // list of usage events for the same or different resources of the publisher
    { // first event
      "resourceUri": "<fullyqualifiedname>", // Unique identifier of the resource against which usage is emitted. 
      "quantity": 5.0, // how many units were consumed for the date and hour specified in effectiveStartTime, must be greater than 0 or a double integer
      "dimension": "dim1", //Custom dimension identifier
      "effectiveStartTime": "2018-12-01T08:30:14",//Time in UTC when the usage event occurred, from now and until 24 hours back
      "planId": "plan1", // id of the plan purchased for the offer
    }
  ]
}

Risposte

Codice: 200
OK. L'emissione di utilizzo batch è stata accettata e registrata sul lato Microsoft per ulteriori elaborazioni e fatturazione. L'elenco di risposte viene restituito con lo stato per ogni singolo evento nel batch. È necessario scorrere il payload della risposta per comprendere le risposte per ogni singolo evento di utilizzo inviato come parte dell'evento batch.

Esempio di payload della risposta:

{
  "count": 2, // number of records in the response
  "result": [
    { // first response
      "usageEventId": "<guid>", // unique identifier associated with the usage event in Microsoft records
      "status": "Accepted" // see list of possible statuses below,
      "messageTime": "2020-01-12T13:19:35.3458658Z", // Time in UTC this event was accepted by Microsoft,
      "resourceId": "<guid1>", // unique identifier of the resource against which usage is emitted.
      "quantity": 5.0, // amount of emitted units as recorded by Microsoft 
      "dimension": "dim1", // custom dimension identifier
      "effectiveStartTime": "2018-12-01T08:30:14",// time in UTC when the usage event occurred, as sent by the ISV
      "planId": "plan1", // id of the plan purchased for the offer
    },
    { // second response
      "status": "Duplicate",
      "messageTime": "0001-01-01T00:00:00",
      "error": {
        "additionalInfo": {
          "acceptedMessage": {
            "usageEventId": "<guid>",
            "status": "Duplicate",
            "messageTime": "2020-01-12T13:19:35.3458658Z",
            "resourceId": "<guid2>",
            "quantity": 1.0,
            "dimension": "email",
            "effectiveStartTime": "2020-01-12T11:03:28.14Z",
            "planId": "gold"
          }
        },
        "message": "This usage event already exist.",
        "code": "Conflict"
      },
      "resourceId": "<guid2>",
      "quantity": 1.0,
      "dimension": "email",
      "effectiveStartTime": "2020-01-12T11:03:28.14Z",
      "planId": "gold"
    }
  ]
}

Descrizione del codice di stato a cui si fa riferimento nella risposta API BatchUsageEvent:

Codice di stato Descrizione
Accepted Accettato.
Expired Uso scaduto.
Duplicate Uso duplicato consentito.
Error Codice di errore.
ResourceNotFound La risorsa di uso specificata non è valida.
ResourceNotAuthorized Non si è autorizzati a fornire l'utilizzo per questa risorsa.
ResourceNotActive La risorsa viene sospesa o non è mai stata attivata.
InvalidDimension Le dimensioni per cui viene passato l'uso non sono valide per questa offerta o per questo piano.
InvalidQuantity La quantità passata è inferiore o uguale a 0.
BadArgument L'input è mancante o non valido.

Codice: 400
Richiesta non valida. Il batch contiene più di 25 eventi di utilizzo.

Codice: 403
Non consentito. Il token di autorizzazione non viene fornito, non è valido o è scaduto. Oppure la richiesta sta tentando di accedere a una sottoscrizione per un'offerta pubblicata con un ID app Microsoft Entra diverso da quello usato per creare il token di autorizzazione.

La fatturazione a consumo recupera gli eventi di utilizzo

È possibile chiamare l'API degli eventi di utilizzo per ottenere l'elenco degli eventi di utilizzo. Gli ISV possono usare questa API per visualizzare gli eventi di utilizzo che sono stati pubblicati per una determinata durata configurabile di tempo e quale stato questi eventi sono al punto di chiamare l'API.

GET: https://marketplaceapi.microsoft.com/api/usageEvents

Parametri di query:

Parametro Elemento consigliato
ApiVersion Usare 2018-08-31.
usageStartDate DateTime in formato ISO8601. Ad esempio, 2020-12-03T15:00 o 2020-12-03
UsageEndDate (facoltativo) DateTime in formato ISO8601. Valore predefinito = data corrente
offerId (facoltativo) Valore predefinito = tutti disponibili
planId (facoltativo) Valore predefinito = tutti disponibili
dimensione (facoltativo) Valore predefinito = tutti disponibili
azureSubscriptionId (facoltativo) Valore predefinito = tutti disponibili
reconStatus (facoltativo) Valore predefinito = tutti disponibili

Valori possibili di reconStatus:

ReconStatus Descrizione
Inviato Non ancora elaborato da Analisi PC
Accettata Corrispondenza con ANALISI PC
Rifiutato Rifiutato nella pipeline. Contattare il supporto tecnico Microsoft per indagare sulla causa.
Mancata corrispondenza Le quantità di Analisi del MarketplaceAPI e del Centro per i partner sono entrambe non pari a zero, ma non corrispondono

Intestazioni della richiesta:

Content type Usare application/json
x-ms-requestid Valore stringa univoco (preferibilmente un GUID), per tenere traccia della richiesta dal client. Se il valore non viene fornito, ne verrà generato e fornito uno nelle intestazioni della risposta.
x-ms-correlationid Valore stringa univoco per l'operazione sul client. Questo parametro mette in correlazione tutti gli eventi dell'operazione del client con gli eventi sul lato server. Se il valore non viene fornito, ne verrà generato e fornito uno nelle intestazioni della risposta.
autorizzazione Token di accesso univoco che identifica l'ISV che effettua questa chiamata API. Il formato è Bearer <access_token> quando il valore del token viene recuperato dal server di pubblicazione. Per altre informazioni, vedi:

Risposte

Esempi di payload della risposta:

Accettato*

[
  {
    "usageDate": "2020-11-30T00:00:00Z",
    "usageResourceId": "11111111-2222-3333-4444-555555555555",
    "dimension": "tokens",
    "planId": "silver",
   "planName": "Silver",
    "offerId": "mycooloffer",
    "offerName": "My Cool Offer",
    "offerType": "SaaS",
    "azureSubscriptionId": "12345678-9012-3456-7890-123456789012",
    "reconStatus": "Accepted",
    "submittedQuantity": 17.0,
    "processedQuantity": 17.0,
    "submittedCount": 17
  }
]

Inviato

[
  {
    "usageDate": "2020-11-30T00:00:00Z",
    "usageResourceId": "11111111-2222-3333-4444-555555555555",
    "dimension": "tokens",
    "planId": "silver",
    "planName": "",
    "offerId": "mycooloffer",
    "offerName": "",
    "offerType": "SaaS",
    "azureSubscriptionId": "12345678-9012-3456-7890-123456789012",
    "reconStatus": "Submitted",
    "submittedQuantity": 17.0,
    "processedQuantity": 0.0,
    "submittedCount": 17
  }
]

Mancata corrispondenza

[
  {
    "usageDate": "2020-11-30T00:00:00Z",
    "usageResourceId": "11111111-2222-3333-4444-555555555555",
    "dimension": "tokens",
    "planId": "silver",
    "planName": "Silver",
    "offerId": "mycooloffer",
    "offerName": "My Cool Offer",
    "offerType": "SaaS",
    "azureSubscriptionId": "12345678-9012-3456-7890-123456789012",
    "reconStatus": "Mismatch",
    "submittedQuantity": 17.0,
    "processedQuantity": 16.0,
    "submittedCount": 17
  }
]

Rifiutata

[
  {
    "usageDate": "2020-11-30T00:00:00Z",
    "usageResourceId": "11111111-2222-3333-4444-555555555555",
    "dimension": "tokens",
    "planId": "silver",
    "planName": "",
    "offerId": "mycooloffer",
    "offerName": "",
    "offerType": "SaaS",
    "azureSubscriptionId": "12345678-9012-3456-7890-123456789012",
    "reconStatus": "Rejected",
    "submittedQuantity": 17.0,
    "processedQuantity": 0.0,
    "submittedCount": 17
  }
]

Codici di stato

Codice: 403 Accesso negato. Il token di autorizzazione non viene fornito, non è valido o è scaduto. Oppure la richiesta sta tentando di accedere a una sottoscrizione per un'offerta pubblicata con un ID app Microsoft Entra diverso da quello usato per creare il token di autorizzazione.

Procedure consigliate per lo sviluppo e il test

Per testare l'emissione di contatori personalizzati, implementare l'integrazione con l'API di misurazione, creare un piano per l'offerta SaaS pubblicata con dimensioni personalizzate definite in esso con prezzo zero per unità. Pubblicare questa offerta come anteprima in modo che solo gli utenti limitati possano accedere e testare l'integrazione.

È anche possibile usare un piano privato per un'offerta live esistente per limitare l'accesso a questo piano durante i test a gruppi di destinatari limitati.

Ottenere supporto

Seguire le istruzioni riportate in Supporto per il programma del marketplace commerciale nel Centro per i partner per comprendere le opzioni di supporto dell'editore e aprire un ticket di supporto con Microsoft.

Passaggi successivi

Per altre informazioni sulle API del servizio di misurazione, vedere Domande frequenti sulle API del servizio di misurazione del Marketplace.