Rozhraní API předplatného plnění SaaS v2 na komerčním marketplace Microsoftu
Tento článek popisuje verzi 2 rozhraní API předplatného plnění SaaS.
Poznámka:
Abyste mohli volat rozhraní API předplatného plnění SaaS, musíte vytvořit autorizační token vydavatele pomocí správného ID prostředku. Informace o získání autorizačního tokenu vydavatele
Řešení potíží s zakoupeným předplatným
Koncový bod řešení umožňuje vydavateli vyměnit nákupní identifikační token z komerčního marketplace (označovaného jako token zakoupený, ale ještě neaktivovaný) na trvalé zakoupené ID předplatného SaaS a jeho podrobnosti.
Když se zákazník přesměruje na adresu URL cílové stránky partnera, předá se identifikační token zákazníka jako parametr tokenu v tomto volání adresy URL. Očekává se, že partner tento token použije a požádá o jeho vyřešení. Odpověď rozhraní RESOLVE API obsahuje ID předplatného SaaS a další podrobnosti k jedinečné identifikaci nákupu. Token poskytnutý voláním adresy URL cílové stránky je platný po dobu 24 hodin. Pokud platnost tokenu, který obdržíte, vypršela, doporučujeme koncovému uživateli poskytnout následující pokyny:
"Tento nákup se nám nepodařilo identifikovat. Znovu otevřete toto předplatné SaaS na webu Azure Portal nebo v centru Správa Microsoftu 365 a znovu vyberte Konfigurovat účet nebo Spravovat účet.
Volání rozhraní API pro řešení vrátí podrobnosti o předplatném a stav pro předplatná SaaS ve všech podporovaných stavech.
Post https://marketplaceapi.microsoft.com/api/saas/subscriptions/resolve?api-version=<ApiVersion>
Parametry dotazu:
| Parametr | Hodnota |
|---|---|
ApiVersion |
Použijte 31. 8. 2018. |
Hlavičky požadavku:
| Parametr | Hodnota |
|---|---|
content-type |
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á, vygeneruje se a zadává se v hlavičce odpovědi. |
x-ms-correlationid |
Jedinečná řetězcová hodnota 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 a zadává se v hlavičce odpovědi. |
authorization |
Jedinečný přístupový token, který identifikuje vydavatele, který provádí toto volání rozhraní API. Formát je "Bearer <access_token>" , když vydavatel načte hodnotu tokenu, jak je vysvětleno v části Získání tokenu na základě aplikace Microsoft Entra. |
x-ms-marketplace-token |
Parametr identifikačního tokenu nákupu, který se má vyřešit. Token se předá při volání adresy URL cílové stránky, když se zákazník přesměruje na web partnera SaaS (například: https://contoso.com/signup?token=<token><authorization_token>). Zakódovaná hodnota tokenu je součástí adresy URL cílové stránky, takže je potřeba ji dekódovat, než se použije jako parametr v tomto volání rozhraní API. Tady je příklad zakódovaného řetězce v adrese URL: contoso.com/signup?token=ab%2Bcd%2Fef, kde token je ab%2Bcd%2Fef. Dekódovaný token je stejný: Ab+cd/ef |
Kódy odpovědí:
Kód: 200 Vrátí jedinečné identifikátory předplatného SaaS založené na zadaném x-ms-marketplace-token kódu.
Příklad textu odpovědi:
{
"id": "<guid>", // purchased SaaS subscription ID
"subscriptionName": "Contoso Cloud Solution", // SaaS subscription name
"offerId": "offer1", // purchased offer ID
"planId": "silver", // purchased offer's plan ID
"quantity": 20, // number of purchased seats, might be empty if the plan is not per seat
"subscription": { // full SaaS subscription details, see Get Subscription APIs response body for full description
"id": "<guid>",
"publisherId": "contoso",
"offerId": "offer1",
"name": "Contoso Cloud Solution",
"saasSubscriptionStatus": " PendingFulfillmentStart ",
"beneficiary": {
"emailId": "test@test.com",
"objectId": "<guid>",
"tenantId": "<guid>",
"puid": "<ID of the user>"
},
"purchaser": {
"emailId": "test@test.com",
"objectId": "<guid>",
"tenantId": "<guid>",
"puid": "<ID of the user>"
},
"planId": "silver",
"term": {
"termUnit": "P1M",
"startDate": "2022-03-07T00:00:00Z", //This field is only available after the saas subscription is active.
"endDate": "2022-04-06T00:00:00Z" //This field is only available after the saas subscription is active.
},
"autoRenew": true/false,
"isTest": true/false,
"isFreeTrial": false,
"allowedCustomerOperations": <CSP purchases>["Read"] <All Others> ["Delete", "Update", "Read"],
"sandboxType": "None",
"lastModified": "0001-01-01T00:00:00", //[Deprecated] Do not use.
"quantity": 5,
"sessionMode": "None"
}
}
Kód: 400 Chybný požadavek. x-ms-marketplace-token chybí, je poškozený, neplatný nebo vypršela platnost.
Kód: 403 Zakázáno. Autorizační token je neplatný, vypršela jeho platnost nebo nebyl poskytnut. Žádost se pokouší o přístup k předplatnému SaaS pro nabídku, která byla publikovaná s jiným ID aplikace Microsoft Entra, než je id aplikace použité k vytvoření autorizačního tokenu.
Tato chyba je často příznakem nesprávného provedení registrace SaaS.
Kód: 500 Vnitřní chyba serveru. Zopakujte volání rozhraní API. Pokud chyba přetrvává, obraťte se na podporu Microsoftu.
Aktivace předplatného
Po nakonfigurování účtu SaaS pro koncového uživatele musí vydavatel volat rozhraní API pro aktivaci předplatného na straně Microsoftu. Zákazník se neúčtuje, pokud toto volání rozhraní API není úspěšné.
Post https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/activate?api-version=<ApiVersion>
Parametry dotazu:
| Parametr | Hodnota |
|---|---|
ApiVersion |
Použijte 31. 8. 2018. |
subscriptionId |
Jedinečný identifikátor zakoupeného předplatného SaaS. Toto ID se získá po překladu autorizačního tokenu komerčního marketplace pomocí rozhraní API pro překlad. |
Hlavičky požadavku:
| Parametr | Hodnota |
|---|---|
content-type |
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á, vygeneruje se a zadává se v hlavičce odpovědi. |
x-ms-correlationid |
Jedinečná řetězcová hodnota pro operaci v klientovi. Tento řetězec koreluje všechny události z operace klienta s událostmi na straně serveru. Pokud tato hodnota není zadaná, vygeneruje se a zadává se v hlavičce odpovědi. |
authorization |
Jedinečný přístupový token, který identifikuje vydavatele, který provádí toto volání rozhraní API. Formát je "Bearer <access_token>" , když vydavatel načte hodnotu tokenu, jak je vysvětleno v části Získání tokenu na základě aplikace Microsoft Entra. |
Kódy odpovědí:
Kód: 200 Žádost o aktualizaci předplatného a označení jako "Přihlášení k odběru" se přijímá. Nezávislí výrobci softwaru (ISV) můžou zkontrolovat stav předplatného po několika minutách (přečtěte si informace o operaci Get a zkontrolujte stav předplatného). Tím získáte konečnou odpověď, jestli se předplatné úspěšně aktualizovalo. Při přihlášení k odběru se automaticky odešle webhook "Odhlásit odběr".
Pro toto volání neexistuje žádný text odpovědi.
Kód: 400 Chybný požadavek: Ověření se nezdařilo.
- Předplatné SaaS je v pozastaveném stavu.
Kód: 403 Zakázáno. Autorizační token je neplatný, vypršela jeho platnost nebo nebyl poskytnut. Žádost se pokouší o přístup k předplatnému SaaS pro nabídku, která byla publikovaná s jiným ID aplikace Microsoft Entra, než je id aplikace použité k vytvoření autorizačního tokenu.
Tato chyba je často příznakem nesprávného provedení registrace SaaS.
Kód: 404 Nenalezena. Odběr SaaS je ve stavu Odhlášení odběru.
Kód: 500 Vnitřní chyba serveru. Zopakujte volání rozhraní API. Pokud chyba přetrvává, obraťte se na podporu Microsoftu.
Získání seznamu všech předplatných
Toto rozhraní API načte seznam všech zakoupených předplatných SaaS pro všechny nabídky, které vydavatel publikuje na komerčním marketplace. Vrátí se předplatná SaaS ve všech možných stavech. Odhlášené odběry předplatných SaaS se také vrátí, protože tyto informace se neodstraní na straně Microsoftu.
Rozhraní API vrátí stránkované výsledky 100 na stránku.
Dostat https://marketplaceapi.microsoft.com/api/saas/subscriptions?api-version=<ApiVersion>
Parametry dotazu:
| Parametr | Hodnota |
|---|---|
ApiVersion |
Použijte 31. 8. 2018. |
continuationToken |
Volitelný parametr. Pokud chcete načíst první stránku výsledků, nechte prázdné. K načtení další stránky použijte hodnotu vrácenou v @nextLink parametru. |
Hlavičky požadavku:
| Parametr | Hodnota |
|---|---|
content-type |
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á, vygeneruje se a zadává se v hlavičce odpovědi. |
x-ms-correlationid |
Jedinečná řetězcová hodnota 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á, vygeneruje se a zadává se v hlavičce odpovědi. |
authorization |
Jedinečný přístupový token, který identifikuje vydavatele, který provádí toto volání rozhraní API. Formát je "Bearer <access_token>" , když vydavatel načte hodnotu tokenu, jak je vysvětleno v části Získání tokenu na základě aplikace Microsoft Entra. |
Kódy odpovědí:
Kód: 200 Vrátí seznam všech existujících předplatných pro všechny nabídky provedené tímto vydavatelem na základě autorizačního tokenu vydavatele.
Příklad textu odpovědi:
{
"subscriptions": [
{
"id": "<guid>", // purchased SaaS subscription ID
"name": "Contoso Cloud Solution", // SaaS subscription name
"publisherId": "contoso", // publisher ID
"offerId": "offer1", // purchased offer ID
"planId": "silver", // purchased plan ID
"quantity": 10, // purchased amount of seats, is empty if plan is not per seat
"beneficiary": { // email address, user ID and tenant ID for which SaaS subscription was purchased.
"emailId": " test@contoso.com",
"objectId": "<guid>",
"tenantId": "<guid>",
"puid": "<ID of the user>"
},
"purchaser": { // email address, user ID and tenant ID that purchased the SaaS subscription. These could be different from beneficiary information for reseller (CSP) purchase
"emailId": " test@contoso.com",
"objectId": "<guid>",
"tenantId": "<guid>",
"puid": "<ID of the user>"
},
"term": { // The period for which the subscription was purchased.
"startDate": "2022-03-04T00:00:00Z", //format: YYYY-MM-DD. This is the date when the subscription was activated by the ISV and the billing started. This field is only available after the saas subscription is active.
"endDate": "2022-04-03T00:00:00Z", // This is the last day the subscription is valid. Unless stated otherwise, the automatic renew happens the next day. This field is only available after the saas subscription is active.
"termUnit": "P1M" // where P1M is monthly and P1Y is yearly. Also reflected in the startDate and endDate values
},
"autoRenew": true,
"allowedCustomerOperations": ["Read", "Update", "Delete"], // Indicates operations allowed on the SaaS subscription for beneficiary. For CSP-initiated purchases, this is always "Read" because the customer cannot update or delete subscription in this flow. Purchaser can perform all operations on the subscription.
"sessionMode": "None", // not relevant
"isFreeTrial": true, // true - the customer subscription is currently in free trial, false - the customer subscription is not currently in free trial. (Optional field -– if not returned, the value is false.)
"isTest": false, // not relevant
"sandboxType": "None", // not relevant
"saasSubscriptionStatus": "Subscribed" // Indicates the status of the operation. Can be one of the following: PendingFulfillmentStart, Subscribed, Suspended or Unsubscribed.
},
// next SaaS subscription details, might be a different offer
{
"id": "<guid1>",
"name": "Contoso Cloud Solution1",
"publisherId": "contoso",
"offerId": "offer2",
"planId": "gold",
"quantity": "",
"beneficiary": {
"emailId": " test@contoso.com",
"objectId": "<guid>",
"tenantId": "<guid>",
"puid": "<ID of the user>"
},
"purchaser": {
"emailId": "purchase@csp.com ",
"objectId": "<guid>",
"tenantId": "<guid>",
"puid": "<ID of the user>"
},
"term": {
"startDate": "2019-05-31", /This field is only available after the saas subscription is active.
"endDate": "2020-04-30", //This field is only available after the saas subscription is active.
"termUnit": "P1Y"
},
"autoRenew": false,
"allowedCustomerOperations": ["Read"],
"sessionMode": "None",
"isFreeTrial": false,
"isTest": false,
"sandboxType": "None",
"saasSubscriptionStatus": "Suspended"
}
],
"@nextLink": "https:// https://marketplaceapi.microsoft.com/api/saas/subscriptions/?continuationToken=%5b%7b%22token%22%3a%22%2bRID%3a%7eYeUDAIahsn22AAAAAAAAAA%3d%3d%23RT%3a1%23TRC%3a2%23ISV%3a1%23FPC%3aAgEAAAAQALEAwP8zQP9%2fFwD%2b%2f2FC%2fwc%3d%22%2c%22range%22%3a%7b%22min%22%3a%22%22%2c%22max%22%3a%2205C1C9CD673398%22%7d%7d%5d&api-version=2018-08-31" // url that contains continuation token to retrieve next page of the SaaS subscriptions list, if empty or absent, this is the last page. ISV can use this url as is to retrieve the next page or extract the value of continuation token from this url.
}
Pokud pro tohoto vydavatele nejsou nalezena žádná zakoupená předplatná SaaS, vrátí se prázdný text odpovědi.
Kód: 403 Zakázáno. Autorizační token je nedostupný, neplatný nebo vypršela jeho platnost.
Tato chyba je často příznakem nesprávného provedení registrace SaaS.
Kód: 500 Vnitřní chyba serveru. Zopakujte volání rozhraní API. Pokud chyba přetrvává, obraťte se na podporu Microsoftu.
Získat předplatné
Toto rozhraní API načte zadané zakoupené předplatné SaaS pro nabídku SaaS, kterou vydavatel publikuje na komerčním marketplace. Toto volání slouží k získání všech dostupných informací pro konkrétní předplatné SaaS podle ID, nikoli voláním rozhraní API, které se používá k získání seznamu všech předplatných.
Dostat https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>
Parametry dotazu:
| Parametr | Hodnota |
|---|---|
ApiVersion |
Použijte 31. 8. 2018. |
subscriptionId |
Jedinečný identifikátor zakoupeného předplatného SaaS. Toto ID se získá po překladu autorizačního tokenu komerčního marketplace pomocí rozhraní API pro překlad. |
Hlavičky požadavku:
| Parametr | Hodnota |
|---|---|
content-type |
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á, vygeneruje se a zadává se v hlavičce odpovědi. |
x-ms-correlationid |
Jedinečná řetězcová hodnota 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á, vygeneruje se a zadává se v hlavičce odpovědi. |
authorization |
Jedinečný přístupový token, který identifikuje vydavatele, který provádí toto volání rozhraní API. Formát je "Bearer <access_token>" , když vydavatel načte hodnotu tokenu, jak je vysvětleno v části Získání tokenu na základě aplikace Microsoft Entra. |
Kódy odpovědí:
Kód: 200 Vrátí podrobnosti o předplatném SaaS na základě poskytnutého předplatného subscriptionId .
Příklad textu odpovědi:
{
"id": "<guid>", // purchased SaaS subscription ID
"name": "Contoso Cloud Solution", // SaaS subscription name
"publisherId": "contoso", // publisher ID
"offerId": "offer1", // purchased offer ID
"planId": "silver", // purchased plan ID
"quantity": 10, // purchased amount of seats is empty if plan is not per seat
"beneficiary": { // email address, user ID and tenant ID for which SaaS subscription is purchased.
"emailId": "test@contoso.com",
"objectId": "<guid>",
"tenantId": "<guid>",
"puid": "<ID of the user>"
},
"purchaser": { // email address ,user ID and tenant ID that purchased the SaaS subscription. These could be different from beneficiary information for reseller (CSP) scenario
"emailId": "test@test.com",
"objectId": "<guid>",
"tenantId": "<guid>",
"puid": "<ID of the user>"
},
"allowedCustomerOperations": ["Read", "Update", "Delete"], // Indicates operations allowed on the SaaS subscription for beneficiary. For CSP-initiated purchases, this is always "Read" because the customer cannot update or delete subscription in this flow. Purchaser can perform all operations on the subscription.
"sessionMode": "None", // not relevant
"isFreeTrial": false, // true - the customer subscription is currently in free trial, false - the customer subscription is not currently in free trial. Optional field – if not returned the value is false.
"autoRenew": true,
"isTest": false, // not relevant
"sandboxType": "None", // not relevant
"created": "2022-03-01T22:59:45.5468572Z",
"lastModified": "0001-01-01T00:00:00", //[Deprecated] Do not use.
"saasSubscriptionStatus": " Subscribed ", // Indicates the status of the operation: PendingFulfillmentStart, Subscribed, Suspended or Unsubscribed.
"term": { // the period for which the subscription was purchased
"startDate": "2022-03-04T00:00:00Z", //format: YYYY-MM-DD. This is the date when the subscription was activated by the ISV and the billing started. This field is only available after the saas subscription is active.
"endDate": "2022-04-03T00:00:00Z", // This is the last day the subscription is valid. Unless stated otherwise, the automatic renew happens the next day. This field is only available after the saas subscription is active.
"termUnit": "P1M" //where P1M is monthly and P1Y is yearly. Also reflected in the startDate and endDate values.
}
}
Kód: 403 Zakázáno. Autorizační token je neplatný, vypršela jeho platnost nebo nebyl poskytnut. Žádost se pokouší o přístup k předplatnému SaaS pro nabídku, která je publikovaná s jiným ID aplikace Microsoft Entra, než je ta, která se používá k vytvoření autorizačního tokenu.
Tato chyba je často příznakem nesprávného provedení registrace SaaS.
Kód: 404 Nenalezena. Předplatné SaaS se zadaným předplatným subscriptionId se nenašlo.
Kód: 500 Vnitřní chyba serveru. Zopakujte volání rozhraní API. Pokud chyba přetrvává, obraťte se na podporu Microsoftu.
Seznam dostupných plánů
Toto rozhraní API načte všechny plány nabídky SaaS identifikované konkrétním nákupem subscriptionId této nabídky. Pomocí tohoto volání získáte seznam všech soukromých a veřejných plánů, které může příjemce předplatného SaaS aktualizovat pro toto předplatné. Vrácené plány jsou k dispozici ve stejné zeměpisné oblasti jako již zakoupený plán.
Toto volání vrátí seznam plánů, které jsou pro daného zákazníka k dispozici kromě už zakoupeného plánu. Seznam lze zobrazit koncovému uživateli na webu vydavatele. Koncový uživatel může plán předplatného změnit na libovolný z plánů ve vráceném seznamu. Změna plánu na plán, který není v seznamu, nefunguje.
Toto rozhraní API také načte aktivní ID privátní nabídky přidružené (pokud voláte rozhraní API s filtrem planId). Volání rozhraní API s filtrem planId zobrazuje identifikátory GUID ID aktivní privátní nabídky v těle odpovědi v uzlu sourceOffers. ID plánu předané v parametru filtru by se mělo shodovat s ID plánu zakoupeného zákazníkem.
Dostat https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/listAvailablePlans?api-version=<ApiVersion>&planId=<planId>
Parametry dotazu:
| Parametr | Hodnota |
|---|---|
ApiVersion |
Použijte 31. 8. 2018. |
subscriptionId |
Jedinečný identifikátor zakoupeného předplatného SaaS. Toto ID se získá po překladu autorizačního tokenu komerčního marketplace pomocí rozhraní API pro překlad. |
planId (Optional) |
ID plánu konkrétního plánu, který chcete načíst. Tato možnost je nepovinná a pokud se ignoruje, vrátí všechny plány. |
Hlavičky požadavku:
| Parametr | Hodnota |
|---|---|
content-type |
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á, vygeneruje se a zadává se v hlavičce odpovědi. |
x-ms-correlationid |
Jedinečná řetězcová hodnota 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á, vygeneruje se a zadává se v hlavičce odpovědi. |
authorization |
Jedinečný přístupový token, který identifikuje vydavatele, který provádí toto volání rozhraní API. Formát je "Bearer <access_token>" , když vydavatel načte hodnotu tokenu, jak je vysvětleno v části Získání tokenu na základě aplikace Microsoft Entra. |
Kódy odpovědí:
Kód: 200 Vrátí seznam všech dostupných plánů pro stávající předplatné SaaS, včetně už zakoupeného předplatného.
Předání neplatného (volitelného) id plánu vrátí prázdný seznam plánů.
Příklad textu odpovědi:
{
"plans": [
{
"planId": "Platinum001",
"displayName": "plan display name",
"isPrivate": true, //returns true for private plans and customized plans created within a private offer.
"description": "plan description",
"minQuantity": 5,
"maxQuantity": 100,
"hasFreeTrials": false,
"isPricePerSeat": true,
"isStopSell": false,
"market": "US",
"planComponents": {
"recurrentBillingTerms": [
{
"currency": "USD",
"price": 1,
"termUnit": "P1M",
"termDescription": "term description",
"meteredQuantityIncluded": [
{
"dimensionId": "Dimension001",
"units": "Unit001"
}
]
}
],
"meteringDimensions": [
{
"id": "MeteringDimension001",
"currency": "USD",
"pricePerUnit": 1,
"unitOfMeasure": "unitOfMeasure001",
"displayName": "unit of measure display name"
}
]
},
"sourceOffers": [ //sourceOffers is returned when planId is passed as filter parameter (note that this is the plan that customer has purchased).
{
"externalId": "<guid>" //private offer id, returned when purchase is made through private offer.
}
]
}
]
}
Kód: 404 Nenalezena.
subscriptionId nebyl nalezen.
Kód: 403 Zakázáno. Autorizační token je neplatný, vypršela jeho platnost nebo nebyl poskytnut. Žádost se může pokusit o přístup k předplatnému SaaS pro nabídku, která se odhlásila nebo publikovala s jiným ID aplikace Microsoft Entra, než které se použilo k vytvoření autorizačního tokenu.
Tato chyba je často příznakem nesprávného provedení registrace SaaS.
Kód: 500 Vnitřní chyba serveru. Zopakujte volání rozhraní API. Pokud chyba přetrvává, obraťte se na podporu Microsoftu.
Změna plánu předplatného
Toto rozhraní API slouží k aktualizaci stávajícího plánu zakoupeného pro předplatné SaaS na nový plán (veřejný nebo soukromý). Vydavatel musí toto rozhraní API volat, když se plán změní na straně vydavatele předplatného SaaS zakoupeného na komerčním marketplace.
Toto rozhraní API lze volat pouze pro aktivní předplatná. Jakýkoliv plán lze změnit na jakýkoli jiný existující plán (veřejný nebo soukromý), ale ne na sebe. V případě privátních plánů musí být tenant zákazníka definován jako součást cílové skupiny plánu v Partnerském centru.
Záplata https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>
Parametry dotazu:
| Parametr | Hodnota |
|---|---|
ApiVersion |
Použijte 31. 8. 2018. |
subscriptionId |
Jedinečný identifikátor zakoupeného předplatného SaaS. Toto ID se získá po překladu autorizačního tokenu komerčního marketplace pomocí rozhraní API pro překlad. |
Hlavičky požadavku:
| Parametr | Hodnota |
|---|---|
content-type |
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á, vygeneruje se a zadává se v hlavičce odpovědi. |
x-ms-correlationid |
Jedinečná řetězcová hodnota 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á, vygeneruje se a zadává se v hlavičce odpovědi. |
authorization |
Jedinečný přístupový token, který identifikuje vydavatele, který provádí toto volání rozhraní API. Formát je "Bearer <access_token>" , když vydavatel načte hodnotu tokenu, jak je vysvětleno v části Získání tokenu na základě aplikace Microsoft Entra. |
Příklad datové části požadavku:
{
"planId": "gold" // the ID of the new plan to be purchased
}
Kódy odpovědí:
Kód: 202 Požadavek na změnu plánu byl přijat a zpracován asynchronně. Očekává se, že se partner dotazuje na adresu URL umístění operace, aby určil úspěch nebo selhání žádosti o plán změn. Dotazování by se mělo provést každých několik sekund, dokud se pro operaci neobdrží konečný stav Selhání, Úspěch nebo Konflikt . Konečný stav operace by se měl rychle vrátit, ale v některých případech může trvat několik minut.
Partner dostane také oznámení webhooku, když je akce připravená k úspěšnému dokončení na straně komerčního marketplace. Teprve potom by měl vydavatel provést změnu plánu na straně vydavatele.
Hlavičky odpovědi:
| Parametr | Hodnota |
|---|---|
Operation-Location |
Adresa URL pro získání stavu operace Například https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=2018-08-31 |
Kód: 400 Chybný požadavek: selhání ověření.
- Nový plán neexistuje nebo není k dispozici pro toto konkrétní předplatné SaaS.
- Nový plán je stejný jako aktuální plán.
- Stav předplatného SaaS není přihlášený k odběru.
- Operace aktualizace pro předplatné SaaS není součástí
allowedCustomerOperations.
Kód: 403 Zakázáno. Autorizační token je neplatný, vypršela jeho platnost nebo nebyl poskytnut. Žádost se pokouší o přístup k předplatnému SaaS pro nabídku, která je publikovaná s jiným ID aplikace Microsoft Entra, než je ta, která se používá k vytvoření autorizačního tokenu.
Tato chyba je často příznakem nesprávného provedení registrace SaaS.
Kód: 404 Nenalezena. Předplatné SaaS se subscriptionId nenašlo.
Kód: 500 Vnitřní chyba serveru. Zopakujte volání rozhraní API. Pokud chyba přetrvává, obraťte se na podporu Microsoftu.
Poznámka:
Plán nebo množství licencí je možné změnit najednou, nikoli obojí.
Toto rozhraní API se dá volat až po získání explicitního schválení změny od koncového uživatele.
Změna počtu licencí v předplatném SaaS
Pomocí tohoto rozhraní API můžete aktualizovat (zvýšit nebo snížit) množství licencí zakoupených pro předplatné SaaS. Vydavatel musí toto rozhraní API volat, když se počet licencí změní ze strany vydavatele pro předplatné SaaS vytvořené na komerčním marketplace.
Množství licencí nemůže být vyšší než množství povolené v aktuálním plánu. V takovém případě by měl vydavatel změnit plán před změnou počtu licencí.
Záplata https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>
Parametry dotazu:
| Parametr | Hodnota |
|---|---|
ApiVersion |
Použijte 31. 8. 2018. |
subscriptionId |
Jedinečný identifikátor zakoupeného předplatného SaaS. Toto ID se získá po překladu autorizačního tokenu komerčního marketplace pomocí rozhraní API pro překlad. |
Hlavičky požadavku:
| Parametr | Hodnota |
|---|---|
content-type |
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á, vygeneruje se a zadává se v hlavičce odpovědi. |
x-ms-correlationid |
Jedinečná řetězcová hodnota 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á, vygeneruje se a zadává se v hlavičce odpovědi. |
authorization |
Jedinečný přístupový token, který identifikuje vydavatele, který provádí toto volání rozhraní API. Formát je "Bearer <access_token>" , když vydavatel načte hodnotu tokenu, jak je vysvětleno v části Získání tokenu na základě aplikace Microsoft Entra. |
Příklad datové části požadavku:
{
"quantity": 5 // the new amount of seats to be purchased
}
Kódy odpovědí:
Kód: 202 Požadavek na změnu množství byl přijat a zpracován asynchronně. Očekává se, že se partner dotazuje na adresu URL umístění operace, aby určil úspěch nebo selhání žádosti o množství změn. Dotazování by se mělo provést každých několik sekund, dokud se pro operaci neobdrží konečný stav Selhání, Úspěch nebo Konflikt . Konečný stav operace by se měl rychle vrátit, ale v některých případech může trvat několik minut.
Partner dostane také oznámení webhooku, když je akce připravená k úspěšnému dokončení na straně komerčního marketplace. Teprve potom by měl vydavatel provést změnu množství na straně vydavatele.
Hlavičky odpovědi:
| Parametr | Hodnota |
|---|---|
Operation-Location |
Propojením s prostředkem získáte stav operace. Například https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=2018-08-31. |
Kód: 400 Chybný požadavek: selhání ověření.
- Nové množství je větší nebo nižší než aktuální limit plánu.
- Chybí nové množství.
- Nové množství je stejné jako aktuální množství.
- Stav předplatného SaaS není přihlášený k odběru.
- Operace aktualizace pro předplatné SaaS není součástí
allowedCustomerOperations.
Kód: 403 Zakázáno. Autorizační token je neplatný, vypršela jeho platnost nebo nebyl poskytnut. Žádost se pokouší o přístup k předplatnému, které nepatří aktuálnímu vydavateli.
Tato chyba je často příznakem nesprávného provedení registrace SaaS.
Kód: 404 Nenalezena. Předplatné SaaS se subscriptionId nenašlo.
Kód: 500 Vnitřní chyba serveru. Zopakujte volání rozhraní API. Pokud chyba přetrvává, obraťte se na podporu Microsoftu.
Poznámka:
Najednou se dá změnit jenom plán nebo množství, ne obojí.
Toto rozhraní API lze volat až po získání explicitního schválení koncového uživatele pro změnu.
Zrušení předplatného:
Toto rozhraní API slouží k odhlášení odběru zadaného předplatného SaaS. Vydavatel nemusí používat toto rozhraní API a doporučujeme, aby zákazníci byli přesměrováni na komerční marketplace, aby zrušili předplatná SaaS.
Pokud se vydavatel rozhodne implementovat zrušení předplatného SaaS zakoupeného na komerčním marketplace na straně vydavatele, musí toto rozhraní API volat. Po dokončení tohoto hovoru se stav předplatného na straně Microsoftu zruší.
Zákazník se neúčtuje, pokud se předplatné zruší do 72 hodin od nákupu.
Zákazník se fakturuje, pokud se předplatné zruší po předchozím období odkladu. Zákazník okamžitě po zrušení ztratí přístup k předplatnému SaaS na straně Microsoftu.
Vymazat https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>
Parametry dotazu:
| Parametr | Hodnota |
|---|---|
ApiVersion |
Použijte 31. 8. 2018. |
subscriptionId |
Jedinečný identifikátor zakoupeného předplatného SaaS. Toto ID se získá po překladu autorizačního tokenu komerčního marketplace pomocí rozhraní API pro překlad. |
Hlavičky požadavku:
| Parametr | Hodnota |
|---|---|
content-type |
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á, vygeneruje se a zadává se v hlavičce odpovědi. |
x-ms-correlationid |
Jedinečná řetězcová hodnota 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á, vygeneruje se a zadává se v hlavičce odpovědi. |
authorization |
Jedinečný přístupový token, který identifikuje vydavatele, který provádí toto volání rozhraní API. Formát je "Bearer <access_token>" , když vydavatel načte hodnotu tokenu, jak je vysvětleno v části Získání tokenu na základě aplikace Microsoft Entra. |
Kódy odpovědí:
Kód: 202 Žádost o odhlášení odběru byla přijata a zpracována asynchronně. Očekává se, že se partner dotazuje na adresu URL umístění operace, aby určil úspěch nebo selhání tohoto požadavku. Dotazování by se mělo provést každých několik sekund, dokud se pro operaci neobdrží konečný stav Selhání, Úspěch nebo Konflikt . Konečný stav operace by se měl rychle vrátit, ale v některých případech může trvat několik minut.
Partner dostane také oznámení webhooku, když se akce úspěšně dokončí na straně komerčního marketplace. Teprve potom by vydavatel měl předplatné zrušit na straně vydavatele.
Kód: 200 Předplatné je již ve stavu Odhlášení odběru.
Hlavičky odpovědi:
| Parametr | Hodnota |
|---|---|
Operation-Location |
Propojením s prostředkem získáte stav operace. Například https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=2018-08-31. |
Kód: 400 Chybný požadavek. Odstranění není v allowedCustomerOperations seznamu pro toto předplatné SaaS.
Kód: 403 Zakázáno. Autorizační token je neplatný, vypršela jeho platnost nebo není k dispozici.
Tato chyba je často příznakem nesprávného provedení registrace SaaS.
Kód: 404 Nenalezena. Předplatné SaaS se subscriptionId nenašlo.
Kód: 409
Odstranění nelze dokončit, protože předplatné je uzamčené kvůli čekajícími operacím.
Kód: 500 Vnitřní chyba serveru. Zopakujte volání rozhraní API. Pokud chyba přetrvává, obraťte se na podporu Microsoftu.
Související obsah
- Další možnosti nabídek SaaS na komerčním marketplace najdete v rozhraních API služby měření komerčního marketplace.
- Kontrola a použití klientů pro různé programovací jazyky a ukázky
- Pokyny k testování najdete v tématu Implementace webhooku ve službě SaaS.
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