SaaS-Erfüllungsabonnement-APIs v2 am kommerziellen Microsoft Marketplace

Artikel
06/14/2024

In diesem Artikel wird Version 2 der SaaS-Fulfillment-Abonnement-APIs beschrieben.

Hinweis

Um SaaS-Erfüllungsabonnement-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 abrufen.

Auflösen eines erworbenen Abonnements

Der Auflösungsendpunkt ermöglicht dem Herausgeber, das Identifizierungstoken für den Kauf aus dem kommerziellen Marketplace (im Abschnitt Gekauft, aber noch nicht aktiviert als Token bezeichnet) gegen eine persistente ID für das erworbene SaaS-Abonnement und dessen Details auszutauschen.

Wenn ein Kunde zur URL der Angebotsseite des Partners weitergeleitet wird, wird das Identifizierungstoken des Kunden in diesem URL-Aufruf als Parameter token übergeben. Es wird erwartet, dass der Partner dieses Token verwendet und dessen Auflösung anfordert. Die Antwort der Auflösungs-API enthält die SaaS-Abonnement-ID und andere Details zur eindeutigen Identifizierung des Kaufs. Das token , das mit dem URL-Aufruf der Zielseite bereitgestellt wird, ist 24 Stunden gültig. Wenn das empfangene Token abgelaufen ist, empfehlen wir, dem Endbenutzer die folgenden Anleitungen bereitzustellen:

„Dieser Kauf konnte nicht identifiziert werden. Öffnen Sie dieses SaaS-Abonnement im Azure-Portal oder im Microsoft 365 Admin Center erneut, und wählen Sie erneut "Konto konfigurieren" oder "Konto verwalten" aus.

Durch Aufrufen der Resolve-API werden Abonnementdetails und -status für SaaS-Abonnements in allen unterstützten Status zurückgegeben.

Post `https://marketplaceapi.microsoft.com/api/saas/subscriptions/resolve?api-version=<ApiVersion>`

Abfrageparameter:

Parameter	Wert
`ApiVersion`	Verwenden Sie 2018-08-31.

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.
`x-ms-marketplace-token`	Der aufzulösende Parameter token zur Identifizierung des Kaufs. Das Token wird im Aufruf der URL der Angebotsseite übergegeben, wenn der Kunde zur Website des SaaS-Partners weitergeleitet wird (z. B. `https://contoso.com/signup?token=<token><authorization_token>`). Der codierte Tokenwert ist Teil der Zielseiten-URL, daher muss er decodiert werden, bevor er in diesem API-Aufruf als Parameter verwendet wird. Ein Beispiel einer codierten Zeichenfolge in der URL sieht wie folgt aus: `contoso.com/signup?token=ab%2Bcd%2Fef`, wobei `ab%2Bcd%2Fef` das Token ist. Dasselbe token decodiert ist: `Ab+cd/ef`

Antwortcodes:

Code: 200 Gibt eindeutige SaaS-Abonnement-IDs basierend auf der x-ms-marketplace-token bereitgestellten Zurück.

Beispiel für einen Antworttext:

{
  "id": "<guid>", // purchased SaaS subscription ID
  "subscriptionName": "Contoso Cloud Solution", // SaaS subscription name
  "offerId": "offer1", // purchased offer ID
  "planId": "silver", // purchased offer's plan ID
  "quantity": 20, // number of purchased seats, might be empty if the plan is not per seat
  "subscription": { // full SaaS subscription details, see Get Subscription APIs response body for full description
    "id": "<guid>",
    "publisherId": "contoso",
    "offerId": "offer1",
    "name": "Contoso Cloud Solution",
    "saasSubscriptionStatus": " PendingFulfillmentStart ",
    "beneficiary": {
      "emailId": "test@test.com",
      "objectId": "<guid>",
      "tenantId": "<guid>",
      "puid": "<ID of the user>"
    },
    "purchaser": {
      "emailId": "test@test.com",
      "objectId": "<guid>",
      "tenantId": "<guid>",
      "puid": "<ID of the user>"
    },
    "planId": "silver",
    "term": {
      "termUnit": "P1M",
      "startDate": "2022-03-07T00:00:00Z", //This field is only available after the saas subscription is active.
      "endDate": "2022-04-06T00:00:00Z" //This field is only available after the saas subscription is active.
    },
      "autoRenew": true/false,
    "isTest": true/false,
    "isFreeTrial": false,
    "allowedCustomerOperations": <CSP purchases>["Read"] <All Others> ["Delete", "Update", "Read"],
      "sandboxType": "None",
      "lastModified": "0001-01-01T00:00:00", //[Deprecated] Do not use.
      "quantity": 5,
    "sessionMode": "None"
  }
}

