Sdílet prostřednictvím

Rozhraní API pro operace plnění SaaS v2 na komerčním marketplace Microsoftu

  • Článek

Poznámka

Abyste mohli volat rozhraní API operací plnění SaaS, musíte vytvořit autorizační token vydavatele pomocí správného ID prostředku. Zjistěte, jak získat autorizační token vydavatele

Tento článek popisuje verzi 2 rozhraní API pro operace plnění SaaS.

Operace jsou užitečné k reagování na všechny požadavky, které procházejí webhookem jako součást akcí ChangePlan, ChangeQuantity a Reinstate. To poskytuje příležitost přijmout nebo odmítnout požadavek pomocí opravy operace webhooku s úspěchem nebo selháním pomocí následujících rozhraní API.

To platí jenom pro události webhooku, jako jsou ChangePlan, ChangeQuantity a Reinstate, které potřebují ACK. U nezávislého dodavatele softwaru (ISV) není potřeba provádět žádné akce týkající se událostí prodloužení, pozastavení a odhlášení odběru, protože se jedná o události pouze pro oznámení.

Výpis nevyřízených operací

Získejte seznam čekajících operací pro zadané předplatné SaaS. Vydavatel by měl potvrdit vrácené operace voláním rozhraní API oprav operací.

Získání https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations?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 Formát se "Bearer <access_token>" při načtení hodnoty tokenu vydavatelem, jak je vysvětleno v Získání tokenu na základě aplikace Microsoft Entra.

kódy odpovědí :

Kód: 200 Vrátí čekající operace se zadaným předplatným SaaS.

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

{
  "operations": [
    {
      "id": "<guid>", //Operation ID, should be provided in the operations patch API call
      "activityId": "<guid>", //not relevant
      "subscriptionId": "<guid>", // subscriptionId of the SaaS subscription that is being reinstated
      "offerId": "offer1", // purchased offer ID
      "publisherId": "contoso",
      "planId": "silver", // purchased plan ID
      "quantity": 20, // purchased amount of seats, will be empty is not relevant
      "action": "Reinstate",
      "timeStamp": "2018-12-01T00:00:00", // UTC
      "status": "InProgress" // the only status that can be returned in this case
    }
  ]
}

Vrátí prázdný kód JSON, pokud nejsou čekající žádné operace.

Kód: 400 Chybný požadavek: selhání ověření.

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.

Tato chyba je často příznakem, že správně neprovádí registraci SaaS.

Kód: 404 Nenalezena. Předplatné SaaS s 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.

Získání stavu operace

Toto rozhraní API umožňuje vydavateli sledovat stav zadané asynchronní operace: odhlásit odběr, ChangePlannebo ChangeQuantity.

operationId pro toto volání rozhraní API lze načíst z hodnoty vrácené umístěním operace, voláním rozhraní API pro čekající operace nebo hodnotou parametru <id> přijatou ve volání webhooku.

Získání https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?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.
operationId Jedinečný identifikátor operace, která se načítá.

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 se "Bearer <access_token>" při načtení hodnoty tokenu vydavatelem, jak je vysvětleno v Získání tokenu na základě aplikace Microsoft Entra.

kódy odpovědí :

Kód: 200 Získá podrobnosti pro zadanou operaci SaaS.

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

Response body:
{
  "id  ": "<guid>", //Operation ID, should be provided in the patch operation API call
  "activityId": "<guid>", //not relevant
  "subscriptionId": "<guid>", // subscriptionId of the SaaS subscription for which this operation is relevant
  "offerId": "offer1", // purchased offer ID
  "publisherId": "contoso",
  "planId": "silver", // purchased plan ID
  "quantity": 20, // purchased amount of seats
  "action": "ChangePlan", // Can be ChangePlan, ChangeQuantity or Reinstate
  "timeStamp": "2018-12-01T00:00:00", // UTC
  "status": "InProgress", // Possible values: NotStarted, InProgress, Failed, Succeeded, Conflict (new quantity / plan is the same as existing)
  "errorStatusCode": "",
  "errorMessage": ""
}

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.

Tato chyba je často příznakem, že správně neprovádí registraci SaaS.

Kód: 404 Nenalezena.

  • Předplatné s subscriptionId se nenašlo.
  • Operace s operationId nebyla nalezena.

Kód: 500 Vnitřní chyba serveru. Zopakujte volání rozhraní API. Pokud chyba přetrvává, obraťte se na podporu Microsoftu.

Aktualizace stavu operace

Pomocí tohoto rozhraní API můžete aktualizovat stav čekající operace tak, aby značil úspěch nebo selhání operace na straně vydavatele.

operationId pro toto volání rozhraní API lze načíst z hodnoty vrácené umístěním operace, voláním rozhraní API pro čekající operace nebo hodnotou parametru <id> přijatou ve volání webhooku.

https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=<ApiVersion> oprav

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.
operationId Jedinečný identifikátor dokončené operace.

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 se "Bearer <access_token>" při načtení hodnoty tokenu vydavatelem, jak je vysvětleno v Získání tokenu na základě aplikace Microsoft Entra.

Příklad datové části požadavku :

{
  "status": "Success" // Allowed Values: Success/Failure. Indicates the status of the operation on ISV side.
}

kódy odpovědí :

Kód: 200 Volání informuje o dokončení operace na straně partnera. Tato odpověď může například signalizovat dokončení změny licencí nebo plánů na straně vydavatele.

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.

Tato chyba je často příznakem, že správně neprovádí registraci SaaS.

Kód: 404 Nenalezena.

  • Předplatné s subscriptionId se nenašlo.
  • Operace s operationId nebyla nalezena.

Kód: Konflikt 409. Například novější aktualizace je již splněna.

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