Delen via

API's voor gebruiksmeting in de Marketplace

  • Artikel

De API's voor facturering naar gebruik moeten worden gebruikt wanneer de uitgever aangepaste meterdimensies maakt voor een aanbieding die in Partnercentrum gepubliceerd moet worden. Integratie met de API's voor verbruik-gebaseerde facturering is vereist voor elke aangeschafte aanbieding met een of meer abonnementen met aangepaste dimensies om gebruiksgebeurtenissen te genereren.

Belangrijk

U moet het gebruik in uw code bijhouden en alleen gebruiksgebeurtenissen naar Microsoft verzenden voor het gebruik dat hoger is dan de basiskosten.

Zie SaaS-verbruiksafrekeningvoor meer informatie over het maken van aangepaste verbruiksdimensies voor SaaS.

Zie De configuratiegegevens van uw Azure-toepassing configurerenvoor meer informatie over het maken van aangepaste meetdimensies voor een Azure-toepassingsaanbieding met een beheerd app-plan.


TLS 1.2-notitie afdwingen

TLS-versie 1.2 wordt afgedwongen als minimale versie voor HTTPS-communicatie. Zorg ervoor dat u deze TLS-versie in uw code gebruikt. TLS-versie 1.0 en 1.1 zijn afgeschaft en verbindingspogingen worden geweigerd.

Afrekening voor eenmalig verbruik

De API voor gebruiksgebeurtenissen moet worden aangeroepen door de uitgever om gebruiksgebeurtenissen te verzenden op basis van een actieve resource (geabonneerd) voor het abonnement dat is gekocht door de specifieke klant. De gebruiks gebeurtenis wordt afzonderlijk verzonden voor elke aangepaste dimensie van het plan dat door de uitgever is gedefinieerd bij het publiceren van de aanbieding.

Er kan slechts één gebruiksgebeurtenis worden verzonden voor elk uur van een kalenderdag per resource en dimensie. Als er meer dan één eenheid in een uur wordt verbruikt, verzamelt u alle eenheden die in het uur worden verbruikt en verzendt u deze vervolgens in één gebeurtenis. Gebruiksevenementen kunnen alleen worden uitgezonden voor de afgelopen 24 uur. Als u een gebruiksevenement op elk gewenst moment verzendt tussen 8:00 en 8:59:59 (en deze wordt geaccepteerd) en een extra gebeurtenis verzendt voor dezelfde dag tussen 8:00 en 8:59:59, wordt deze geweigerd als een duplicaat.

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

Query parameters:

Parameter Aanbeveling
ApiVersion Gebruik 2018-08-31.

verzoekheaders:

Inhoudstype Gebruik application/json
x-ms-requestid Unieke tekenreekswaarde voor het volgen van de aanvraag van de client, bij voorkeur een GUID. Als deze waarde niet is opgegeven, wordt er een gegenereerd en opgegeven in de antwoordheaders.
x-ms-correlationid Unieke tekenreekswaarde voor bewerking op de client. Deze parameter correleert alle gebeurtenissen van de clientbewerking met gebeurtenissen aan de serverzijde. Als deze waarde niet is opgegeven, wordt er een gegenereerd en opgegeven in de antwoordheaders.
authorization Een uniek toegangstoken dat de ISV identificeert die deze API-aanroep maakt. Het formaat is "Bearer <access_token>" wanneer de tokenwaarde wordt opgehaald door de uitgever, zoals eerder uitgelegd.

voorbeeld van aanvraagtekst:

{
  "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
}

Voor Azure Application Managed Apps-abonnementen is het resourceId de beheerde app-resource group Id. Een voorbeeldscript voor het ophalen ervan vindt u in met behulp van het door Azure beheerde identiteitentoken.

Voor SaaS-aanbiedingen is de resourceId de Id van het SaaS-abonnement. Zie lijst met abonnementenvoor meer informatie over SaaS-abonnementen.

Reacties

Code: 200
OK. De gebruiksemissie is geaccepteerd en geregistreerd aan de zijde van Microsoft voor verdere verwerking en facturering.

Voorbeeld van antwoord payload:

{
  "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
}

Code: 400
Onjuist verzoek.

  • Ontbrekende of ongeldige aanvraaggegevens opgegeven.
  • effectiveStartTime ligt meer dan 24 uur in het verleden. Het evenement is verlopen.
  • Het SaaS-abonnement heeft niet de status 'Geabonneerd'.

Voorbeeld van payload van antwoord:

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

Code: 401 Niet geautoriseerd. Het autorisatietoken is ongeldig of verlopen. De aanvraag probeert toegang te krijgen tot een SaaS-abonnement voor een aanbieding die is gepubliceerd met een ander Microsoft Entra-app-ID dan het ID dat gebruikt is om het verificatietoken aan te maken.