Code: 400 Ungültige Anforderung. x-ms-marketplace-token fehlt, ist falsch formatiert, ungültig oder abgelaufen.

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 wurde als die, die zum Erstellen des Autorisierungstokens verwendet wurde.

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

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

Aktivieren eines Abonnements

Nachdem das SaaS-Konto für einen Endkunden konfiguriert wurde, muss der Herausgeber die API zum Aktivieren des Abonnements auf Microsoft-Seite aufrufen. Der Kunde wird nicht in Rechnung gestellt, es sei denn, dieser API-Aufruf ist erfolgreich.

Post `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/activate?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. Diese Zeichenfolge korreliert alle Ereignisse des Clientvorgangs 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 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 Anforderung, das Abonnement zu aktualisieren und als "Abonniert" zu kennzeichnen, wird empfangen. Unabhängige Softwareanbieter (ISVs) können den Status des Abonnements nach wenigen Minuten überprüfen (lesen Sie weiter, um den Abonnementstatus zu überprüfen). Dadurch erhalten Sie die endgültige Antwort, ob das Abonnement erfolgreich aktualisiert wurde. Fehler beim Abonnieren sendet automatisch einen "Unsubscribe"-Webhook.

Für diesen Anruf gibt es keinen Antworttext.

Code: 400 Ungültige Anforderung: Überprüfung fehlgeschlagen.

Das SaaS-Abonnement befindet sich im Status "Suspended ".

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 weist den Status Gekündigt auf.

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

Abrufen einer Liste aller Abonnements

Diese API ruft eine Liste aller erworbenen SaaS-Abonnements für alle Angebote ab, die der Herausgeber im kommerziellen Marketplace veröffentlicht. SaaS-Abonnements in allen möglichen Status werden zurückgegeben. Abbestellte SaaS-Abonnements werden auch zurückgegeben, da diese Informationen nicht auf der Microsoft-Seite gelöscht werden.

Diese API gibt paginierte Ergebnisse zurück (100 pro Seite).

Get `https://marketplaceapi.microsoft.com/api/saas/subscriptions?api-version=<ApiVersion>`

Abfrageparameter:

Parameter	Wert
`ApiVersion`	Verwenden Sie 2018-08-31.
`continuationToken`	Optionaler Parameter. Wenn Sie die erste Seite der Ergebnisse abrufen möchten, lassen Sie den Parameter leer. Verwenden Sie den Wert, der im Parameter `@nextLink` zurückgegeben wird, um die nächste Seite abzurufen.

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 Gibt die Liste aller vorhandenen Abonnements für alle Angebote dieses Herausgebers basierend auf dem Autorisierungstoken des Herausgebers zurück.

Beispiel für einen Antworttext:

