Interfejsy API operacji realizacji SaaS w wersji 2 na komercyjnej platformie handlowej firmy Microsoft

  • Artykuł

W tym artykule opisano wersję 2 interfejsów API operacji realizacji SaaS.

Operacje są przydatne do odpowiadania na wszelkie żądania przechodzące przez element webhook w ramach akcji ChangePlan, ChangeQuantity i Reinstate. Zapewnia to możliwość zaakceptowania lub odrzucenia żądania przez poprawkę operacji elementu webhook z powodzeniem lub niepowodzeniem przy użyciu poniższych interfejsów API.

Dotyczy to tylko zdarzeń elementu webhook, takich jak ChangePlan, ChangeQuantity i Reinstate, które wymagają usługi ACK. Nie jest wymagana żadna akcja od niezależnego dostawcy oprogramowania (ISV) w przypadku zdarzeń odnawiania, wstrzymania i anulowania subskrypcji, ponieważ są one zdarzeniami tylko powiadamiania.

Wyświetlanie listy zaległych operacji

Pobierz listę oczekujących operacji dla określonej subskrypcji SaaS. Wydawca powinien potwierdzić zwrócone operacje przez wywołanie interfejsu API poprawki operacji.

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

Parametry zapytania:

Parametr Wartość
ApiVersion Użyj 2018-08-31.
subscriptionId Unikatowy identyfikator zakupionej subskrypcji SaaS. Ten identyfikator jest uzyskiwany po rozpoznaniu tokenu autoryzacji komercyjnej platformy handlowej przy użyciu interfejsu API rozpoznawania.

Nagłówki żądań:

Parametr Wartość
content-type application/json
x-ms-requestid Unikatowa wartość ciągu do śledzenia żądania od klienta, najlepiej identyfikator GUID. Jeśli ta wartość nie zostanie podana, zostanie wygenerowana i podana w nagłówkach odpowiedzi.
x-ms-correlationid Unikatowa wartość ciągu dla operacji na kliencie. Ten parametr koreluje wszystkie zdarzenia z operacji klienta ze zdarzeniami po stronie serwera. Jeśli ta wartość nie zostanie podana, zostanie wygenerowana i podana w nagłówkach odpowiedzi.
authorization Format jest "Bearer <access_token>" taki, gdy wartość tokenu jest pobierana przez wydawcę, jak wyjaśniono w artykule Uzyskiwanie tokenu na podstawie aplikacji Microsoft Entra.

Kody odpowiedzi:

Kod: 200 Zwraca oczekujące operacje w określonej subskrypcji SaaS.

Przykład ładunku odpowiedzi:

{
  "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
    }
  ]
}

Zwraca pusty kod JSON, jeśli żadne operacje nie są oczekujące.

Kod: 400 Nieprawidłowe żądanie: niepowodzenia walidacji.

Kod: 403 Zabronione. Token autoryzacji jest nieprawidłowy, wygasł lub nie został podany. Żądanie próbuje uzyskać dostęp do subskrypcji SaaS dla oferty opublikowanej przy użyciu innego identyfikatora aplikacji Microsoft Entra z tej, która została użyta do utworzenia tokenu autoryzacji.

Ten błąd jest często objawem nieprawidłowego wykonania rejestracji SaaS.

Kod: 404 Nie znaleziono. Nie można odnaleźć subskrypcji SaaS z subscriptionId programem .

Kod: 500 Wewnętrzny błąd serwera. Ponów próbę wywołania interfejsu API. Jeśli błąd będzie się powtarzać, skontaktuj się z pomocą techniczną firmy Microsoft.

Uzyskiwanie stanu operacji

Ten interfejs API umożliwia wydawcy śledzenie stanu określonej operacji asynchronicznych: Anulowanie subskrypcji, Plan zmian lub ChangeQuantity.

Dla operationId tego wywołania interfejsu API można pobrać wartość zwróconą przez operację-lokalizację, wywołanie interfejsu API oczekujące operacje lub wartość parametru <id> odebraną w wywołaniu elementu webhook.

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

Parametry zapytania:

Parametr Wartość
ApiVersion Użyj 2018-08-31.
subscriptionId Unikatowy identyfikator zakupionej subskrypcji SaaS. Ten identyfikator jest uzyskiwany po rozpoznaniu tokenu autoryzacji komercyjnej platformy handlowej przy użyciu interfejsu API rozpoznawania.
operationId Unikatowy identyfikator pobieranej operacji.

Nagłówki żądań:

