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

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:

Anforderungsheader:

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:

Anforderungsheader:

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:

Anforderungsheader:

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.

Zugehöriger Inhalt

• Weitere Optionen für SaaS-Angebote im kommerziellen Marketplace finden Sie unter APIs für getaktete Abrechnung im Marketplace.
• Überprüfen und verwenden Sie die Clients für verschiedene Programmiersprachen und Beispiele.