{
  "subscriptions": [
    {
      "id": "<guid>", // purchased SaaS subscription ID
      "name": "Contoso Cloud Solution", // SaaS subscription name
      "publisherId": "contoso", // publisher ID
      "offerId": "offer1", // purchased offer ID
      "planId": "silver", // purchased plan ID
      "quantity": 10, // purchased amount of seats, is empty if plan is not per seat
      "beneficiary": { // email address, user ID and tenant ID for which SaaS subscription was purchased.
        "emailId": " test@contoso.com",
        "objectId": "<guid>",
        "tenantId": "<guid>",
        "puid": "<ID of the user>"
      },
      "purchaser": { // email address, user ID and tenant ID that purchased the SaaS subscription. These could be different from beneficiary information for reseller (CSP) purchase
        "emailId": " test@contoso.com",
        "objectId": "<guid>",
        "tenantId": "<guid>",
        "puid": "<ID of the user>"
      },
      "term": { // The period for which the subscription was purchased.
        "startDate": "2022-03-04T00:00:00Z", //format: YYYY-MM-DD. This is the date when the subscription was activated by the ISV and the billing started. This field is only available after the saas subscription is active.
        "endDate": "2022-04-03T00:00:00Z", // This is the last day the subscription is valid. Unless stated otherwise, the automatic renew happens the next day. This field is only available after the saas subscription is active.
        "termUnit": "P1M" // where P1M is monthly and P1Y is yearly. Also reflected in the startDate and endDate values
      },
      "autoRenew": true,
      "allowedCustomerOperations": ["Read", "Update", "Delete"], // Indicates operations allowed on the SaaS subscription for beneficiary. For CSP-initiated purchases, this is always "Read" because the customer cannot update or delete subscription in this flow. Purchaser can perform all operations on the subscription.
      "sessionMode": "None", // not relevant
      "isFreeTrial": true, // true - the customer subscription is currently in free trial, false - the customer subscription is not currently in free trial. (Optional field -– if not returned, the value is false.)
      "isTest": false, // not relevant
      "sandboxType": "None", // not relevant
      "saasSubscriptionStatus": "Subscribed" // Indicates the status of the operation. Can be one of the following: PendingFulfillmentStart, Subscribed, Suspended or Unsubscribed.
    },
    // next SaaS subscription details, might be a different offer
    {
      "id": "<guid1>",
      "name": "Contoso Cloud Solution1",
      "publisherId": "contoso",
      "offerId": "offer2",
      "planId": "gold",
      "quantity": "",
      "beneficiary": {
        "emailId": " test@contoso.com",
        "objectId": "<guid>",
        "tenantId": "<guid>",
        "puid": "<ID of the user>"
      },
      "purchaser": {
        "emailId": "purchase@csp.com ",
        "objectId": "<guid>",
        "tenantId": "<guid>",
        "puid": "<ID of the user>"
      },
      "term": {
        "startDate": "2019-05-31", /This field is only available after the saas subscription is active.
        "endDate": "2020-04-30",  //This field is only available after the saas subscription is active.
        "termUnit": "P1Y"
      },
      "autoRenew": false,
      "allowedCustomerOperations": ["Read"],
      "sessionMode": "None",
      "isFreeTrial": false,
      "isTest": false,
      "sandboxType": "None",
      "saasSubscriptionStatus": "Suspended"
    }
  ],
  "@nextLink": "https:// https://marketplaceapi.microsoft.com/api/saas/subscriptions/?continuationToken=%5b%7b%22token%22%3a%22%2bRID%3a%7eYeUDAIahsn22AAAAAAAAAA%3d%3d%23RT%3a1%23TRC%3a2%23ISV%3a1%23FPC%3aAgEAAAAQALEAwP8zQP9%2fFwD%2b%2f2FC%2fwc%3d%22%2c%22range%22%3a%7b%22min%22%3a%22%22%2c%22max%22%3a%2205C1C9CD673398%22%7d%7d%5d&api-version=2018-08-31" // url that contains continuation token to retrieve next page of the SaaS subscriptions list, if empty or absent, this is the last page. ISV can use this url as is to retrieve the next page or extract the value of continuation token from this url.
}

Wenn keine erworbenen SaaS-Abonnements für diesen Herausgeber gefunden werden, wird ein leerer Antworttext zurückgegeben.

Code: 403 Verboten. Das Autorisierungstoken ist nicht verfügbar, ungültig oder abgelaufen.

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

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

Abrufen eines Abonnements

Diese API ruft ein angegebenes SaaS-Abonnements für ein SaaS-Angebot ab, das der Herausgeber im kommerziellen Marketplace veröffentlicht. Rufen Sie mithilfe dieses Aufrufs alle verfügbaren Informationen zu einem bestimmten SaaS-Abonnement anhand seiner ID ab, anstatt die API aufzurufen, mit der eine Liste aller Abonnements abgerufen werden kann.

