Sdílet prostřednictvím

API pro fakturaci podle měřené spotřeby na Marketplace

  • Článek

Rozhraní API pro měřenou fakturaci by se měla použít, když vydavatel vytvoří vlastní dimenze měření pro nabídku, která se má publikovat v Partner Center. Integrace s rozhraními API pro fakturaci na základě spotřeby je požadována pro každou zakoupenou nabídku, která má jeden nebo více plánů s vlastními dimenzemi pro generování událostí spotřeby.

Důležitý

Musíte mít přehled o využití ve vašem kódu a odesílat společnosti Microsoft pouze události využití, které přesahují základní poplatek.

Další informace o vytváření vlastních dimenzí měření pro SaaS najdete v části SaaS metered billing.

Další informace o vytváření vlastních dimenzí měření pro nabídku aplikace Azure pomocí plánu spravované aplikace najdete v tématu Konfigurace podrobností o nastavení nabídky aplikace Azure.


Vynucování protokolu TLS 1.2 Poznámka

Verze PROTOKOLU TLS 1.2 se vynucuje jako minimální verze komunikace HTTPS. Ujistěte se, že ve svém kódu používáte tuto verzi protokolu TLS. Tls verze 1.0 a 1.1 jsou zastaralé a pokusy o připojení budou odmítnuty.

Událost jednorázového účtování podle spotřeby

Rozhraní API pro události využití by mělo být voláno vydavatelem, aby generovalo události využití pro aktivní prostředky (předplacené) podle plánu zakoupeného konkrétním zákazníkem. Událost využití se vygeneruje zvlášť pro každou vlastní dimenzi plánu definovanou vydavatelem při publikování nabídky.

Pro každou hodinu kalendářního dne na zdroj a dimenzi je možné vygenerovat pouze jednu událost využití. Pokud se spotřebuje více než jedna jednotka za hodinu, kumulujte všechny jednotky spotřebované v hodině a pak je vygenerujte v jedné události. Události využití je možné emitovat pouze za posledních 24 hodin. Pokud událost využití vygenerujete kdykoli v rozmezí od 8:00 do 8:59:59 (a přijme se) a odešlete další událost pro stejný den od 8:00 do 8:59:59, bude odmítnuta jako duplicitní.

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

parametry dotazu :

Parametr Doporučení
ApiVersion Použijte 31. 8. 2018.

Hlavičky požadavku:

Typ obsahu Použijte application/json
x-ms-requestid Jedinečná hodnota ve formě řetězce pro sledování požadavku od klienta, nejlépe ve formátu GUID. Pokud tato hodnota není zadaná, jedna se vygeneruje a poskytne v hlavičce odpovědi.
x-ms-correlationid Jedinečná hodnota řetězce pro operaci na straně klienta. Tento parametr koreluje všechny události z operace klienta s událostmi na straně serveru. Pokud tato hodnota není zadaná, jedna se vygeneruje a poskytne v hlavičce odpovědi.
authorization Jedinečný přístupový token, který identifikuje ISV, jenž provádí toto volání rozhraní API. Formát je "Bearer <access_token>", když je hodnota tokenu načtena vydavatelem, jak je to vysvětleno výše.

Příklad textu požadavku :

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

Pro plány spravovaných aplikací Azure je resourceId spravovaná aplikace resource group Id. Ukázkový skript pro načtení najdete v za použití tokenu spravovaných identit Azure.

U nabídek SaaS je resourceId ID předplatného SaaS. Pro další podrobnosti o předplatných SaaS viz seznam předplatných.

Odpovědi

Kód: 200
OK. Emise využití byly přijaty a zaznamenány na straně Microsoftu pro další zpracování a fakturaci.

Příklad datového obsahu odpovědi:

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

Kód: 400
Chybný požadavek.

  • Byla nalezena chybějící nebo neplatná data žádosti.
  • effectiveStartTime uběhlo více než 24 hodin. Vypršela platnost události.
  • Předplatné SaaS není ve stavu Přihlášení k odběru.

Příklad obsahu odpovědi:

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

Kód: 401 Neautorizováno. Autorizační token je neplatný nebo vypršela jeho platnost. Žádost se pokouší o přístup k předplatnému SaaS pro nabídku, která byla publikována s jiným ID aplikace Microsoft Entra, než které se použilo k vytvoření ověřovacího tokenu.