Code: 403 Verboden. Het autorisatietoken is ongeldig, is niet opgegeven of is voorzien van onvoldoende machtigingen. Zorg ervoor dat u een geldig autorisatietoken opgeeft.

Code: 409
Conflict. Er is al een gebruiksgebeurtenis gerapporteerd voor de opgegeven resource-id, de ingangsdatum en het uur.

Voorbeeld van nettolading van antwoord:

{
  "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"
}

Gebeurtenis voor batchgebruik met een datalimiet

Met de gebeurtenis-API voor batchgebruik kunt u gebruiksgebeurtenissen verzenden voor meer dan één aangeschafte resource tegelijk. Hiermee kunt u ook verschillende gebruiksgebeurtenissen verzenden voor dezelfde resource, zolang ze voor verschillende kalenderuren zijn. Het maximale aantal gebeurtenissen in één batch is 25.

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

Queryparameters:

Parameter Aanbeveling
ApiVersion Gebruik 2018-08-31.

Verzoekheaders:

Inhoudstype Gebruik application/json
x-ms-requestid Unieke tekenreekswaarde voor het bijhouden van het verzoek van de client, bij voorkeur een GUID. Als deze waarde niet is opgegeven, wordt er een gegenereerd en opgegeven in de antwoordheaders.
x-ms-correlationid Unieke tekenreekswaarde voor bewerking op de client. Deze parameter correleert alle gebeurtenissen van de clientbewerking met gebeurtenissen aan de serverzijde. Als deze waarde niet is opgegeven, wordt er een gegenereerd en opgegeven in de antwoordheaders.
authorization Een uniek toegangstoken dat de ISV identificeert die deze API-aanroep maakt. Het formaat is Bearer <access_token> wanneer de tokenwaarde wordt opgehaald door de uitgever, zoals uitgelegd voor

Notitie

In de aanvraagbody heeft de resource-id verschillende betekenissen voor de SaaS-app en voor de beheerde Azure-app die een aangepaste meter verzendt. De resource-id voor SaaS-app is resourceID. De resource-id voor Azure Application Managed Apps-abonnementen is resourceUri. Zie voor meer informatie over resource-identifiers het gedeelte Azure Marketplace-facturering naar gebruik: de juiste id kiezen bij het verzenden van gebruiksgebeurtenissen.

Voor SaaS-aanbiedingen is de resourceId de Id van het SaaS-abonnement. Zie lijst met abonnementenvoor meer informatie over SaaS-abonnementen.

voorbeeld van aanvraagtekst voor SaaS-apps:

{
  "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
    }
  ]
}

Voor Azure Application Managed Apps-plannen is de resourceUri de beheerde toepassing resourceUsageId. Een voorbeeldscript voor het ophalen ervan vindt u in met behulp van het door Azure beheerde identiteitentoken.

voorbeeld van aanvraagbody voor door Azure-toepassingen beheerde apps:

{
  "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
    }
  ]
}

Reacties

Code: 200
OK. De emissie van batchgebruik is geaccepteerd en geregistreerd door Microsoft voor verdere verwerking en facturering. De antwoordlijst wordt geretourneerd met de status voor elke afzonderlijke gebeurtenis in de batch. U moet door de antwoordpayload itereren om inzicht te krijgen in de reacties voor elke afzonderlijke gebruiksgebeurtenis die verzonden wordt als onderdeel van de batchgebeurtenis.

Voorbeeld van antwoordpayload:

{
  "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"
    }
  ]
}

Beschrijving van de statuscode waarnaar wordt verwezen in BatchUsageEvent API-antwoord:

Statuscode Beschrijving
Accepted Geaccepteerd.
Expired Verlopen gebruik.
Duplicate Er is een dubbel gebruik opgegeven.
Error Foutcode.
ResourceNotFound De opgegeven gebruiksresource is ongeldig.
ResourceNotAuthorized U bent niet gemachtigd om het gebruik van deze bron aan te geven.
ResourceNotActive De hulpbron is opgeschort of was nooit geactiveerd.
InvalidDimension De dimensie waarvoor het gebruik wordt doorgegeven, is ongeldig voor deze aanbieding/plan.
InvalidQuantity De doorgegeven hoeveelheid is lager of gelijk aan 0.
BadArgument De invoer ontbreekt of is onjuist.

Code: 400
Ongeldig verzoek. De batch bevat meer dan 25 gebruiksgebeurtenissen.

