API pro fakturaci podle měřené spotřeby na Marketplace
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 vyžadována pro každou zakoupenou nabídku, která má jeden nebo více plánů s vlastními dimenzemi pro vysílá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 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í 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 datového 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 využití účtované podle měrného využití
Toto rozhraní API událostí dávkového využití umožňuje generovat události využití pro více než jeden zakoupený prostředek současně. 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á řetězcová hodnota 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 bylo 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í 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. Další podrobnosti o předplatných SaaS najdete v list subscriptions.
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
}
]
}
V případě plánů pro spravované aplikace Azure je resourceUri
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. Emise dávkového využití byla přijata a zaznamenána u 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é zátěže 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á události využití z 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 datum 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á textová hodnota pro klientskou operaci. 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.