Kód: 403 Zakázáno. Autorizační token je neplatný, nebyl poskytnut nebo byl poskytnut s nedostatečnými oprávněními. Nezapomeňte zadat platný autorizační token.

Kód: 409
Konflikt. Událost využití již byla úspěšně hlášena pro zadané ID prostředku, datum efektivního využití a hodinu.

Příklad datového obsahu odpovědi:

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

Událost dávkového účtování na základě měrného využití

Rozhraní API pro hromadné využívání umožňuje generovat události využití pro více zakoupených prostředků najednou. Umožňuje také vyvolat několik událostí využití pro stejný zdroj, pokud jsou určeny pro různé kalendářní hodiny. Maximální počet událostí v jedné dávce je 25.

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

parametry dotazu :

Parametr Doporučení
ApiVersion Použijte 31. 8. 2018.

Hlavičky požadavku:

Typ obsahu Použijte application/json
x-ms-requestid Jedinečná hodnota ve formě řetězce pro sledování požadavku od klienta, nejlépe ve formátu GUID. Pokud tuto hodnotu nezadáte, vygeneruje se jedna a bude poskytnuta v hlavičkách odpovědi.
x-ms-correlationid Jedinečná hodnota řetězce pro operaci na straně klienta. Tento parametr koreluje všechny události z operace klienta s událostmi na straně serveru. Pokud tuto hodnotu nezadáte, vygeneruje se jedna a bude poskytnuta v hlavičkách odpovědi.
authorization Jedinečný přístupový token, který identifikuje ISV, jenž provádí toto volání rozhraní API. Formát je Bearer <access_token>, když je hodnota tokenu načtena vydavatelem, jak je vysvětleno výše.

Poznámka

V textu požadavku má identifikátor prostředku různé významy pro aplikaci SaaS a pro aplikaci spravovanou v Azure, která generuje vlastní měřič. Identifikátor prostředku aplikace SaaS je resourceID. Identifikátor prostředku pro plány spravovaných aplikací Azure je resourceUri. Další informace o identifikátorech zdrojů, které se týkají fakturace na základě měření v Azure Marketplace, najdete v tématu Výběr správného ID při odesílání událostí využití.

U nabídek SaaS je resourceId ID předplatného SaaS. Pro další podrobnosti o předplatných SaaS viz seznam předplatných.

Příklad textu požadavku pro aplikace SaaS:

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

Pro plány spravovaných aplikací Azure je resourceUri vlastně spravovaná aplikace resourceUsageId. Ukázkový skript pro načtení najdete v za použití tokenu spravovaných identit Azure.

Příklad textu požadavku pro aplikace spravované aplikací Azure:

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

Odpovědi

Kód: 200
OK. Deklarace dávkového využití byla přijata a zaznamenána na straně Microsoftu pro další zpracování a fakturaci. Seznam odpovědí je vrácen s uvedením stavu pro každou jednotlivou událost v dávce. Měli byste procházet obsah odpovědi, abyste porozuměli odpovědím pro každou jednotlivou událost použití poslanou jako součást dávkové události.

Příklad datového obsahu odpovědi:

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

Popis stavového kódu odkazovaného v odpovědi rozhraní API BatchUsageEvent:

Stavový kód Popis
Accepted Přijato.
Expired Platnost vypršela.
Duplicate Bylo poskytnuto duplicitní využití.
Error Kód chyby
ResourceNotFound Zadaný zdroj využití je neplatný.
ResourceNotAuthorized Nemáte oprávnění k poskytování použití pro tento zdroj.
ResourceNotActive Prostředek je pozastavený nebo se nikdy neaktivoval.
InvalidDimension Dimenze, pro kterou je využití předáno, je pro tuto nabídku nebo plán neplatná.
InvalidQuantity Předané množství je nižší nebo rovno 0.
BadArgument Vstup chybí nebo je poškozený.

Kód: 400
Chybný požadavek. Dávka obsahovala více než 25 událostí využití.