Get `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?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`	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 Gibt Details für ein SaaS-Abonnement basierend auf der subscriptionId bereitgestellten Zurück.

Beispiel für einen Antworttext:

{
  "id": "<guid>", // purchased SaaS subscription ID
  "name": "Contoso Cloud Solution", // SaaS subscription name
  "publisherId": "contoso", // publisher ID
  "offerId": "offer1", // purchased offer ID
  "planId": "silver", // purchased plan ID
  "quantity": 10, // purchased amount of seats is empty if plan is not per seat
  "beneficiary": { // email address, user ID and tenant ID for which SaaS subscription is purchased.
    "emailId": "test@contoso.com",
    "objectId": "<guid>",
    "tenantId": "<guid>",
    "puid": "<ID of the user>"
  },
  "purchaser": { // email address ,user ID and tenant ID that purchased the SaaS subscription. These could be different from beneficiary information for reseller (CSP) scenario
    "emailId": "test@test.com",
    "objectId": "<guid>",
    "tenantId": "<guid>",
    "puid": "<ID of the user>"
  },
  "allowedCustomerOperations": ["Read", "Update", "Delete"], // Indicates operations allowed on the SaaS subscription for beneficiary. For CSP-initiated purchases, this is always "Read" because the customer cannot update or delete subscription in this flow. Purchaser can perform all operations on the subscription.
  "sessionMode": "None", // not relevant
  "isFreeTrial": false, // true - the customer subscription is currently in free trial, false - the customer subscription is not currently in free trial. Optional field – if not returned the value is false.
  "autoRenew": true,
  "isTest": false, // not relevant
  "sandboxType": "None", // not relevant
  "created": "2022-03-01T22:59:45.5468572Z",
     "lastModified": "0001-01-01T00:00:00", //[Deprecated] Do not use.
  "saasSubscriptionStatus": " Subscribed ", // Indicates the status of the operation: PendingFulfillmentStart, Subscribed, Suspended or Unsubscribed.
  "term": { // the period for which the subscription was purchased
    "startDate": "2022-03-04T00:00:00Z", //format: YYYY-MM-DD. This is the date when the subscription was activated by the ISV and the billing started. This field is only available after the saas subscription is active.
    "endDate": "2022-04-03T00:00:00Z", // This is the last day the subscription is valid. Unless stated otherwise, the automatic renew happens the next day. This field is only available after the saas subscription is active.
    "termUnit": "P1M" //where P1M is monthly and P1Y is yearly. Also reflected in the startDate and endDate values.
  }
}

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 der angegebenen 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.

Auflisten verfügbarer Pläne

Diese API ruft alle Pläne für ein SaaS-Angebot ab, das durch die subscriptionId eines bestimmten Erwerbs dieses Angebots bestimmt wird. Verwenden Sie diesen Aufruf, um eine Liste aller privaten und öffentlichen Pläne abzurufen, die der Begünstigte eines SaaS-Abonnements für das Abonnement aktualisieren kann. Die zurückgegebenen Pläne sind in derselben Geografie wie der bereits erworbene Plan verfügbar.

Dieser Aufruf gibt eine Liste der Pläne zurück, die für diesen Kunden zusätzlich zu dem bereits erworbenen Plan verfügbar sind. Die Liste kann einem Endbenutzer auf der Website des Herausgebers angezeigt werden. Ein Endbenutzer kann den Abonnementplan in einen beliebigen Plan in der zurückgegebenen Liste ändern. Das Ändern des Plans in einen Plan, der nicht in der Liste enthalten ist, funktioniert nicht.

Diese API ruft auch die aktive private Angebots-ID ab (wenn Sie die API mit planId-Filter aufrufen). Das Aufrufen der API mit planId-Filter zeigt die guiDs der aktiven privaten Angebots-ID im Antworttext unter "sourceOffers"-Knoten an. Die im Filterparameter übergebene planId sollte mit der planId übereinstimmen, die der Kunde erworben hat.

Get `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/listAvailablePlans?api-version=<ApiVersion>&planId=<planId>`

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.
`planId (Optional)`	Plan-ID eines bestimmten Plans, den Sie abrufen möchten. Dies ist optional und wenn ignoriert wird, werden alle Pläne zurückgegeben.

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 Gibt eine Liste aller verfügbaren Pläne für ein vorhandenes SaaS-Abonnement einschließlich der bereits erworbenen zurück.