Code: 401 Niet geautoriseerd. Het autorisatietoken is ongeldig of verlopen. De aanvraag probeert toegang te krijgen tot een SaaS-abonnement voor een aanbod dat met een andere Microsoft Entra-app-ID is gepubliceerd dan degene die is gebruikt om het authenticatietoken te maken.

Code: 403 Verboden. Het autorisatietoken is ongeldig, is niet opgegeven of is voorzien van onvoldoende machtigingen. Zorg ervoor dat u een geldig autorisatietoken opgeeft.

Gebruiksgebeurtenissen ophalen met een datalimiet

U kunt de API voor gebruiksevenementen aanroepen om de lijst met gebruiksevenementen op te halen. ISV's kunnen deze API gebruiken om de gebruiksgebeurtenissen te zien die gedurende een bepaalde configureerbare tijdsduur zijn gepost en welke status deze gebeurtenissen zijn op het moment dat de API wordt aangeroepen.

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

query parameters:

Parameter Aanbeveling
ApiVersion Gebruik 2018-08-31.
gebruiksstartdatum Datum en tijd in ISO8601-formaat. Bijvoorbeeld: 2020-12-03T15:00 of 2020-12-03
UsageEndDate (optioneel) Datum en tijd in ISO8601-indeling. Standaard = huidige datum
offerId (optioneel) Standaard = alle beschikbare
planId (optioneel) Standaard = alle beschikbare opties
dimensie (optioneel) Standaard = alle beschikbare
azureSubscriptionId (optioneel) Standaard: alle beschikbare opties
reconStatus (optioneel) Standaard = alle beschikbare

Mogelijke waarden van reconStatus:

ReconStatus Beschrijving
Ingediend Nog niet verwerkt door PC Analytics
Geaccepteerd Overeenkomend met PC Analytics
Afgekeurd Geweigerd in de pijplijn. Neem contact op met Microsoft Ondersteuning om de oorzaak te onderzoeken.
Wanverhouding MarketplaceAPI- en Partner Center Analytics-hoeveelheden zijn beide niet-nul, maar niet overeenkomend

request-headers:

Inhoudstype Toepassing/json gebruiken
x-ms-requestid Unieke tekenreekswaarde (bij voorkeur een GUID) voor het bijhouden van de aanvraag van de client. Als deze waarde niet is opgegeven, wordt er een gegenereerd en opgegeven in de antwoordheaders.
x-ms-correlationid Unieke tekenreekswaarde voor bewerking op de client. Deze parameter correleert alle gebeurtenissen van de clientbewerking met gebeurtenissen aan de serverzijde. Als deze waarde niet is opgegeven, wordt er een gegenereerd en opgegeven in de antwoordheaders.
machtiging Een uniek toegangstoken dat de ISV identificeert die deze API-aanroep maakt. Het formaat is Bearer <access_token> wanneer de tokenwaarde door de uitgever wordt opgehaald. Zie voor meer informatie:

Reacties

Voorbeelden van nettoladingen van antwoorden:

geaccepteerde*

[
  {
    "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
  }
]

verzonden

[
  {
    "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
  }
]

niet-overeenkomende

[
  {
    "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
  }
]

Geweigerd

[
  {
    "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
  }
]

Statuscodes

Code: 401 Niet geautoriseerd. Het autorisatietoken is ongeldig of verlopen. De aanvraag probeert toegang te krijgen tot een SaaS-abonnement voor een aanbieding die is gepubliceerd met een andere Microsoft Entra-app-id dan degene die wordt gebruikt om het authenticatietoken te maken.

Code: 403 Verboden. Het autorisatietoken is ongeldig, is niet opgegeven of is voorzien van onvoldoende machtigingen. Zorg ervoor dat u een geldig autorisatietoken opgeeft.

Best practices voor ontwikkelings- en testprocessen

Als u de emissie van de aangepaste meter wilt testen, implementeert u de integratie met de metering-API, maakt u een plan voor uw gepubliceerde SaaS-aanbieding met aangepaste dimensies die erin zijn gedefinieerd met nulprijs per eenheid. En publiceer deze aanbieding als preview zodat alleen beperkte gebruikers de integratie kunnen openen en testen.

U kunt ook een privéabonnement gebruiken voor een bestaande live-aanbieding om de toegang tot dit plan tijdens het testen te beperken tot een beperkt publiek.

Ondersteuning krijgen

Volg de instructies in Ondersteuning voor het commerciële marketplace-programma in Partnercentrum om inzicht te krijgen in ondersteuningsopties voor uitgevers en een ondersteuningsticket te openen bij Microsoft.

Verwante inhoud

Zie voor meer informatie over meteredienst-API's de FAQ over Marketplace-meterdienst-API's .