Kód: 401 Neautorizováno. Autorizační token je neplatný nebo vypršela jeho platnost. Žádost se pokouší o přístup k předplatnému SaaS pro nabídku, která byla publikována s jiným ID aplikace Microsoft Entra, než které se použilo k vytvoření ověřovacího tokenu.

Kód: 403 Zakázáno. Autorizační token je neplatný, nebyl poskytnut nebo byl poskytnut s nedostatečnými oprávněními. Nezapomeňte zadat platný autorizační token.

Načítání událostí užití ze systému měřeného účtování

Pokud chcete získat seznam událostí využití, můžete volat rozhraní API událostí využití. Nezávislí výrobci softwaru můžou toto rozhraní API použít k zobrazení událostí využití, které byly publikovány po určitou konfigurovatelnou dobu a jaký stav jsou tyto události v okamžiku volání rozhraní API.

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

parametry dotazu:

Parametr Doporučení
ApiVersion Použijte 31. 8. 2018.
datum začátku použití Datum a čas ve formátu ISO 8601. Například 2020-12-03T15:00 nebo 2020-12-03
UsageEndDate (volitelné) Datum a čas ve formátu ISO 8601. Výchozí = aktuální datum
offerId (volitelné) Výchozí = vše k dispozici
planId (volitelné) Výchozí = vše k dispozici
dimenze (volitelné) Výchozí = vše k dispozici
azureSubscriptionId (volitelné) Výchozí = vše k dispozici
reconStatus (volitelné) Výchozí = vše k dispozici

Možné hodnoty reconStatus:

ReconStatus Popis
Předložený Dosud nezpracované službou PC Analytics
Přijato Spárováno s počítačovou analytikou
Odmítnutý Odmítnuto ve fázi zpracování. Pokud chcete zjistit příčinu, obraťte se na podporu Microsoftu.
Neshoda Hodnoty pro MarketplaceAPI a analýzy Partnerského centra jsou obě nenulové, ale neshodují se.

hlavičky žádosti :

Typ obsahu Použijte application/json
x-ms-requestid Jedinečná řetězcová hodnota (nejlépe identifikátor GUID) pro sledování požadavku od klienta. Pokud tato hodnota není zadaná, jedna se vygeneruje a poskytne v hlavičce odpovědi.
x-ms-correlationid Jedinečná hodnota řetězce pro operaci na straně klienta. Tento parametr koreluje všechny události z operace klienta s událostmi na straně serveru. Pokud tato hodnota není zadaná, jedna se vygeneruje a poskytne v hlavičce odpovědi.
oprávnění Jedinečný přístupový token, který identifikuje ISV, jenž provádí toto volání rozhraní API. Formát je Bearer <access_token>, když vydavatel načte hodnotu tokenu. Další informace najdete tady:

Odpovědi

Příklady datového obsahu z odpovědí:

přijato*

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

odeslané

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

Neshoda

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

odmítnuté

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

stavové kódy

Kód: 401 Neautorizováno. Autorizační token je neplatný nebo vypršela jeho platnost. Žádost se pokouší o přístup k předplatnému SaaS pro nabídku, která byla publikována s jiným ID aplikace Microsoft Entra, než které se použilo k vytvoření ověřovacího tokenu.

Kód: 403 Zakázáno. Autorizační token je neplatný, nebyl poskytnut nebo byl poskytnut s nedostatečnými oprávněními. Nezapomeňte zadat platný autorizační token.

Osvědčené postupy vývoje a testování

Pokud chcete otestovat emise vlastního měřiče, implementujte integraci s rozhraním API pro měření, vytvořte plán publikované nabídky SaaS s vlastními dimenzemi definovanými s nulovou cenou za jednotku. Tuto nabídku publikujte jako verzi Preview, aby k integraci měli přístup a otestování jenom omezený uživatelé.

Pokud chcete omezit přístup k tomuto plánu během testování na omezenou cílovou skupinu, můžete také použít soukromý plán pro existující živou nabídku.

Získání podpory

Postupujte podle pokynů v části Podpora pro program komerčního marketplace v Partnerském centru, abyste porozuměli možnostem podpory vydavatele a otevřeli lístek podpory u Microsoftu.

Související obsah

Další informace o rozhraních API služby měření najdete v tématu Rozhraní API služby měření marketplace – nejčastější dotazy.