Das Übergeben einer ungültigen (optionalen) planId gibt eine leere Liste von Plänen zurück.

Beispiel für einen Antworttext:

{
  "plans": [
    {
      "planId": "Platinum001",
      "displayName": "plan display name",
      "isPrivate": true, //returns true for private plans and customized plans created within a private offer.
      "description": "plan description",
      "minQuantity": 5,
      "maxQuantity": 100,
      "hasFreeTrials": false,
      "isPricePerSeat": true,
      "isStopSell": false,
      "market": "US",
      "planComponents": {
        "recurrentBillingTerms": [
          {
            "currency": "USD",
            "price": 1,
            "termUnit": "P1M",
            "termDescription": "term description",
            "meteredQuantityIncluded": [
              {
                "dimensionId": "Dimension001",
                "units": "Unit001"
              }
            ]
          }
        ],
        "meteringDimensions": [
          {
            "id": "MeteringDimension001",
            "currency": "USD",
            "pricePerUnit": 1,
            "unitOfMeasure": "unitOfMeasure001",
            "displayName": "unit of measure display name"
          }
        ]
      },
      "sourceOffers": [ //sourceOffers is returned when planId is passed as filter parameter (note that this is the plan that customer has purchased).
        {
          "externalId": "<guid>" //private offer id, returned when purchase is made through private offer.
        }
      ]
    }
  ]
}

Code: 404 – Nicht gefunden. subscriptionId wurde nicht gefunden.

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

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

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

Ändern des Plans für das Abonnement

Diese API dient zum Ändern des vorhandenen Plans, der für ein SaaS-Abonnement erworben wurde, in einen neuen Plan (öffentlich oder privat). Der Herausgeber muss diese API aufrufen, wenn ein Plan auf Herausgeberseite für ein im kommerziellen Marketplace erworbenes SaaS-Abonnement geändert wird.

Diese API kann nur für aktive Abonnements aufgerufen werden. Jeder Plan kann in einen anderen vorhandenen Plan (öffentlich oder privat), aber nicht in sich selbst geändert werden. Bei privaten Plänen muss der Mandant des Kunden im Partner Center als Teil der Zielgruppe für den Plan definiert werden.

Patch `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?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`	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:

{
  "planId": "gold" // the ID of the new plan to be purchased
}

Antwortcodes:

Code: 202 Die Anforderung zum Ändern des Plans wurde akzeptiert und asynchron behandelt. Vom Partner wird erwartet, dass er die Standort-URL für den Vorgang abfragt, um zu ermitteln, ob die Änderungsanforderung für den Plan erfolgreich war oder fehlgeschlagen ist. Die Abfrage sollte alle paar Sekunden durchgeführt werden, bis der endgültige Status Fehler, Erfolgreich oder Konflikt für den Vorgang empfangen wird. Der endgültige Vorgangsstatus sollte schnell zurückgegeben werden, doch kann dies in einigen Fällen mehrere Minuten dauern.

Der Partner erhält auch eine Webhook-Benachrichtigung, wenn die Aktion auf der kommerziellen Marketplace-Seite erfolgreich abgeschlossen werden kann. Erst dann sollte der Herausgeber die Planänderung auf Herausgeberseite vornehmen.

Antwortheader:

Parameter	Wert
`Operation-Location`	URL zum Abrufen des Vorgangsstatus. Beispiel: `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=2018-08-31`

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

Der angeforderte Plan kann nicht gefunden werden, oder der Plan ist für den Benutzer nicht verfügbar.
Der angeforderte Plan ist identisch mit dem abonnierten Plan.
Der Status des SaaS-Abonnements ist nicht Abonniert.
Das saaS-Abonnement, das aktualisiert wird, wird von einem Cloud Solution Provider (CSP) erworben. Sie müssen mit dem CSP-Anbieter arbeiten, um diese Aktion auszuführen.

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 Microsoft Entra-App-ID veröffentlicht wird, die sich von der zum Erstellen des Autorisierungstokens unterscheidet.

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 dem angegebenen subscriptionId Wurde wurde nicht gefunden.

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

