API di fatturazione a consumo del Marketplace

  • Articolo

Le API di fatturazione basate sul consumo devono essere usate quando il publisher crea dimensioni di misurazione personalizzate per un'offerta da pubblicare nel Partner Center. 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 applicazione Azure 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 fatturazione a consumo per singolo utilizzo

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 emessi 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.

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

Parametri di Query :

Parametro Raccomandazione
ApiVersion Utilizzare entro il 31/08/2018.

Intestazioni di richiesta:

Tipo di contenuto Usare application/json
x-ms-requestid Valore stringa univoco per tenere traccia della richiesta dal client, preferibilmente un GUID. Se questo valore non viene specificato, ne verrà generato uno e fornito nelle intestazioni della risposta.
x-ms-correlationid Valore stringa univoco per l'operazione sul client. Questo parametro correla tutti gli eventi dell'operazione client con gli eventi sul lato server. Se questo valore non viene specificato, ne verrà generato uno e fornito 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 del 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 delle Applicazioni gestite di Azure, il resourceId è l'app gestita resource group Id. Uno script di esempio per il recupero è disponibile in usando il token delle identità gestite da Azure.

Per le offerte SaaS, il resourceId è l'ID sottoscrizione SaaS. Per ulteriori dettagli sulle sottoscrizioni SaaS, consulta 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 è passato da più di 24 ore. 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: 401 Non autorizzato. Il token di autorizzazione non è valido o è scaduto. La richiesta sta tentando di accedere a una sottoscrizione SaaS per un'offerta pubblicata con un ID app Microsoft Entra diverso da quello usato per creare il token di autenticazione.

Codice: 403 Accesso negato. Il token di autorizzazione non è valido, non è stato fornito o è stato fornito con autorizzazioni insufficienti. Assicurarsi di fornire un token di autorizzazione valido.

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 di 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 per la fatturazione basata sul 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.

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

parametri di query :

Parametro Raccomandazione
ApiVersion Utilizzare entro il 31-08-2018.

intestazioni di richiesta :

Tipo di contenuto Usare application/json
x-ms-requestid Valore stringa univoco per tenere traccia della richiesta dal client, preferibilmente un GUID. Se questo valore non viene specificato, ne verrà generato uno e fornito nelle intestazioni della risposta.
x-ms-correlationid Valore stringa univoco per l'operazione sul client. Questo parametro correla tutti gli eventi dell'operazione client con gli eventi sul lato server. Se questo valore non viene specificato, ne verrà generato uno e fornito 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 pubblicatore come spiegato 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 applicazioni di Azure è 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 resourceId è l'ID sottoscrizione SaaS. Per altre informazioni sulle sottoscrizioni SaaS, vedere elenco delle sottoscrizioni.

Esempio di Contenuto 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 i piani di Azure per le App Gestite, il resourceUri è l'Applicazione Gestita resourceUsageId. Uno script di esempio per il recupero è disponibile in usando il token delle identità gestite da Azure.

esempio di corpo della richiesta per le app gestite da applicazioni di Azure:

{
  "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 da parte di 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 dell'API BatchUsageEvent:

Codice di stato Descrizione
Accepted Accettato.
Expired Utilizzo scaduto.
Duplicate Utilizzo duplicato fornito.
Error Codice di errore.
ResourceNotFound La risorsa di utilizzo specificata non è valida.
ResourceNotAuthorized Tu non sei autorizzato a gestire l'utilizzo di questa risorsa.
ResourceNotActive La risorsa viene sospesa o non è mai stata attivata.
InvalidDimension La dimensione per cui viene passato l'utilizzo non è valida per l'offerta o il piano.
InvalidQuantity La quantità passata è inferiore o uguale a 0.
BadArgument L'input è mancante o malformato.

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

Codice: 401 Non autorizzato. Il token di autorizzazione non è valido o è scaduto. La richiesta sta tentando di accedere a una sottoscrizione SaaS per un'offerta pubblicata con un ID app Microsoft Entra diverso da quello usato per creare il token di autenticazione.

Codice: 403 Accesso negato. Il token di autorizzazione non è valido, non è stato fornito o è stato fornito con autorizzazioni insufficienti. Assicurarsi di fornire un token di autorizzazione valido.

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 Raccomandazione
ApiVersion Utilizzare entro il 31-08-2018.
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 quelli disponibili
planId (facoltativo) Valore predefinito = tutti gli elementi disponibili
dimensione (facoltativo) Il valore predefinito è impostato su tutti quelli disponibili.
azureSubscriptionId (facoltativo) Valore predefinito = tutti disponibili
reconStatus (facoltativo) Valore predefinito = tutto disponibile

Valori possibili di reconStatus:

ReconStatus Descrizione
Inviato Non ancora elaborato da Analisi PC
Accettato Abbinato con l'analisi del PC
Respinto Rifiutato nella pipeline. Contattare il supporto tecnico Microsoft per indagare sulla causa.
Discrepanza Le quantità di MarketplaceAPI e Partner Center Analytics sono entrambe diverse da zero, tuttavia non corrispondono.

intestazioni di richiesta:

Tipo di contenuto Utilizza application/json
x-ms-requestid Valore stringa univoco (preferibilmente un GUID), per tenere traccia della richiesta dal client. Se questo valore non viene specificato, ne verrà generato uno e fornito nelle intestazioni della risposta.
x-ms-correlationid Valore stringa univoco per l'operazione sul client. Questo parametro correla tutti gli eventi dell'operazione client con gli eventi sul lato server. Se questo valore non viene specificato, ne verrà generato uno e fornito 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, vedere:

Risposte

Esempi di payload di 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 a

[
  {
    "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: 401 Non autorizzato. Il token di autorizzazione non è valido o è scaduto. La richiesta sta tentando di accedere a una sottoscrizione SaaS per un'offerta pubblicata con un ID app Microsoft Entra diverso da quello usato per creare il token di autenticazione.

Codice: 403 Accesso negato. Il token di autorizzazione non è valido, non è stato fornito o è stato fornito con autorizzazioni insufficienti. Assicurarsi di fornire un token di autorizzazione valido.

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, con un prezzo per unità pari a zero. 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

Segui le istruzioni riportate in , Supporto per il programma del marketplace commerciale in Partner Center, per aprire un ticket di supporto con Microsoft e comprendere le opzioni di supporto dell'editore.

Contenuto correlato

Per ulteriori informazioni sulle API del servizio di misurazione del Marketplace, vedere le domande frequenti .