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.

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:

Begärandehuvuden:

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:

Begärandehuvuden:

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:

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:

Möjliga värden för reconStatus:

Begärandehuvuden:

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.