Parametr Wartość
content-type application/json
x-ms-requestid Unikatowa wartość ciągu do śledzenia żądania od klienta, najlepiej identyfikator GUID. Jeśli ta wartość nie zostanie podana, zostanie wygenerowana i podana w nagłówkach odpowiedzi.
x-ms-correlationid Unikatowa wartość ciągu dla operacji na kliencie. Ten parametr koreluje wszystkie zdarzenia z operacji klienta ze zdarzeniami po stronie serwera. Jeśli ta wartość nie zostanie podana, zostanie wygenerowana i podana w nagłówkach odpowiedzi.
authorization Unikatowy token dostępu identyfikujący wydawcę wykonującego to wywołanie interfejsu API. Format jest "Bearer <access_token>" taki, gdy wartość tokenu jest pobierana przez wydawcę, jak wyjaśniono w artykule Uzyskiwanie tokenu na podstawie aplikacji Microsoft Entra.

Kody odpowiedzi:

Kod: 200 Pobiera szczegóły dla określonej operacji SaaS.

Przykład ładunku odpowiedzi:

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": ""
}

Kod: 403 Zabronione. Token autoryzacji jest nieprawidłowy, wygasł lub nie został podany. Żądanie próbuje uzyskać dostęp do subskrypcji SaaS dla oferty opublikowanej przy użyciu innego identyfikatora aplikacji Microsoft Entra z tej, która została użyta do utworzenia tokenu autoryzacji.

Ten błąd jest często objawem nieprawidłowego wykonania rejestracji SaaS.

Kod: 404 Nie znaleziono.

  • Nie można odnaleźć subskrypcji z subscriptionId programem .
  • Operacja z elementem operationId nie zostanie znaleziona.

Kod: 500 Wewnętrzny błąd serwera. Ponów próbę wywołania interfejsu API. Jeśli błąd będzie się powtarzać, skontaktuj się z pomocą techniczną firmy Microsoft.

Aktualizowanie stanu operacji

Użyj tego interfejsu API, aby zaktualizować stan oczekującej operacji, aby wskazać powodzenie lub niepowodzenie operacji po stronie wydawcy.

Dla operationId tego wywołania interfejsu API można pobrać wartość zwróconą przez operację-lokalizację, wywołanie interfejsu API oczekujące operacje lub wartość parametru <id> odebraną w wywołaniu elementu webhook.

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

Parametry zapytania:

Parametr Wartość
ApiVersion Użyj 2018-08-31.
subscriptionId Unikatowy identyfikator zakupionej subskrypcji SaaS. Ten identyfikator jest uzyskiwany po rozpoznaniu tokenu autoryzacji komercyjnej platformy handlowej przy użyciu interfejsu API rozpoznawania.
operationId Unikatowy identyfikator wykonywanej operacji.

Nagłówki żądań:

Parametr Wartość
content-type application/json
x-ms-requestid Unikatowa wartość ciągu do śledzenia żądania od klienta, najlepiej identyfikator GUID. Jeśli ta wartość nie zostanie podana, zostanie wygenerowana i podana w nagłówkach odpowiedzi.
x-ms-correlationid Unikatowa wartość ciągu dla operacji na kliencie. Ten parametr koreluje wszystkie zdarzenia z operacji klienta ze zdarzeniami po stronie serwera. Jeśli ta wartość nie zostanie podana, zostanie wygenerowana i podana w nagłówkach odpowiedzi.
authorization Unikatowy token dostępu identyfikujący wydawcę, który wykonuje to wywołanie interfejsu API. Format jest "Bearer <access_token>" taki, gdy wartość tokenu jest pobierana przez wydawcę, jak wyjaśniono w artykule Uzyskiwanie tokenu na podstawie aplikacji Microsoft Entra.

Przykład ładunku żądania:

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

Kody odpowiedzi:

Kod: 200 Wywołanie w celu poinformowania o zakończeniu operacji po stronie partnera. Na przykład ta odpowiedź może sygnalizować zakończenie zmiany miejsc lub planów po stronie wydawcy.

Kod: 403

  • Zakazane. Token autoryzacji jest niedostępny, jest nieprawidłowy lub wygasł. Żądanie może próbować uzyskać dostęp do subskrypcji, która nie należy do bieżącego wydawcy.
  • Zakazane. Token autoryzacji jest nieprawidłowy, wygasł lub nie został podany. Żądanie próbuje uzyskać dostęp do subskrypcji SaaS dla oferty opublikowanej przy użyciu innego identyfikatora aplikacji Microsoft Entra z tej, która została użyta do utworzenia tokenu autoryzacji.

Ten błąd jest często objawem nieprawidłowego wykonania rejestracji SaaS.

Kod: 404 Nie znaleziono.

  • Nie można odnaleźć subskrypcji z subscriptionId programem .
  • Operacja z elementem operationId nie zostanie znaleziona.

Kod: 409 Konflikt. Na przykład nowsza aktualizacja jest już spełniona.

Kod: 500 Wewnętrzny błąd serwera. Ponów próbę wywołania interfejsu API. Jeśli błąd będzie się powtarzać, skontaktuj się z pomocą techniczną firmy Microsoft.

Następne kroki