Share via

Facturerings-API's voor Marketplace naar gebruik

  • Artikel

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

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-facturering met een datalimiet voor meer informatie over het maken van aangepaste metingsdimensies voor SaaS.

Zie De configuratiedetails van uw Azure-toepassingsaanbieding configureren voor meer informatie over het maken van aangepaste metingsdimensies voor een Azure-toepassing aanbieding 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.

Eenmalige factureringsgebeurtenis met één gebruik

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 de afgelopen 24 uur alleen worden verzonden. 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>

Queryparameters:

Parameter Aanbeveling
ApiVersion Gebruik 2018-08-31.

Aanvraagheaders:

Inhoudstype application/json gebruiken
x-ms-requestid Unieke tekenreekswaarde voor het bijhouden 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. De notatie is "Bearer <access_token>" wanneer de tokenwaarde wordt opgehaald door de uitgever zoals uitgelegd voor

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-toepassing Managed Apps-abonnementen is dit de resourceId beheerde appresource group Id. Een voorbeeldscript voor het ophalen ervan vindt u in het gebruik van het door Azure beheerde identiteitentoken.

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

Antwoorden

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

Voorbeeld van nettolading van antwoord:

{
  "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
Ongeldig verzoek.

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

Voorbeeld van nettolading van antwoord:

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

Code: 403

Verboden. Het autorisatietoken is niet opgegeven, is ongeldig of verlopen. Of de aanvraag probeert toegang te krijgen tot een abonnement voor een aanbieding die is gepubliceerd met een andere Microsoft Entra-app-id van degene die wordt gebruikt om het autorisatietoken te maken.

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.

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

Queryparameters:

Parameter Aanbeveling
ApiVersion Gebruik 2018-08-31.

Aanvraagheaders:

Inhoudstype application/json gebruiken
x-ms-requestid Unieke tekenreekswaarde voor het bijhouden 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. De notatie 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-toepassing Managed Apps-abonnementen isresourceUri. Zie Azure Marketplace-facturering met een datalimiet voor meer informatie over resource-id's. Het kiezen van de juiste id bij het verzenden van gebruiksgebeurtenissen.

Voor SaaS-aanbiedingen is dit de Id van het resourceId SaaS-abonnement. Zie de lijst met abonnementen voor 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-toepassing Managed Apps-plannen is dit resourceUri de beheerde toepassingresourceUsageId. Een voorbeeldscript voor het ophalen ervan vindt u in het gebruik van het door Azure beheerde identiteitentoken.

Voorbeeld van aanvraagbody voor Azure-toepassing 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
    }
  ]
}

Antwoorden

Code: 200
OK. De emissie van batchgebruik is geaccepteerd en geregistreerd aan de zijde van Microsoft voor verdere verwerking en facturering. De antwoordlijst wordt geretourneerd met de status voor elke afzonderlijke gebeurtenis in de batch. U moet de nettolading van het antwoord herhalen om inzicht te krijgen in de antwoorden voor elke afzonderlijke gebruiksgebeurtenis die wordt verzonden als onderdeel van de batchgebeurtenis.

Voorbeeld van nettolading van antwoord:

{
  "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 statuscode waarnaar wordt verwezen in BatchUsageEvent API-antwoord:

Statuscode Beschrijving
Accepted Aanvaard.
Expired Verlopen gebruik.
Duplicate Er is een dubbel gebruik opgegeven.
Error Foutcode.
ResourceNotFound De opgegeven gebruiksresource is ongeldig.
ResourceNotAuthorized U bent niet gemachtigd om gebruik voor deze resource op te geven.
ResourceNotActive De resource is onderbroken of is 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: 403
Verboden. Het autorisatietoken is niet opgegeven, is ongeldig of verlopen. Of de aanvraag probeert toegang te krijgen tot een abonnement voor een aanbieding die is gepubliceerd met een andere Microsoft Entra-app-id van degene die wordt gebruikt om het autorisatietoken te maken.

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

Queryparameters:

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

Mogelijke waarden van reconStatus:

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

Aanvraagheaders:

Content type 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.
autorisatie Een uniek toegangstoken dat de ISV identificeert die deze API-aanroep maakt. De notatie is Bearer <access_token> wanneer de tokenwaarde wordt opgehaald door de uitgever. Zie voor meer informatie:

Antwoorden

Voorbeelden van nettoladingen van antwoorden:

Aanvaard*

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

Ingediend

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

Mismatch

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

Afgekeurd

[
  {
    "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: 403 Verboden. Het autorisatietoken is niet opgegeven, is ongeldig of verlopen. Of de aanvraag probeert toegang te krijgen tot een abonnement voor een aanbieding die is gepubliceerd met een andere Microsoft Entra-app-id van degene die wordt gebruikt om het autorisatietoken te maken.

Best practices voor ontwikkelen en testen

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.

Support krijgen

Volg de instructies in Ondersteuning voor het commerciële marketplace-programma in Partnercentrum voor meer informatie over ondersteuningsopties voor uitgevers en open een ondersteuningsticket bij Microsoft.

Volgende stappen

Zie de veelgestelde vragen over service-API's voor de meteringservice voor Marketplace voor meer informatie over service-API's voor metering.