Implementace webhooku ve službě SaaS
Při vytváření nabídky SaaS s možností transakce v Partnerském centru poskytuje partner adresu URL webhooku připojení, která se má použít jako koncový bod HTTP. Tento webhook volá Společnost Microsoft pomocí volání POST HTTP, která informuje vydavatele o následujících událostech, ke kterým dochází na straně Microsoftu:
| Událost Webhooku | 1. Při přijetí | 2. Je-li přijato | 3. Pokud byl odmítnut |
|---|---|---|---|
ChangePlan |
Odpověď pomocí HTTP 200 | PATCH s úspěchem (tato událost je volitelná a automaticky se vyčte v 10 sekundách) | PATCH s chybou NEBO odpovězte na 4xx (do 10 sekund) |
ChangeQuantity |
Odpověď pomocí HTTP 200 | PATCH s úspěchem (tato událost je volitelná a automaticky se vyčte v 10 sekundách) | PATCH s chybou NEBO odpovězte na 4xx (do 10 sekund) |
Renew |
Odpověď pomocí HTTP 200 | Nelze použít | Nelze použít |
Suspend |
Odpověď pomocí HTTP 200 | Nelze použít | Nelze použít |
Unsubscribe |
Odpověď pomocí HTTP 200 | Nelze použít | Nelze použít |
Reinstate |
Odpověď pomocí HTTP 200 | Nelze použít | Nejde použít (pokud není možné přijmout obnovení, volání rozhraní API pro odstranění, které aktivuje odstranění) |
Vydavatel musí ve službě SaaS implementovat webhook, aby byl stav předplatného SaaS konzistentní se stranou Microsoftu. Služba SaaS je nutná k volání rozhraní API operace Get, aby bylo před provedením akce na základě oznámení webhooku ověřeno a autorizováno volání webhooku a dat datové části webhooku. Jakmile bude volání webhooku zpracováno, vydavatel by měl microsoftu vrátit http 200. Tato hodnota potvrzuje, že volání webhooku bylo úspěšně přijato vydavatelem.
Důležité
Služba URL webhooku musí být spuštěná a spuštěná 24 × 7 a je připravená přijímat nová volání od Microsoftu vždy. Microsoft má zásady opakování pro volání webhooku (500 opakovaných pokusů za osm hodin), ale pokud vydavatel hovor nepřijme a vrátí odpověď, operace, o které webhook upozorní, nakonec selže na straně Microsoftu.
Důležité
Nezávislí výrobci softwaru by se měli vyhnout přísné deserializaci schématu Webhooku. Společnost Microsoft si vyhrazuje právo rozšířit schéma v budoucnu.
Důležité
Nezávislí výrobci softwaru musí z hlavičky požadavku ověřit token Microsoft Entra Token (JWT Token) ve svém koncovém bodu webhooku. Jedná se o standardní nosný token a poskytne isV podrobnosti o tom, kdo volající je. Další informace o ověření tokenu najdete v tomto článku. learn.microsoft.com/azure/active-directory/develop/access-tokens
Příklad datové části Webhooku ChangePlan:
{
"id": "<guid>",
"activityId": "<guid>",
"publisherId": "XXX",
"offerId": "YYY",
"planId": "plan2",
"quantity": 10,
"subscriptionId": "<guid>",
"timeStamp": "2023-02-10T18:48:58.4449937Z",
"action": "ChangePlan",
"status": "InProgress",
"operationRequestSource": "Azure",
"subscription":
{
"id": "<guid>",
"name": "Test",
"publisherId": "XXX",
"offerId": "YYY",
"planId": "plan1",
"quantity": 10,
"beneficiary":
{
"emailId": XX@outlook.com,
"objectId": "<guid>",
"tenantId": "<guid>",
"puid": "1234567890",
},
"purchaser":
{
"emailId": XX@outlook.com,
"objectId": "<guid>",
"tenantId": "<guid>",
"puid": "1234567890",
},
"allowedCustomerOperations": ["Delete", "Update", "Read"],
"sessionMode": "None",
"isFreeTrial": false,
"isTest": false,
"sandboxType": "None",
"saasSubscriptionStatus": "Subscribed",
"term":
{
"startDate": "2022-02-10T00:00:00Z",
"endDate": "2022-03-12T00:00:00Z",
"termUnit": "P1M",
"chargeDuration": null,
},
"autoRenew": true,
"created": "2022-01-10T23:15:03.365988Z",
"lastModified": "2022-02-14T20:26:04.5632549Z",
},
"purchaseToken": null
}
Příklad datové části Webhooku události ChangeQuantity:
{
"id": "<guid>",
"activityId": "<guid>",
"publisherId": "XXX",
"offerId": "YYY",
"planId": "plan1",
"quantity": 20,
"subscriptionId": "<guid>",
"timeStamp": "2023-02-10T18:54:00.6158973Z",
"action": "ChangeQuantity",
"status": "InProgress",
"operationRequestSource": "Azure",
"subscription": {
"id": "<guid>",
"name": "Test",
"publisherId": "XXX",
"offerId": "YYY",
"planId": "plan1",
"quantity": 10,
"beneficiary":
{
"emailId": XX@outlook.com,
"objectId": "<guid>",
"tenantId": "<guid>",
"puid": "1234567890",
},
"purchaser":
{
"emailId": XX@outlook.com,
"objectId": "<guid>",
"tenantId": "<guid>",
"puid": "1234567890",
},
"allowedCustomerOperations": ["Delete", "Update", "Read"],
"sessionMode": "None",
"isFreeTrial": false,
"isTest": false,
"sandboxType": "None",
"saasSubscriptionStatus": "Subscribed",
"term":
{
"startDate": "2022-02-10T00:00:00Z",
"endDate": "2022-03-12T00:00:00Z",
"termUnit": "P1M",
"chargeDuration": null,
},
"autoRenew": true,
"created": "2022-01-10T23:15:03.365988Z",
"lastModified": "2022-02-14T20:26:04.5632549Z",
},
"purchaseToken": null
}
Příklad datové části Webhooku události obnovení předplatného:
// end user's payment instrument became valid again, after being suspended, and the SaaS subscription is being reinstated
{
"id": "<guid>",
"activityId": "<guid>",
"publisherId": "XXX",
"offerId": "YYY",
"planId": "plan1",
"quantity": 100,
"subscriptionId": "<guid>",
"timeStamp": "2023-02-11T11:38:10.3508619Z",
"action": "Reinstate",
"status": "InProgress",
"operationRequestSource": "Azure",
"subscription":
{
"id": "<guid>",
"name": "Test",
"publisherId": "XXX",
"offerId": "YYY",
"planId": "plan1",
"quantity": 100,
"beneficiary":
{
"emailId": XX@outlook.com,
"objectId": "<guid>",
"tenantId": "<guid>",
"puid": "1234567890",
},
"purchaser":
{
"emailId": XX@outlook.com,
"objectId": "<guid>",
"tenantId": "<guid>",
"puid": "1234567890",
},
"allowedCustomerOperations": ["Delete", "Update", "Read"],
"sessionMode": "None",
"isFreeTrial": false,
"isTest": false,
"sandboxType": "None",
"saasSubscriptionStatus": "Suspended",
"term":
{
"startDate": "2022-02-10T00:00:00Z",
"endDate": "2022-03-12T00:00:00Z",
"termUnit": "P1M",
"chargeDuration": null,
},
"autoRenew": true,
"created": "2022-01-10T23:15:03.365988Z",
"lastModified": "2022-02-14T20:26:04.5632549Z",
},
"purchaseToken": null
}
Příklad datové části Webhooku události prodloužení:
// end user's subscription renewal
{
"id": "<guid>",
"activityId": "<guid>",
"publisherId": "XXX",
"offerId": "YYY",
"planId": "plan1",
"quantity": 100,
"subscriptionId": "<guid>",
"timeStamp": "2023-02-10T08:49:01.8613208Z",
"action": "Renew",
"status": "Succeeded",
"operationRequestSource": "Azure",
"subscription":
{
"id": "<guid>",
"name": "Test",
"publisherId": "XXX",
"offerId": "YYY",
"planId": "plan1",
"quantity": 100,
"beneficiary":
{
"emailId": XX@outlook.com,
"objectId": "<guid>",
"tenantId": "<guid>",
"puid": "1234567890",
},
"purchaser":
{
"emailId": XX@outlook.com,
"objectId": "<guid>",
"tenantId": "<guid>",
"puid": "1234567890",
},
"allowedCustomerOperations": ["Delete", "Update", "Read"],
"sessionMode": "None",
"isFreeTrial": false,
"isTest": false,
"sandboxType": "None",
"saasSubscriptionStatus": "Subscribed",
"term":
{
"startDate": "2022-02-10T00:00:00Z",
"endDate": "2022-03-12T00:00:00Z",
"termUnit": "P1M",
"chargeDuration": null,
},
"autoRenew": true,
"created": "2022-01-10T23:15:03.365988Z",
"lastModified": "2022-02-14T20:26:04.5632549Z",
},
"purchaseToken": null,
}
Příklad datové části Webhooku události pozastavení:
{
"id": "<guid>",
"activityId": "<guid>",
"publisherId": "XXX",
"offerId": "YYY",
"planId": "plan1",
"quantity": 100,
"subscriptionId": "<guid>",
"timeStamp": "2023-02-10T08:49:01.8613208Z",
"action": "Suspend",
"status": "Succeeded",
"operationRequestSource": "Azure",
"subscription":
{
"id": "<guid>",
"name": "Test",
"publisherId": "XXX",
"offerId": "YYY",
"planId": "plan1",
"quantity": 100,
"beneficiary":
{
"emailId": XX@outlook.com,
"objectId": "<guid>",
"tenantId": "<guid>",
"puid": "1234567890",
},
"purchaser":
{
"emailId": XX@outlook.com,
"objectId": "<guid>",
"tenantId": "<guid>",
"puid": "1234567890",
},
"allowedCustomerOperations": ["Delete", "Update", "Read"],
"sessionMode": "None",
"isFreeTrial": false,
"isTest": false,
"sandboxType": "None",
"saasSubscriptionStatus": "Suspended",
"term":
{
"startDate": "2022-02-10T00:00:00Z",
"endDate": "2022-03-12T00:00:00Z",
"termUnit": "P1M",
"chargeDuration": null,
},
"autoRenew": true,
"created": "2022-01-10T23:15:03.365988Z",
"lastModified": "2022-02-14T20:26:04.5632549Z",
},
"purchaseToken": null,
}
Příklad datové části Webhooku události odhlášení odběru:
Jedná se o událost, která je určena pouze pro upozornění. Pro tuto událost neexistuje odeslání do ACK.
{
"id": "<guid>",
"activityId": "<guid>",
"publisherId": "XXX",
"offerId": "YYY",
"planId": "plan1",
"quantity": 100,
"subscriptionId": "<guid>",
"timeStamp": "2023-02-10T08:49:01.8613208Z",
"action": "Unsubscribe",
"status": "Succeeded",
"operationRequestSource": "Azure",
"subscription":
{
"id": "<guid>",
"name": "Test",
"publisherId": "XXX",
"offerId": "YYY",
"planId": "plan1",
"quantity": 100,
"beneficiary":
{
"emailId": XX@outlook.com,
"objectId": "<guid>",
"tenantId": "<guid>",
"puid": "1234567890",
},
"purchaser":
{
"emailId": XX@outlook.com,
"objectId": "<guid>",
"tenantId": "<guid>",
"puid": "1234567890",
},
"allowedCustomerOperations": ["Delete", "Update", "Read"],
"sessionMode": "None",
"isFreeTrial": false,
"isTest": false,
"sandboxType": "None",
"saasSubscriptionStatus": "Unsubscribed",
"term":
{
"startDate": "2022-02-10T00:00:00Z",
"endDate": "2022-03-12T00:00:00Z",
"termUnit": "P1M",
"chargeDuration": null,
},
"autoRenew": true,
"created": "2022-01-10T23:15:03.365988Z",
"lastModified": "2022-02-14T20:26:04.5632549Z",
},
"purchaseToken": null,
}
Zabezpečení webhooků
Webhooky je nutné zabezpečit, aby žádné jiné než koncové body Microsoftu takové volání Webhooku nevolají. K implementaci webhooků můžete použít libovolnou technologii, ale implementace Webhooku musí dodržovat následující pokyny zabezpečení (viz kurz).
Microsoft volá webhooky s autorizačními hlavičkami, které obsahují potřebné informace k ověření volání. Aby webhooky mohly přijímat autorizační hlavičky, musíte povolit. (Nepřidávejte podrobnosti o autorizaci ani tokeny zabezpečení, jako jsou tokeny SAS, přímo do adres URL webhooku. Takové webhooky se nemusí podařit načíst autorizační hlavičky, které Microsoft odesílá při volání webhooků).
Nosný token JWT předaný v autorizační hlavičce obsahuje následující data v datové části, která můžete použít k zabezpečení koncových bodů.
"aud": "toto je ID aplikace Microsoft Entra Identity, které přidáte do technické konfigurace vaší nabídky v Partnerském centru Microsoftu"
"appid" nebo "azp": Toto je ID prostředku, které používáte při vytváření autorizačního tokenu vydavatele pro volání rozhraní API pro plnění SaaS. V závislosti na nastavení aplikace se tato hodnota ID prostředku může zobrazit buď v "appid" nebo "azp". Token má jednu ze dvou deklarací identity a v kódu musíte odpovídajícím způsobem reagovat.
"tid": "toto je ID tenanta Microsoft Entra, které přidáte do technické konfigurace vaší nabídky v Partnerském centru Microsoftu"
Zkontrolujte výše uvedená předaná pole a ujistěte se, že volání Webhooku je platné.
Důležité
Společnost Microsoft začne vyžadovat nezávislé výrobce softwaru, aby vytvořili své webhooky zabezpečeným způsobem a přijali autorizační hlavičky. Pokud vaše aktuální implementace Webhooku nemůže přijmout autorizační hlavičky, musíte aktualizovat webhooky a zabezpečit tyto koncové body (pomocí výše uvedených pokynů), aby nedošlo k přerušení.
Vývoj a testování
Pokud chcete zahájit proces vývoje, doporučujeme na straně vydavatele vytvářet fiktivní odpovědi rozhraní API. Tyto odpovědi mohou být založeny na ukázkových odpovědích uvedených v tomto článku.
Až bude vydavatel připravený na kompletní testování:
- Publikujte nabídku SaaS pro omezenou cílovou skupinu ve verzi Preview a ponechte ji ve fázi Preview.
- Nastavte cenu plánu na nulu, abyste se vyhnuli aktivaci skutečných fakturačních výdajů při testování. Další možností je nastavit nenulovou cenu a zrušit všechny testovací nákupy do 24 hodin.
- Ujistěte se, že jsou všechny toky vyvolány na konci, aby simulovaly scénář skutečného zákazníka.
- Pokud chce partner otestovat úplný nákup a tok fakturace, udělejte to s nabídkou, která má cenu vyšší než 0 USD. Nákup se fakturuje a vygeneruje se faktura.
Tok nákupu se dá aktivovat z webu Azure Portal nebo webu Microsoft AppSource v závislosti na tom, kde se nabídka publikuje.
Akce změnit plán, změnit množství a odhlášení odběru se testují na straně vydavatele. Na straně Microsoftu je možné zrušit odběr odběru na webu Azure Portal i v Centru pro správu (portál, kde se spravují nákupy Microsoft AppSource). Změna množství a plánu se dá aktivovat jenom z Centra pro správu.
Získání podpory
Možnosti podpory vydavatele najdete v tématu Podpora pro program komerčního marketplace v Partnerském centru .
Další kroky
- Další možnosti nabídek SaaS na komerčním marketplace najdete v rozhraních API služby měření komerčního marketplace.
- Zkontrolujte a používejte klienty pro různé programovací jazyky a ukázky.
- Podívejte se na následující videokursy:
Váš názor
Připravujeme: V průběhu roku 2024 budeme postupně vyřazovat problémy z GitHub coby mechanismus zpětné vazby pro obsah a nahrazovat ho novým systémem zpětné vazby. Další informace naleznete v tématu: https://aka.ms/ContentUserFeedback.
Odeslat a zobrazit názory pro