Freigeben über

SaaS-Erfüllungsvorgänge APIs v2 im kommerziellen Microsoft Marketplace

  • Artikel

Anmerkung

Um SaaS-Erfüllungsvorgänge-APIs aufrufen zu können, müssen Sie das Autorisierungstoken eines Herausgebers mithilfe der richtigen Ressourcen-ID erstellen. Erfahren Sie, wie Sie das Autorisierungstoken des Herausgebers

In diesem Artikel wird Version 2 der SaaS-Erfüllungsvorgänge-APIs beschrieben.

Vorgänge sind nützlich, um auf alle Anforderungen zu reagieren, die im Rahmen von ChangePlan-, ChangeQuantity- und Reinstate-Aktionen über den Webhook erfolgen. Dies bietet die Möglichkeit, eine Anforderung per Patch mit Erfolg oder Fehler mithilfe der folgenden APIs zu akzeptieren oder abzulehnen.

Dies gilt nur für Webhook-Ereignisse wie ChangePlan, ChangeQuantity und Reinstate, die eine ACK benötigen. Es ist keine Aktion des unabhängigen Softwareanbieters (ISV) für Die Ereignisse "Renew", "Suspend" und "Unsubscribe" erforderlich, da sie nur Benachrichtigungsereignisse sind.

Ausstehende Vorgänge auflisten

Ruft eine Liste der ausstehenden Vorgänge für das angegebene SaaS-Abonnement ab. Der Herausgeber sollte zurückgegebene Vorgänge durch Aufrufen der Operation Patch-APIbestätigen.

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

Abfrageparameter:

Parameter Wert
ApiVersion Verwenden Sie 2018-08-31.
subscriptionId Der eindeutige Bezeichner des erworbenen SaaS-Abonnements. Diese ID wird nach dem Auflösen des kommerziellen Marketplace-Autorisierungstokens mithilfe der Resolve-API abgerufen.

Anforderungsheader:

Parameter Wert
content-type application/json
x-ms-requestid Ein eindeutiger Zeichenfolgenwert zum Nachverfolgen der Anforderung vom Client, vorzugsweise eine GUID. Wenn dieser Wert nicht angegeben wird, wird ein Wert generiert und in den Antwortheadern bereitgestellt.
x-ms-correlationid Ein eindeutiger Zeichenfolgenwert für den Vorgang auf dem Client. Dieser Parameter korreliert alle Ereignisse vom Clientvorgang mit Ereignissen auf der Serverseite. Wenn dieser Wert nicht angegeben wird, wird ein Wert generiert und in den Antwortheadern bereitgestellt.
authorization Das Format wird "Bearer <access_token>", wenn der Tokenwert vom Herausgeber abgerufen wird, wie in Abrufen eines Tokens basierend auf der Microsoft Entra-App.

Antwortcodes:

Code: 200 Gibt ausstehende Vorgänge für das angegebene SaaS-Abonnement zurück.

Beispiel für Antwortnutzlast:

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

Gibt leere JSON zurück, wenn keine Vorgänge ausstehen.

Code: 400 Ungültige Anforderung: Überprüfungsfehler.

Code: 401 Nicht autorisiert. Das Autorisierungstoken ist ungültig oder abgelaufen. Die Anforderung versucht, auf ein SaaS-Abonnement für ein Angebot zuzugreifen, das mit einer anderen Microsoft Entra-App-ID veröffentlicht wurde, die zum Erstellen des Authentifizierungstokens verwendet wurde.

Code: 403 Verboten. Das Autorisierungstoken ist ungültig, wurde nicht bereitgestellt oder mit unzureichenden Berechtigungen bereitgestellt. Stellen Sie sicher, dass Sie ein gültiges Autorisierungstoken angeben.

Dieser Fehler ist häufig ein Symptom dafür, dass die SaaS-Registrierung ordnungsgemäß ausgeführt wird.

Code: 404 Nicht gefunden. Das SaaS-Abonnement mit subscriptionId wurde nicht gefunden.

Code: 500 Interner Serverfehler. Wiederholen Sie den API-Aufruf. Wenn der Fehler weiterhin besteht, wenden Sie sich an Microsoft-Support.

Vorgangsstatus abrufen

Diese API ermöglicht es dem Herausgeber, den Status des angegebenen asynchronen Vorgangs nachzuverfolgen: Unsubscribe, ChangePlanoder ChangeQuantity.

Die operationId für diesen API-Aufruf kann aus dem von Operation-Locationzurückgegebenen Wert abgerufen werden, dem Aufruf der api zum Abrufen ausstehender Vorgänge oder des <id> Parameterwerts, der in einem Webhook-Aufruf empfangen wird.

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

Abfrageparameter:

Parameter Wert
ApiVersion Verwenden Sie 2018-08-31.
subscriptionId Der eindeutige Bezeichner des erworbenen SaaS-Abonnements. Diese ID wird nach dem Auflösen des kommerziellen Marketplace-Autorisierungstokens mithilfe der Resolve-API abgerufen.
operationId Der eindeutige Bezeichner des abzurufenden Vorgangs.

Anforderungsheader:

Parameter Wert
content-type application/json
x-ms-requestid Ein eindeutiger Zeichenfolgenwert zum Nachverfolgen der Anforderung vom Client, vorzugsweise eine GUID. Wenn dieser Wert nicht angegeben wird, wird ein Wert generiert und in den Antwortheadern bereitgestellt.
x-ms-correlationid Ein eindeutiger Zeichenfolgenwert für den Vorgang auf dem Client. Dieser Parameter korreliert alle Ereignisse vom Clientvorgang mit Ereignissen auf der Serverseite. Wenn dieser Wert nicht angegeben wird, wird ein Wert generiert und in den Antwortheadern bereitgestellt.
authorization Ein eindeutiges Zugriffstoken, das den Herausgeber identifiziert, der diesen API-Aufruf vornimmt. Das Format wird "Bearer <access_token>", wenn der Tokenwert vom Herausgeber abgerufen wird, wie in Abrufen eines Tokens basierend auf der Microsoft Entra-App.

Antwortcodes:

Code: 200 Ruft Details für den angegebenen SaaS-Vorgang ab.

Beispiel für Antwortnutzlast:

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

Code: 401 Nicht autorisiert. Das Autorisierungstoken ist ungültig oder abgelaufen. Die Anforderung versucht, auf ein SaaS-Abonnement für ein Angebot zuzugreifen, das mit einer anderen Microsoft Entra-App-ID veröffentlicht wurde, die zum Erstellen des Authentifizierungstokens verwendet wurde.

Code: 403 Verboten. Das Autorisierungstoken ist ungültig, wurde nicht bereitgestellt oder mit unzureichenden Berechtigungen bereitgestellt. Stellen Sie sicher, dass Sie ein gültiges Autorisierungstoken angeben.

Dieser Fehler ist häufig ein Symptom dafür, dass die SaaS-Registrierung ordnungsgemäß ausgeführt wird.

Code: 404 Nicht gefunden.

  • Das Abonnement mit subscriptionId wurde nicht gefunden.
  • Der Vorgang mit operationId wurde nicht gefunden.

Code: 500 Interner Serverfehler. Wiederholen Sie den API-Aufruf. Wenn der Fehler weiterhin besteht, wenden Sie sich an Microsoft-Support.

Aktualisieren des Status eines Vorgangs

Verwenden Sie diese API, um den Status eines ausstehenden Vorgangs zu aktualisieren, um den Erfolg oder Fehler des Vorgangs auf der Herausgeberseite anzugeben.

Die operationId für diesen API-Aufruf kann aus dem von Operation-Locationzurückgegebenen Wert abgerufen werden, dem Aufruf der api zum Abrufen ausstehender Vorgänge oder des <id> Parameterwerts, der in einem Webhook-Aufruf empfangen wird.

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

Abfrageparameter:

Parameter Wert
ApiVersion Verwenden Sie 2018-08-31.
subscriptionId Der eindeutige Bezeichner des erworbenen SaaS-Abonnements. Diese ID wird nach dem Auflösen des kommerziellen Marketplace-Autorisierungstokens mithilfe der Resolve-API abgerufen.
operationId Der eindeutige Bezeichner des Vorgangs, der abgeschlossen wird.

Anforderungsheader:

Parameter Wert
content-type application/json
x-ms-requestid Ein eindeutiger Zeichenfolgenwert zum Nachverfolgen der Anforderung vom Client, vorzugsweise eine GUID. Wenn dieser Wert nicht angegeben wird, wird ein Wert generiert und in den Antwortheadern bereitgestellt.
x-ms-correlationid Ein eindeutiger Zeichenfolgenwert für den Vorgang auf dem Client. Dieser Parameter korreliert alle Ereignisse vom Clientvorgang mit Ereignissen auf der Serverseite. Wenn dieser Wert nicht angegeben wird, wird ein Wert generiert und in den Antwortheadern bereitgestellt.
authorization Ein eindeutiges Zugriffstoken, das den Herausgeber identifiziert, der diesen API-Aufruf vornimmt. Das Format wird "Bearer <access_token>", wenn der Tokenwert vom Herausgeber abgerufen wird, wie in Abrufen eines Tokens basierend auf der Microsoft Entra-App.

Anforderungsnutzlastbeispiel:

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

Antwortcodes:

Code: 200 Ein Aufruf, um über den Abschluss eines Vorgangs auf der Partnerseite zu informieren. Diese Antwort könnte beispielsweise den Abschluss der Änderung von Arbeitsplätzen oder Plänen auf der Herausgeberseite signalisieren.

Code: 401 Nicht autorisiert. Das Autorisierungstoken ist ungültig oder abgelaufen. Die Anforderung versucht, auf ein SaaS-Abonnement für ein Angebot zuzugreifen, das mit einer anderen Microsoft Entra-App-ID veröffentlicht wurde, die zum Erstellen des Authentifizierungstokens verwendet wurde.

Code: 403 Verboten. Das Autorisierungstoken ist ungültig, wurde nicht bereitgestellt oder mit unzureichenden Berechtigungen bereitgestellt. Stellen Sie sicher, dass Sie ein gültiges Autorisierungstoken angeben.

Dieser Fehler ist häufig ein Symptom dafür, dass die SaaS-Registrierung ordnungsgemäß ausgeführt wird.

Code: 404 Nicht gefunden.

  • Das Abonnement mit subscriptionId wurde nicht gefunden.
  • Der Vorgang mit operationId wurde nicht gefunden.

Code: 409 Konflikt. Beispielsweise ist ein neueres Update bereits erfüllt.

Code: 500 Interner Serverfehler. Wiederholen Sie den API-Aufruf. Wenn der Fehler weiterhin besteht, wenden Sie sich an Microsoft-Support.

Verwandte Inhalte