Rozhraní API fakturace účtované podle měrného využití Marketplace

  • Článek

Účtovaná rozhraní API pro fakturaci by se měla použít, když vydavatel vytvoří vlastní dimenze měření pro nabídku, která se má publikovat v Partnerském centru. Integrace s účtovanými rozhraními API pro fakturaci se vyžaduje pro každou zakoupenou nabídku, která má jeden nebo více plánů s vlastními dimenzemi k generování událostí využití.

Důležité

Musíte mít přehled o využití v kódu a odesílat microsoftu pouze události využití za využití nad základním poplatkem.

Další informace o vytváření vlastních dimenzí měření pro SaaS najdete v tématu Fakturace účtovaná podle měření SaaS.

Další informace o vytváření vlastních dimenzí měření pro nabídku Aplikace Azure s plánem spravované aplikace najdete v tématu Konfigurace podrobností o nastavení nabídky aplikací 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 využití účtované podle měrného využití

Rozhraní API události využití by mělo být volána vydavatelem, aby vygeneroval události využití pro aktivní prostředek (přihlášený) pro plán zakoupený 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é vygenerovat 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žití application/json
x-ms-requestid Jedinečná řetězcová hodnota pro sledování požadavku od klienta, nejlépe identifikátor 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 v klientovi. 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 výrobce softwaru, který provádí toto volání rozhraní API. Formát je "Bearer <access_token>" , když vydavatel načte hodnotu tokenu, jak je vysvětleno

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í Aplikace Azure je spravovaná resourceId aplikace resource group Id. Ukázkový skript pro načtení najdete v tokenu identit spravovaných Azure.

U nabídek resourceId SaaS je ID předplatného SaaS. Další podrobnosti o předplatných SaaS najdete v seznamu 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é části 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 je v minulosti více než 24 hodin. Vypršela platnost události.
  • Předplatné SaaS není ve stavu Přihlášení k odběru.

Příklad datové části 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: 403

Zakázáno. Autorizační token není zadaný, je neplatný nebo vypršela jeho platnost. Nebo se žádost pokouší o přístup k předplatnému nabídky publikované s jiným ID aplikace Microsoft Entra, než je id aplikace použité k vytvoření autorizačního tokenu.

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é části 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 využití účtované podle měrného využití

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

PŘÍSPĚVEK: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žití application/json
x-ms-requestid Jedinečná řetězcová hodnota pro sledování požadavku od klienta, nejlépe identifikátor GUID. Pokud tuto hodnotu nezadáte, vygeneruje se jedna a zadaná v hlavičce odpovědi.
x-ms-correlationid Jedinečná hodnota řetězce pro operaci v klientovi. 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 zadaná v hlavičce odpovědi.
authorization Jedinečný přístupový token, který identifikuje výrobce softwaru, který provádí toto volání rozhraní API. Formát je Bearer <access_token> , když vydavatel načte hodnotu tokenu, jak je vysvětleno

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í Aplikace Azure je resourceUri. Další informace oidentifikátorch službě Azure Marketplace najdete v tématu o tom, jak při odesílání událostí využití vybrat správné ID.

U nabídek resourceId SaaS je ID předplatného SaaS. Další podrobnosti o předplatných SaaS najdete v seznamu 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í resourceUri Aplikace Azure je spravovaná aplikace resourceUsageId. Ukázkový skript pro načtení najdete v tokenu identit spravovaných Azure.

Příklad textu požadavku pro Aplikace Azure spravovaných aplikací:

{
  "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. Emise dávkového využití byly přijaty a zaznamenány na straně Microsoftu pro další zpracování a fakturaci. Seznam odpovědí se vrátí se stavem každé jednotlivé události v dávce. Měli byste iterovat datovou část odpovědi, abyste porozuměli odpovědím pro každou jednotlivou událost využití poslanou jako součást dávkové události.

Příklad datové části 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 BatchUsageEvent odpovědi rozhraní API:

Stavový kód Popis
Accepted Přijata.
Expired Platnost vypršela.
Duplicate Bylo poskytnuto duplicitní využití.
Error Kód chyby
ResourceNotFound Zadaný prostředek využití je neplatný.
ResourceNotAuthorized Nemáte oprávnění k poskytování využití pro tento prostředek.
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: 403
Zakázáno. Autorizační token není zadaný, je neplatný nebo vypršela jeho platnost. Nebo se žádost pokouší o přístup k předplatnému nabídky publikované s jiným ID aplikace Microsoft Entra, než je id aplikace použité k vytvoření autorizačního tokenu.

Načítá události využití účtované podle měřených dat fakturace

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.
usageStartDate DateTime ve formátu ISO8601. Například 2020-12-03T15:00 nebo 2020-12-03
UsageEndDate (volitelné) DateTime ve formátu ISO8601. 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
Odesláno Dosud nezpracované službou PC Analytics
Akceptováno Spárováno s analýzou počítačů
Zamítnuto Odmítnuto v kanálu. Pokud chcete zjistit příčinu, obraťte se na podporu Microsoftu.
Neshoda Objem analýzy MarketplaceAPI i Partnerského centra jsou nenulové, ale neshodují se

Hlavičky požadavku:

Typ obsahu Použití 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 v klientovi. 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.
autorizace Jedinečný přístupový token, který identifikuje výrobce softwaru, který provádí toto volání rozhraní API. Formát je Bearer <access_token> , když vydavatel načte hodnotu tokenu. Další informace naleznete v tématu:

Odpovědi

Příklady datové části odpovědi:

Přijata*

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

Odesláno

[
  {
    "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ítnuto

[
  {
    "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: 403 Zakázáno. Autorizační token není zadaný, je neplatný nebo vypršela jeho platnost. Nebo se žádost pokouší o přístup k předplatnému nabídky publikované s jiným ID aplikace Microsoft Entra, než je id aplikace použité k vytvoření autorizačního tokenu.

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.

Technická podpora

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.

Další kroky

Další informace o rozhraních API služby měření najdete v tématu Nejčastější dotazy k rozhraním API služby měření na Marketplace.