Hinweis

Es kann jeweils nur der Plan oder die Menge von Arbeitsplätzen geändert werden, nicht beides gleichzeitig.

Diese API kann nur nach ausdrücklicher Genehmigung der Änderung durch den Endbenutzer aufgerufen werden.

Ändern der Menge von Arbeitsplätzen für das SaaS-Abonnement

Diese API dient zum Ändern (Erhöhen oder Verringern) der Menge von Arbeitsplätzen, die für ein SaaS-Abonnement erworben wurden. Der Herausgeber muss diese API aufrufen, wenn die Menge der Arbeitsplätze für ein im kommerziellen Marketplace erstelltes SaaS-Abonnement über die Herausgeberseite geändert wird.

Die Anzahl der Arbeitsplätze darf nicht mehr sein als die im aktuellen Plan zulässige Menge. In diesem Fall muss der Herausgeber den Plan ändern, bevor die Anzahl der Arbeitsplätze geändert wird.

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

Abfrageparameter:

Parameter	Wert
`ApiVersion`	Verwenden Sie 2018-08-31.
`subscriptionId`	Ein eindeutiger 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`	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:

{
  "quantity": 5 // the new amount of seats to be purchased
}

Antwortcodes:

Code: 202 Die Anforderung zum Ändern der Menge wurde akzeptiert und asynchron behandelt. Vom Partner wird erwartet, dass er die Standort-URL für den Vorgang abfragt, um zu ermitteln, ob die Änderungsanforderung für die Menge erfolgreich war oder fehlgeschlagen ist. Die Abfrage sollte alle paar Sekunden durchgeführt werden, bis der endgültige Status Fehler, Erfolgreich oder Konflikt für den Vorgang empfangen wird. Der endgültige Vorgangsstatus sollte schnell zurückgegeben werden, doch kann dies in einigen Fällen mehrere Minuten dauern.

Antwortheader:

Parameter	Wert
`Operation-Location`	Link zu einer Ressource, um den Vorgangsstatus abzurufen. Beispiel: `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=2018-08-31`.

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

Die neue Menge liegt nicht innerhalb des zulässigen Bereichs.
Die neue Menge fehlt oder 0.
Die neue Menge ist identisch mit der aktuellen Menge.
Der Status des SaaS-Abonnements ist nicht „Abonniert“.
Das saaS-Abonnement, das aktualisiert wird, wird von einem Cloud Solution Provider (CSP) erworben. Sie müssen mit dem CSP-Anbieter arbeiten, um diese Aktion auszuführen.

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 Microsoft Entra-App-ID veröffentlicht wird, die sich von der zum Erstellen des Autorisierungstokens unterscheidet.

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 dem angegebenen subscriptionId Wurde wurde nicht gefunden.

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

Hinweis

Es kann jeweils nur ein Plan oder eine Menge geändert werden, nicht beides gleichzeitig.

Diese API kann nur nach ausdrücklicher Genehmigung der Änderung durch den Endbenutzer aufgerufen werden.

Kündigen eines Abonnements

Diese API dient zum Kündigen eines angegebenen SaaS-Abonnements. Der Herausgeber muss diese API nicht verwenden, und es wird empfohlen, die Kunden zum Kündigen von SaaS-Abonnements an den kommerziellen Marketplace weiterzuleiten.

Wenn der Herausgeber beschließt, die Kündigung von im kommerziellen Marketplace erworbenen SaaS-Abonnements auf seiner Website zu implementieren, muss er diese API aufrufen. Nach Abschluss dieses Anrufs wird der Status des Abonnements auf der Microsoft-Seite gekündigt .

Der Kunde wird nicht in Rechnung gestellt, wenn ein Abonnement innerhalb von 72 Stunden nach dem Kauf storniert wird.

Der Kunde wird in Rechnung gestellt, wenn ein Abonnement nach der vorherigen Nachfrist storniert wird. Der Kunde verliert unmittelbar nach der Kündigung den Zugriff auf das SaaS-Abonnement auf der Microsoft-Seite.

Delete `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?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`	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: 202 Die Anforderung zum Kündigen des Abonnements wurde akzeptiert und asynchron verarbeitet. Vom Partner wird erwartet, dass er die Standort-URL für den Vorgang abfragt, um zu ermitteln, ob diese Anforderung erfolgreich war oder fehlgeschlagen ist. Die Abfrage sollte alle paar Sekunden durchgeführt werden, bis der endgültige Status Fehler, Erfolgreich oder Konflikt für den Vorgang empfangen wird. Der endgültige Vorgangsstatus sollte schnell zurückgegeben werden, doch kann dies in einigen Fällen mehrere Minuten dauern.

Der Partner erhält auch die Webhook-Benachrichtigung, wenn die Aktion erfolgreich auf der kommerziellen Marketplace-Seite abgeschlossen wird. Erst dann sollte der Herausgeber das Abonnement auf Herausgeberseite kündigen.

Code: 200 Das Abonnement befindet sich bereits im Status "Abonnement kündigen".

Antwortheader:

Parameter	Wert
`Operation-Location`	Link zu einer Ressource, um den Vorgangsstatus abzurufen. Beispiel: `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=2018-08-31`.

Code: 400 Ungültige Anforderung. „Delete“ ist nicht in der Liste allowedCustomerOperations für dieses SaaS-Abonnement enthalten.

Code: 403 Verboten. Das Autorisierungstoken ist ungültig, abgelaufen oder nicht verfügbar.

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: 409

Das Löschen kann nicht abgeschlossen werden, da das Abonnement aufgrund ausstehender Vorgänge gesperrt ist.

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

Weitere Optionen für SaaS-Angebote auf dem kommerziellen Markt finden Sie in den APIs für den kommerziellen Marketplace-Meteringdienst
Überprüfen und Verwenden der Clients für verschiedene Programmiersprachen und Beispiele
Anleitungen zum Testen finden Sie unter Implementieren eines Webhooks für den SaaS-Dienst

Freigeben über

SaaS-Erfüllungsabonnement-APIs v2 am kommerziellen Microsoft Marketplace

Auflösen eines erworbenen Abonnements

Post `https://marketplaceapi.microsoft.com/api/saas/subscriptions/resolve?api-version=<ApiVersion>`

