Dela via

API:er för mätdebitering i marknadsplats

  • Artikel

API:erna för mätbaserad fakturering ska användas när utgivaren skapar anpassade mätningsdimensioner för ett erbjudande som ska publiceras i Partner Center. Integrering med API:er för mätfakturering är nödvändig för alla köpta erbjudanden som har en eller flera planer med anpassade dimensioner för att rapportera användningshändelser.

Viktig

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ätardimensioner för SaaS finns i SaaS-fakturering baserad på mätvärden.

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.

Mätarfaktureringshändelse för enskild användning

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.

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

Frågeparametrar:

Parameter Rekommendation
ApiVersion Använd 2018-08-31.

Begäransrubriker:

Innehållstyp Använd 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 Managed Apps-planer är resourceId 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 resourceId SaaS-prenumerations-ID. Mer information om SaaS-prenumerationer finns i listprenumerationer.

Svaren

Kod: 200
OKEJ. Användningsutsläppet accepterades och registrerades på Microsofts sida för vidare bearbetning och fakturering.

Exempel på svarslast:

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

  • Saknade eller ogiltiga förfrågningsdata har angetts.
  • effectiveStartTime är mer än 24 timmar före. 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: 401 Obehörig. Auktoriseringstoken är ogiltig eller har upphört att gälla. Begäran försöker komma åt en SaaS-prenumeration för ett erbjudande som publicerades med ett annat Microsoft Entra-app-ID än det som användes för att skapa autentiseringstoken.

Kod: 403 Förbjudet. Auktoriseringstoken är ogiltig, har inte angetts eller har inte fått tillräckliga behörigheter. Ange en giltig 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"
}

Batchhändelse för mätad debitering

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 datumet 2018-08-31.

Begärandehuvuden:

Innehållstyp Använd 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

Not

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 resourceId SaaS-prenumerations-ID. 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 är resourceUri det hanterade programmet resourceUsageId. Ett exempelskript för att hämta det finns i med tokenfö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
    }
  ]
}

Svaren

Kod: 200
OKEJ. 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 i BatchUsageEvent API-svar:

Statuskod Beskrivning
Accepted Accepterad.
Expired Användning har upphört att gälla.
Duplicate Upprepad användning tillåten.
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: 401 Obehörig. Auktoriseringstoken är ogiltig eller har upphört att gälla. Begäran försöker komma åt en SaaS-prenumeration för ett erbjudande som publicerades med ett annat Microsoft Entra-app-ID än det som användes för att skapa autentiseringstoken.

Kod: 403 Förbjudet. Auktoriseringstoken är ogiltig, har inte angetts eller har inte fått tillräckliga behörigheter. Ange en giltig auktoriseringstoken.

Hämta användningshändelser för mätarfakturering

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.
användningsstartdatum Datum och tid i ISO8601-format. Till exempel 2020-12-03T15:00 eller 2020-12-03
UsageEndDate (valfritt) Datum och tid i ISO8601-formatet. 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
Skickat Har inte bearbetats av PC Analytics än
Accepterad Matchad med PC Analytics
Avvisad Avvisades i processen. 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änd application/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.
auktorisation 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:

Svaren

Exempel på svarsinnehåll:

accepterade*

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

skickade

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

matchningsfel

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

avvisade

[
  {
    "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: 401 Obehörig. Auktoriseringstoken är ogiltig eller har upphört att gälla. Begäran försöker komma åt en SaaS-prenumeration för ett erbjudande som publicerades med ett annat Microsoft Entra-app-ID än det som användes för att skapa autentiseringstoken.

Kod: 403 Förbjudet. Auktoriseringstoken är ogiltig, har inte angetts eller har inte fått tillräckliga behörigheter. Ange en giltig 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

För mer information om API:er för avläsningstjänsten, se vanliga frågor och svar om Marketplace-avläsningstjänstens API:er.