API:er för fakturering med marketplace-dataförbrukning
API:erna för fakturering med dataförbrukning ska användas när utgivaren skapar anpassade mått för avläsning för ett erbjudande som ska publiceras i Partnercenter. Integrering med API:er för fakturering med dataförbrukning krävs för alla köpta erbjudanden som har en eller flera planer med anpassade dimensioner för att generera användningshändelser.
Viktigt!
Du måste hålla reda på användningen i koden och endast skicka användningshändelser till Microsoft för den användning som ligger över basavgiften.
Mer information om hur du skapar anpassade mätningsdimensioner för SaaS finns i SaaS-fakturering med mätning.
Mer information om hur du skapar anpassade mätningsdimensioner för ett Azure-programerbjudande med en hanterad appplan finns i Konfigurera konfigurationsinformation för ditt Azure-programerbjudande.
Framtvinga TLS 1.2-anmärkning
TLS version 1.2-versionen framtvingas som den lägsta versionen för HTTPS-kommunikation. Se till att du använder den här TLS-versionen i koden. TLS version 1.0 och 1.1 är inaktuella och anslutningsförsök nekas.
Händelse för enkel användning med mätarfakturering
API:et för användningshändelsen ska anropas av utgivaren för att generera användningshändelser mot en aktiv resurs (prenumererad) för den plan som köpts av den specifika kunden. Användningshändelsen genereras separat för varje anpassad dimension av planen som definieras av utgivaren när erbjudandet publiceras.
Endast en användningshändelse kan genereras för varje timme per kalenderdag per resurs och dimension. Om mer än en enhet förbrukas på en timme ackumulerar du alla enheter som förbrukas under timmen och genererar den sedan i en enda händelse. Användningshändelser kan bara genereras under de senaste 24 timmarna. Om du genererar en användningshändelse när som helst mellan 8:00 och 8:59:59 (och den godkänns) och skickar en ytterligare händelse för samma dag mellan 8:00 och 8:59:59, avvisas den som en dubblett.
POST: https://marketplaceapi.microsoft.com/api/usageEvent?api-version=<ApiVersion>
Frågeparametrar:
| Parameter | Rekommendation |
|---|---|
ApiVersion |
Använd 2018-08-31. |
Begärandehuvuden:
| Innehållstyp | Använda application/json |
|---|---|
x-ms-requestid |
Unikt strängvärde för att spåra begäran från klienten, helst ett GUID. Om det här värdet inte anges genereras ett värde och anges i svarshuvudena. |
x-ms-correlationid |
Unikt strängvärde för åtgärden på klienten. Den här parametern korrelerar alla händelser från klientåtgärden med händelser på serversidan. Om det här värdet inte anges genereras ett värde och anges i svarshuvudena. |
authorization |
En unik åtkomsttoken som identifierar den ISV som gör det här API-anropet. Formatet är "Bearer <access_token>" när tokenvärdet hämtas av utgivaren enligt beskrivningen för
|
Exempel på begärandetext:
{
"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
}
För Azure Application Managed Apps-planer resourceId är den hanterade appen resource group Id. Ett exempelskript för att hämta det finns i med hjälp av token för Azure-hanterade identiteter.
För SaaS-erbjudanden är saaS-prenumerations-ID resourceId :t. Mer information om SaaS-prenumerationer finns i listprenumerationer.
Svar
Kod: 200
OK. Användningsutsläppet accepterades och registrerades på Microsofts sida för vidare bearbetning och fakturering.
Exempel på svarsnyttolast:
{
"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
}
Kod: 400
Felaktig begäran.
- Data om saknade eller ogiltiga begäranden har angetts.
effectiveStartTimeär mer än 24 timmar tidigare. Händelsen har upphört att gälla.- SaaS-prenumerationen har inte prenumerationsstatus.
Exempel på svarsnyttolast:
{
"message": "One or more errors have occurred.",
"target": "usageEventRequest",
"details": [
{
"message": "The resourceId is required.",
"target": "ResourceId",
"code": "BadArgument"
}
],
"code": "BadArgument"
}
Kod: 403
Förbjuden. Auktoriseringstoken har inte angetts, är ogiltig eller har upphört att gälla. Eller så försöker begäran komma åt en prenumeration för ett erbjudande som publicerades med ett annat Microsoft Entra-app-ID än det som användes för att skapa auktoriseringstoken.
Kod: 409
Konflikt. En användningshändelse har redan rapporterats för det angivna resurs-ID:t, gällande användningsdatum och timme.
Exempel på svarsnyttolast:
{
"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"
}
Användningshändelse för batchanvändning med dataförbrukning
Med händelse-API:et för batchanvändning kan du generera användningshändelser för mer än en köpt resurs samtidigt. Det gör också att du kan generera flera användningshändelser för samma resurs så länge de är för olika kalendertimmar. Det maximala antalet händelser i en enda batch är 25.
POST: https://marketplaceapi.microsoft.com/api/batchUsageEvent?api-version=<ApiVersion>
Frågeparametrar:
| Parameter | Rekommendation |
|---|---|
ApiVersion |
Använd 2018-08-31. |
Begärandehuvuden:
| Innehållstyp | Använda application/json |
|---|---|
x-ms-requestid |
Unikt strängvärde för att spåra begäran från klienten, helst ett GUID. Om det här värdet inte anges genereras ett värde och anges i svarshuvudena. |
x-ms-correlationid |
Unikt strängvärde för åtgärden på klienten. Den här parametern korrelerar alla händelser från klientåtgärden med händelser på serversidan. Om det här värdet inte anges genereras ett värde och anges i svarshuvudena. |
authorization |
En unik åtkomsttoken som identifierar den ISV som gör det här API-anropet. Formatet är Bearer <access_token> när tokenvärdet hämtas av utgivaren enligt beskrivningen för
|
Kommentar
I begärandetexten har resursidentifieraren olika betydelser för SaaS-appen och för Azure Managed App som genererar anpassad mätare. Resursidentifieraren för SaaS-appen är resourceID. Resursidentifieraren för Azure Application Managed Apps-planer är resourceUri. Mer information om resursidentifierare finns i Azure Marketplace-fakturering med mätardata – Välja rätt ID när du skickar användningshändelser.
För SaaS-erbjudanden är saaS-prenumerations-ID resourceId :t. Mer information om SaaS-prenumerationer finns i listprenumerationer.
Exempel på begärandetext för SaaS-appar:
{
"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
}
]
}
För Azure Application Managed Apps-planer resourceUri är det hanterade programmet resourceUsageId. Ett exempelskript för att hämta det finns i med hjälp av token för Azure-hanterade identiteter.
Exempel på begärandetext för azure-programhanterade appar:
{
"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
}
]
}
Svar
Kod: 200
OK. Batchanvändningsutsläppet accepterades och registrerades på Microsofts sida för vidare bearbetning och fakturering. Svarslistan returneras med status för varje enskild händelse i batchen. Du bör iterera genom svarsnyttolasten för att förstå svaren för varje enskild användningshändelse som skickas som en del av batchhändelsen.
Exempel på svarsnyttolast:
{
"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"
}
]
}
Beskrivning av statuskod som refereras till i BatchUsageEvent API-svaret:
| Statuskod | beskrivning |
|---|---|
Accepted |
Accepterad. |
Expired |
Användning har upphört att gälla. |
Duplicate |
Duplicerad användning tillhandahålls. |
Error |
Felkod. |
ResourceNotFound |
Den angivna användningsresursen är ogiltig. |
ResourceNotAuthorized |
Du har inte behörighet att använda den här resursen. |
ResourceNotActive |
Resursen är pausad eller har aldrig aktiverats. |
InvalidDimension |
Dimensionen för vilken användningen skickas är ogiltig för det här erbjudandet/planen. |
InvalidQuantity |
Mängden som skickas är lägre eller lika med 0. |
BadArgument |
Indata saknas eller är felaktiga. |
Kod: 400
Felaktig begäran. Batchen innehöll fler än 25 användningshändelser.
Kod: 403
Förbjuden. Auktoriseringstoken har inte angetts, är ogiltig eller har upphört att gälla. Eller så försöker begäran komma åt en prenumeration för ett erbjudande som publicerades med ett annat Microsoft Entra-app-ID än det som användes för att skapa auktoriseringstoken.
Hämta användningshändelser för fakturering med dataförbrukning
Du kan anropa API:et för användningshändelser för att hämta listan över användningshändelser. ISV:er kan använda det här API:et för att se användningshändelser som har publicerats under en viss konfigurerbar tidsperiod och vilket tillstånd dessa händelser befinner sig vid tidpunkten för att anropa API:et.
GET: https://marketplaceapi.microsoft.com/api/usageEvents
Frågeparametrar:
| Parameter | Rekommendation |
|---|---|
| ApiVersion | Använd 2018-08-31. |
| usageStartDate | DateTime i ISO8601 format. Till exempel 2020-12-03T15:00 eller 2020-12-03 |
| UsageEndDate (valfritt) | DateTime i ISO8601 format. Standard = aktuellt datum |
| offerId (valfritt) | Standard = alla tillgängliga |
| planId (valfritt) | Standard = alla tillgängliga |
| dimension (valfritt) | Standard = alla tillgängliga |
| azureSubscriptionId (valfritt) | Standard = alla tillgängliga |
| reconStatus (valfritt) | Standard = alla tillgängliga |
Möjliga värden för reconStatus:
| ReconStatus | beskrivning |
|---|---|
| Skickad | Har inte bearbetats av PC Analytics än |
| Har godkänts | Matchas med PC Analytics |
| Avvisat | Avvisades i pipelinen. Kontakta Microsofts support för att undersöka orsaken. |
| Obalans | MarketplaceAPI- och Partner Center Analytics-kvantiteterna är båda icke-noll, men matchar inte |
Begärandehuvuden:
| Innehållstyp | Använda program/json |
|---|---|
| x-ms-requestid | Unikt strängvärde (helst ett GUID) för att spåra begäran från klienten. Om det här värdet inte anges genereras ett värde och anges i svarshuvudena. |
| x-ms-correlationid | Unikt strängvärde för åtgärden på klienten. Den här parametern korrelerar alla händelser från klientåtgärden med händelser på serversidan. Om det här värdet inte anges genereras ett värde och anges i svarshuvudena. |
| auktorisering | En unik åtkomsttoken som identifierar den ISV som gör det här API-anropet. Formatet är Bearer <access_token> när tokenvärdet hämtas av utgivaren. Mer information finns i:
|
Svar
Exempel på svarsnyttolast:
Accepterad*
[
{
"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
}
]
Skickat
[
{
"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
}
]
Obalans
[
{
"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
}
]
Avvisad
[
{
"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
}
]
Statuskoder
Kod: 403 Förbjudet. Auktoriseringstoken har inte angetts, är ogiltig eller har upphört att gälla. Eller så försöker begäran komma åt en prenumeration för ett erbjudande som publicerades med ett annat Microsoft Entra-app-ID än det som användes för att skapa auktoriseringstoken.
Metodtips för utveckling och testning
Om du vill testa den anpassade mätarutsläppen implementerar du integreringen med mätnings-API:et, skapar en plan för ditt publicerade SaaS-erbjudande med anpassade dimensioner som definierats i det med noll pris per enhet. Och publicera det här erbjudandet som förhandsversion så att endast begränsade användare skulle kunna komma åt och testa integreringen.
Du kan också använda en privat plan för ett befintligt liveerbjudande för att begränsa åtkomsten till den här planen under testningen till en begränsad målgrupp.
Få support
Följ anvisningarna i Support för det kommersiella marketplace-programmet i Partnercenter för att förstå supportalternativ för utgivare och öppna ett supportärende med Microsoft.
Relaterat innehåll
Mer information om API:er för avläsningstjänsten finns i Vanliga frågor och svar om API:er för Marketplace-avläsningstjänsten.