API di fatturazione a consumo del Marketplace

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.

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:

Intestazioni della richiesta:

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.

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

Parametri di query:

Intestazioni della richiesta:

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: 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:

Valori possibili di reconStatus:

Intestazioni della richiesta:

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.

Contenuto correlato

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