Aktivieren eines Abonnements

Post `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/activate?api-version=<ApiVersion>`

Abrufen einer Liste aller Abonnements

Get `https://marketplaceapi.microsoft.com/api/saas/subscriptions?api-version=<ApiVersion>`

Abrufen eines Abonnements

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

Auflisten verfügbarer Pläne

Get `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/listAvailablePlans?api-version=<ApiVersion>&planId=<planId>`

Ändern des Plans für das Abonnement

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

Ändern der Menge von Arbeitsplätzen für das SaaS-Abonnement

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

Kündigen eines Abonnements

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

Feedback

Zusätzliche Ressourcen

Freigeben über

SaaS-Erfüllungsabonnement-APIs v2 am kommerziellen Microsoft Marketplace

Auflösen eines erworbenen Abonnements

Post https://marketplaceapi.microsoft.com/api/saas/subscriptions/resolve?api-version=<ApiVersion>

Aktivieren eines Abonnements

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

Abrufen einer Liste aller Abonnements

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

Abrufen eines Abonnements

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

Auflisten verfügbarer Pläne

Get https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/listAvailablePlans?api-version=<ApiVersion>&planId=<planId>

Ändern des Plans für das Abonnement

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

Ändern der Menge von Arbeitsplätzen für das SaaS-Abonnement

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

Kündigen eines Abonnements

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

Zugehöriger Inhalt

Feedback

Zusätzliche Ressourcen

Post `https://marketplaceapi.microsoft.com/api/saas/subscriptions/resolve?api-version=<ApiVersion>`

Post `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/activate?api-version=<ApiVersion>`

Get `https://marketplaceapi.microsoft.com/api/saas/subscriptions?api-version=<ApiVersion>`

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

Get `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/listAvailablePlans?api-version=<ApiVersion>&planId=<planId>`

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

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

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