Webhook implementálása az SaaS szolgáltatásban
Amikor a Partnerközpontban létrehoz egy végrehajtható SaaS-ajánlatot, a partner megadja a HTTP-végpontként használandó Csatlakozás ion webhook URL-címét. Ezt a webhookot a Microsoft a POST HTTP-hívással hívja meg, hogy értesítse a közzétevőt a Következő eseményekről, amelyek a Microsoft oldalán történnek:
| Webhook esemény | 1. Fogadáskor | 2. Ha elfogadják | 3. Elutasítás esetén |
|---|---|---|---|
ChangePlan |
Válasz HTTP 200-nal | PATCH sikerrel (ez az esemény nem kötelező, és 10 másodperc alatt automatikusan elérhető) | JAVÍTÁS hibával VAGY válasz 4xx-el (10 másodpercen belül) |
ChangeQuantity |
Válasz HTTP 200-nal | PATCH sikerrel (ez az esemény nem kötelező, és 10 másodperc alatt automatikusan elérhető) | JAVÍTÁS hibával VAGY válasz 4xx-el (10 másodpercen belül) |
Renew |
Válasz HTTP 200-nal | Nem alkalmazható | Nem alkalmazható |
Suspend |
Válasz HTTP 200-nal | Nem alkalmazható | Nem alkalmazható |
Unsubscribe |
Válasz HTTP 200-nal | Nem alkalmazható | Nem alkalmazható |
Reinstate |
Válasz HTTP 200-nal | Nem alkalmazható | Nem alkalmazható (a törlési API meghívása törlés aktiválásához, ha az újbóli visszaállítás nem fogadható el) |
A közzétevőnek webhookot kell implementálnia az SaaS szolgáltatásban, hogy az SaaS-előfizetés állapota konzisztens legyen a Microsoft oldalával. Az SaaS szolgáltatásnak meg kell hívnia a Get Operation API-t, hogy ellenőrizze és engedélyezze a webhook hívási és hasznos adatadatait, mielőtt a webhookértesítés alapján műveletet hajt végre. A közzétevőnek a webhookhívás feldolgozása után azonnal vissza kell adnia a HTTP 200-as értéket a Microsoftnak. Ez az érték elismeri, hogy a webhook-hívást sikeresen fogadta a közzétevő.
Fontos
A webhook URL-szolgáltatásának 24 x 7-et kell futtatnia, és készen kell állnia arra, hogy mindig új hívásokat fogadjon a Microsofttól. A Microsoftnak van egy újrapróbálkozási szabályzata a webhookhíváshoz (500 újrapróbálkozás nyolc órán keresztül), de ha a közzétevő nem fogadja el a hívást, és választ ad vissza, a webhook által küldött művelet végül meghiúsul a Microsoft oldalán.
Fontos
Az ISV-knek kerülnie kell a Webhook-séma szigorú deszerializálását. A Microsoft fenntartja a jogot, hogy a jövőben bővítse a sémát.
Fontos
Az ISV-knek ellenőrizniük kell a Microsoft Entra Tokent (JWT Token) a webhook végpontján a kérés fejlécéből. Ez egy szabványos tulajdonosi jogkivonat, amely részletes információkat ad az ISV-nek arról, hogy ki a hívó. További információ a jogkivonat érvényesítéséről ebben a cikkben. learn.microsoft.com/azure/active-directory/develop/access-tokens
A Webhook hasznos adatokra vonatkozó példája a ChangePlannak:
{
"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
}
A Webhook hasznos adatainak példája a ChangeQuantity eseményre:
{
"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
}
A Webhook hasznos adatokra vonatkozó példája egy előfizetés visszaállítására vonatkozó eseménynek:
// 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
}
Webhook hasznos adatokra vonatkozó példa egy megújítási eseményre:
// 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,
}
Webhook hasznos adatokra vonatkozó példa felfüggesztési eseményre:
{
"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,
}
Webhook payload example of an unsubscribe event:
Ez csak értesítési esemény. Ehhez az eseményhez nincs küldés az ACK-nek.
{
"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,
}
Webhookok védelme
Biztonságossá kell tennie a webhookokat, hogy a Microsoft-végpontokon kívül senki más ne kezdeményezhesse ezeket a Webhook-hívásokat. A webhookok implementálásához bármilyen technológiát használhat, azonban a Webhook implementációjának az alábbi biztonsági irányelveket kell követnie.
A Microsoft engedélyezési fejlécekkel hívja meg a webhookokat, amelyek a hívások ellenőrzéséhez szükséges információkat tartalmazzák. Engedélyeznie kell a webhookok számára az engedélyezési fejlécek fogadását. (Ne adjon hozzá engedélyezési adatokat vagy biztonsági jogkivonatokat, például SAS-jogkivonatokat közvetlenül a webhook URL-címeiben. Előfordulhat, hogy az ilyen webhookok nem kérik le a Microsoft által a webhookok hívása során küldött engedélyezési fejléceket.
Az Engedélyezési fejlécben átadott JWT Bearer-jogkivonat a következő adatokat tartalmazza a hasznos adatokban, amelyekkel biztonságossá teheti a végpontokat.
"aud": "ez a Microsoft Entra Identity alkalmazásazonosító, amelyet hozzáad az ajánlat műszaki konfigurációjához a Microsoft Partnerközpontban"
"appid" vagy "azp": Ezt az erőforrás-azonosítót használja a közzétevő engedélyezési jogkivonatának létrehozásakor az SaaS fulfillment API-k meghívásához. Az alkalmazás beállításától függően az erőforrás-azonosító értéke "appid" vagy "azp" lehet. A jogkivonat a két jogcím valamelyikével rendelkezik, és ennek megfelelően kell reagálnia a kódban.
"tid": "ez a Microsoft Entra-bérlőazonosító, amelyet hozzáad az ajánlat műszaki konfigurációjához a Microsoft Partnerközpontban"
A fenti átadott mezők alapján ellenőrizheti, hogy a Webhook-hívás érvényes-e.
Fontos
A Microsoft megköveteli, hogy az isv-k biztonságos módon hozzák létre a webhookokat, és elfogadják az engedélyezési fejléceket. Ha a jelenlegi Webhook-implementáció nem tudja elfogadni az engedélyezési fejléceket, frissítenie kell a webhookokat, és biztonságossá kell tennie ezeket a végpontokat (a fenti irányelvek alapján), hogy elkerülje a fennakadásokat.
Fejlesztés és tesztelés
A fejlesztési folyamat elindításához javasoljuk, hogy hozzon létre hamis API-válaszokat a közzétevő oldalán. Ezek a válaszok a cikkben megadott mintaválaszokon alapulhatnak.
Ha a közzétevő készen áll a végpontok közötti tesztelésre:
- Közzétehet egy SaaS-ajánlatot egy korlátozott előzetes verziójú közönségnek, és megtarthatja az előzetes verzióban.
- Állítsa a csomag árát nullára, hogy a tesztelés során ne aktiválja a tényleges számlázási költségeket. Egy másik lehetőség a nonzero ár beállítása és az összes tesztvásárlás lemondása 24 órán belül.
- Győződjön meg arról, hogy az összes folyamat végpontok közötti meghívása valós ügyfélforgatókönyv szimulálásához szükséges.
- Ha a partner szeretné tesztelni a teljes vásárlási és számlázási folyamatot, tegye ezt a 0 usd feletti ajánlattal. A vásárlás kiszámlázva lesz, és a rendszer létrehoz egy számlát.
A vásárlási folyamat az Azure Portalról vagy a Microsoft AppSource-webhelyekről indítható el attól függően, hogy az ajánlat hol van közzétéve.
A terv módosítása, a mennyiség módosítása és a leiratkozási műveletek tesztelése a közzétevő oldalról végezhető. A Microsoft részéről a leiratkozás az Azure Portalról és a Rendszergazda központból is aktiválható (az a portál, ahol a Microsoft AppSource-vásárlásokat kezelik). A mennyiség és a terv módosítása csak a Rendszergazda Központból indítható el.
Támogatás kérése
A közzétevők támogatási lehetőségeiről a Partnerközpont kereskedelmi piactér programjának támogatása című témakörben olvashat.
Következő lépések
- Az SaaS-ajánlatokra vonatkozó további lehetőségekért tekintse meg a kereskedelmi piactér mérési szolgáltatás API-jait a kereskedelmi piactéren.
- Tekintse át és használja az ügyfeleket különböző programozási nyelvekhez és mintákhoz.
- Tekintse meg az alábbi oktatóvideókat:
Visszajelzés
Hamarosan elérhető: 2024-ben fokozatosan kivezetjük a GitHub-problémákat a tartalom visszajelzési mechanizmusaként, és lecseréljük egy új visszajelzési rendszerre. További információ: https://aka.ms/ContentUserFeedback.
Visszajelzés küldése és megtekintése a következőhöz: