SaaS-Fulfillment-Vorgangs-APIs der Version 2 im kommerziellen Microsoft-Marketplace

  • Artikel

In diesem Artikel wird Version 2 der SaaS-Fulfillment-Vorgangs-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, Anforderungen durch Patchen dieses Webhook-Vorgangs erfolgreich oder erfolglos unter Verwendung der nachfolgenden 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.

Auflisten ausstehender Vorgänge

Ruft die Liste der ausstehenden Vorgänge für das angegebene SaaS-Abonnement ab. Zurückgegebene Vorgänge müssen vom Herausgeber bestätigt werden, indem die API zum Patchen von Vorgängen aufgerufen wird.

Get 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 abgerufen, nachdem das Autorisierungstoken für den kommerziellen Marketplace mithilfe der Auflösungs-API aufgelöst wurde.

Anforderungsheader:

Parameter Wert
content-type application/json
x-ms-requestid Ein eindeutiger Zeichenfolgenwert für die Nachverfolgung 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 des Clientvorgangs mit serverseitigen Ereignissen. Wenn dieser Wert nicht angegeben wird, wird ein Wert generiert und in den Antwortheadern bereitgestellt.
authorization Das Format ist "Bearer <access_token>" , wenn der Tokenwert vom Herausgeber abgerufen wird, wie unter " Abrufen eines Tokens" basierend auf der Microsoft Entra-App erläutert.

Antwortcodes:

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

Beispiel einer 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 eine leere JSON-Datei zurück, wenn keine Vorgänge ausstehen.

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

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

Dieser Fehler ist häufig ein Symptom dafür, dass die SaaS-Registrierung nicht 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 auftritt, wenden Sie sich an den Microsoft-Support.

Abrufen des Vorgangsstatus

Diese API ermöglicht dem Herausgeber das Nachverfolgen des Status des angegebenen asynchronen Vorgangs: Unsubscribe (Kündigen), ChangePlan (Plan ändern) oder ChangeQuantity (Menge ändern).

Die operationId für diesen API-Aufruf kann von dem Wert abgerufen werden, der von Operation-Location zurückgegeben wird, dem API-Aufruf zum Abrufen ausstehender Vorgänge oder dem vom Wert des Parameters <id>, der in einem Webhookaufruf empfangen wird.

Get 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 abgerufen, nachdem das Autorisierungstoken für den kommerziellen Marketplace mithilfe der Auflösungs-API aufgelöst wurde.
operationId Der eindeutige Bezeichner des Vorgangs, der gerade abgerufen wird.

Anforderungsheader:

Parameter Wert
content-type application/json
x-ms-requestid Ein eindeutiger Zeichenfolgenwert für die Nachverfolgung 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 des Clientvorgangs mit serverseitigen Ereignissen. 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 sendet. Das Format ist "Bearer <access_token>" , wenn der Tokenwert vom Herausgeber abgerufen wird, wie unter " Abrufen eines Tokens" basierend auf der Microsoft Entra-App erläutert.

Antwortcodes:

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

Beispiel einer 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: 403 Verboten. Das Autorisierungstoken ist ungültig, abgelaufen oder wurde nicht angegeben. Die Anforderung versucht, auf ein SaaS-Abonnement für ein Angebot zuzugreifen, das mit einer anderen Microsoft Entra-App-ID veröffentlicht wird, die zum Erstellen des Autorisierungstokens verwendet wird.

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

Code: 404 Nicht gefunden.

  • Abonnement mit subscriptionId wurde nicht gefunden.
  • Operation with operationId isn't found.

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

Aktualisieren des Status eines Vorgangs

Diese API dient zum Aktualisieren des Status eines ausstehenden Vorgangs, um anzugeben, ob der Vorgang auf Herausgeberseite erfolgreich oder fehlerhaft war.

Die operationId für diesen API-Aufruf kann von dem Wert abgerufen werden, der von Operation-Location zurückgegeben wird, dem API-Aufruf zum Abrufen ausstehender Vorgänge oder dem vom Wert des Parameters <id>, der in einem Webhookaufruf 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 abgerufen, nachdem das Autorisierungstoken für den kommerziellen Marketplace mithilfe der Auflösungs-API aufgelöst wurde.
operationId Der eindeutige Bezeichner des Vorgangs, der gerade abgeschlossen wird.

Anforderungsheader:

Parameter Wert
content-type application/json
x-ms-requestid Ein eindeutiger Zeichenfolgenwert für die Nachverfolgung 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 des Clientvorgangs mit serverseitigen Ereignissen. 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 sendet. Das Format ist "Bearer <access_token>" , wenn der Tokenwert vom Herausgeber abgerufen wird, wie unter " Abrufen eines Tokens" basierend auf der Microsoft Entra-App erläutert.

Beispiel einer Anforderungsnutzlast:

{
  "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 kann z. B. den Abschluss einer Änderung der Arbeitsplätze oder Pläne auf Herausgeberseite anzeigen.

Code: 403

  • Unzulässig. Das Autorisierungstoken ist nicht verfügbar, ist ungültig oder abgelaufen. Die Anforderung versucht möglicherweise, auf ein Abonnement zuzugreifen, das nicht zum aktuellen Herausgeber gehört.
  • Unzulässig. Das Autorisierungstoken ist ungültig, abgelaufen oder wurde nicht angegeben. Die Anforderung versucht, auf ein SaaS-Abonnement für ein Angebot zuzugreifen, das mit einer anderen Microsoft Entra-App-ID veröffentlicht wird, die zum Erstellen des Autorisierungstokens verwendet wird.

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

Code: 404 Nicht gefunden.

  • Abonnement mit subscriptionId wurde nicht gefunden.
  • Operation with operationId isn't found.

Code: 409 Konflikt. Es wurde z. B. bereits eine neuere Transaktion abgeschlossen.

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

Nächste Schritte