Freigeben über

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

  • Artikel

In diesem Artikel wird Version 2 der SaaS-Erfüllungsabonnement-APIs beschrieben.

Anmerkung

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

Auflösen eines erworbenen Abonnements

Der Auflösungsendpunkt ermöglicht es dem Herausgeber, das Kaufidentifikationstoken aus dem kommerziellen Marketplace (als Token bezeichnet in Gekauft, aber noch nicht aktiviert) in eine permanent erworbene SaaS-Abonnement-ID und seine Details auszutauschen.

Wenn ein Kunde an die Startseiten-URL des Partners umgeleitet wird, wird das Kundenidentifikationstoken als Token Parameter in diesem URL-Aufruf übergeben. Es wird erwartet, dass der Partner dieses Token verwendet und eine Anforderung zum Auflösen des Tokens vorgibt. Die Lösungs-API-Antwort enthält die SaaS-Abonnement-ID und andere Details, um den Kauf eindeutig zu identifizieren. Das Token, das mit dem URL-Aufruf der Zielseite bereitgestellt wird, ist 24 Stunden gültig. Wenn das Token, das Sie erhalten, abgelaufen ist, empfehlen wir, dem Endbenutzer die folgenden Anleitungen bereitzustellen:

"Wir konnten diesen Kauf nicht identifizieren. Öffnen Sie dieses SaaS-Abonnement im Azure-Portal oder im Microsoft 365 Admin Center erneut, und wählen Sie "Konto konfigurieren" oder "Konto verwalten" erneut aus.

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

Posten 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 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.
x-ms-marketplace-token Die Einkaufsidentifikation Token Parameter, der aufgelöst werden soll. Das Token wird im URL-Aufruf der Zielseite übergeben, wenn der Kunde auf die Website des SaaS-Partners umgeleitet wird (z. B. https://contoso.com/signup?token=<token><authorization_token>).

Das Token codierten Werts ist Teil der Zielseiten-URL, daher muss es decodiert werden, bevor es in diesem API-Aufruf als Parameter verwendet wird.

Hier ist ein Beispiel für eine codierte Zeichenfolge in der URL: contoso.com/signup?token=ab%2Bcd%2Fef, wobei Token-ab%2Bcd%2Fefist. Dasselbe token decodiert ist: Ab+cd/ef

Antwortcodes:

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

Beispiel für 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, falsch formatiert, ungültig oder abgelaufen ist.

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: 500 Interner Serverfehler. Wiederholen Sie den API-Aufruf. Wenn der Fehler weiterhin besteht, wenden Sie sich an Microsoft-Support.

Aktivieren eines Abonnements

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

Posten 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 nach dem Auflösen des kommerziellen Marketplace-Autorisierungstokens mithilfe der Resolve APIabgerufen.

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. Diese Zeichenfolge korreliert alle Ereignisse aus dem 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 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 in Status "Suspended".

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 befindet sich in einem Status "Gekündigt".

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

Liste aller Abonnements abrufen

Diese API ruft eine Liste aller erworbenen SaaS-Abonnements für alle Angebote ab, die der Herausgeber auf dem 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.

Die API gibt paginierte Ergebnisse zurück, Sie müssen das Fortsetzungstoken übergeben, um die nachfolgenden Ergebnisse abzurufen.

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

Abfrageparameter:

Parameter Wert
ApiVersion Verwenden Sie 2018-08-31.
continuationToken Wahlparameter. Wenn Sie die erste Seite der Ergebnisse abrufen möchten, lassen Sie es leer. Verwenden Sie den in @nextLink Parameter zurückgegebenen Wert, um die nächste Seite abzurufen.

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

Beispiel für 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 für diesen Herausgeber keine erworbenen SaaS-Abonnements gefunden werden, wird ein leerer Antworttext zurückgegeben.

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: 500 Interner Serverfehler. Wiederholen Sie den API-Aufruf. Wenn der Fehler weiterhin besteht, wenden Sie sich an Microsoft-Support.

Abonnement abrufen

Diese API ruft ein angegebenes erworbenes SaaS-Abonnement für ein SaaS-Angebot ab, das der Herausgeber auf dem kommerziellen Marketplace veröffentlicht. Verwenden Sie diesen Aufruf, um alle verfügbaren Informationen für ein bestimmtes SaaS-Abonnement anhand ihrer ID abzurufen, anstatt die API aufzurufen, die zum Abrufen einer Liste aller Abonnements verwendet wird.

Abrufen von 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 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 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 Gibt Details für ein SaaS-Abonnement basierend auf der bereitgestellten subscriptionId zurück.

Beispiel für 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: 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. SaaS-Abonnement mit dem angegebenen subscriptionId nicht gefunden werden.

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

Verfügbare Pläne auflisten

Diese API ruft alle Pläne für ein SaaS-Angebot ab, das vom subscriptionId eines bestimmten Kaufs dieses Angebots identifiziert wird. Verwenden Sie diesen Aufruf, um eine Liste aller privaten und öffentlichen Pläne zu erhalten, 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 Herausgeberwebsite angezeigt werden. Ein Endbenutzer kann den Abonnementplan in einen der Pläne 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.

Abrufen von 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 nach dem Auflösen des kommerziellen Marketplace-Autorisierungstokens mithilfe der Resolve-API abgerufen.
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 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 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 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: 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: 500 Interner Serverfehler. Wiederholen Sie den API-Aufruf. Wenn der Fehler weiterhin besteht, wenden Sie sich an Microsoft-Support.

Ändern des Plans für das Abonnement

Verwenden Sie diese API, um den vorhandenen Plan zu aktualisieren, der für ein SaaS-Abonnement erworben wurde, auf einen neuen Plan (öffentlich oder privat). Der Herausgeber muss diese API aufrufen, wenn ein Plan auf der Herausgeberseite für ein saaS-Abonnement geändert wird, das im kommerziellen Marketplace erworben wurde.

Diese API kann nur für Active-Abonnements aufgerufen werden. Jeder Plan kann in einen anderen vorhandenen Plan (öffentlich oder privat) geändert werden, aber nicht in sich selbst. Für private Pläne muss der Mandant des Kunden als Teil der Zielgruppe des Plans im Partner Center 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 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 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:

{
  "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. Es wird erwartet, dass der Partner die Operation-Location URL abruft, um einen Erfolg oder Fehler der Änderungsplananforderung zu ermitteln. Die Abfrage sollte alle mehrere Sekunden ausgeführt werden, bis der endgültige Status Fehlgeschlagen, erfolgreichoder Konflikt für den Vorgang empfangen wird. Der endgültige Vorgangsstatus sollte schnell zurückgegeben werden, kann jedoch 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. Nur dann sollte der Herausgeber den Plan auf der Herausgeberseite ändern.

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 SaaS-Abonnementstatus 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: 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 dem angegebenen subscriptionId kann nicht gefunden werden.

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

Anmerkung

Entweder der Plan oder die Anzahl der Arbeitsplätze können gleichzeitig geändert werden, nicht beides.

Diese API kann nur aufgerufen werden, nachdem die explizite Genehmigung für die Änderung vom Endbenutzer abgerufen wurde.

Ändern der Anzahl von Arbeitsplätzen im SaaS-Abonnement

Verwenden Sie diese API, um die Anzahl der lizenzen, die für ein SaaS-Abonnement erworben wurden, zu aktualisieren (zu erhöhen oder zu verringern). Der Herausgeber muss diese API aufrufen, wenn die Anzahl der Arbeitsplätze von der Herausgeberseite für ein saaS-Abonnement geändert wird, das auf dem kommerziellen Marketplace erstellt wurde.

Die Anzahl der Arbeitsplätze darf nicht mehr sein als die im aktuellen Plan zulässige Menge. In diesem Fall sollte 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 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 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:

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

Antwortcodes:

Code: 202 Die Anforderung zum Ändern der Menge wurde akzeptiert und asynchron behandelt. Es wird erwartet, dass der Partner die Operation-Location URL abruft, um einen Erfolg oder Fehler der Anforderung der Änderungsmenge zu ermitteln. Die Abfrage sollte alle mehrere Sekunden ausgeführt werden, bis der endgültige Status Fehlgeschlagen, erfolgreichoder Konflikt für den Vorgang empfangen wird. Der endgültige Vorgangsstatus sollte schnell zurückgegeben werden, kann jedoch 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. Nur dann sollte der Herausgeber die Menge auf der Herausgeberseite ändern.

Antwortheader:

Parameter Wert
Operation-Location Verknüpfen Sie eine Ressource, um den Status des Vorgangs 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 entspricht der aktuellen Menge.
  • Der SaaS-Abonnementstatus 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: 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 dem angegebenen subscriptionId kann nicht gefunden werden.

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

Anmerkung

Nur ein Plan oder eine Menge kann gleichzeitig geändert werden, nicht beide.

Diese API kann erst aufgerufen werden, nachdem der Endbenutzer die explizite Genehmigung für die Änderung erhalten hat.

Kündigen eines Abonnements

Verwenden Sie diese API, um ein angegebenes SaaS-Abonnement zu kündigen. Der Herausgeber muss diese API nicht verwenden, und wir empfehlen, dass Kunden an den kommerziellen Marketplace weitergeleitet werden, um SaaS-Abonnements zu kündigen.

Wenn der Herausgeber entscheidet, die Kündigung eines SaaS-Abonnements zu implementieren, das auf dem kommerziellen Marketplace auf der Seite des Herausgebers erworben wurde, muss er diese API aufrufen. Nach Abschluss dieses Anrufs wird der Status des Abonnements auf der Microsoft-Seite "Abonnement kündigen".

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.

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

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 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: 202 Die Anforderung zum Kündigen des Abonnements wurde akzeptiert und asynchron verarbeitet. Es wird erwartet, dass der Partner die Operation-Location URL abruft, um einen Erfolg oder Fehler dieser Anforderung zu ermitteln. Die Abfrage sollte alle mehrere Sekunden ausgeführt werden, bis der endgültige Status Fehlgeschlagen, erfolgreichoder Konflikt für den Vorgang empfangen wird. Der endgültige Vorgangsstatus sollte schnell zurückgegeben werden, kann jedoch 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. Nur dann sollte der Herausgeber das Abonnement auf der Herausgeberseite kündigen.

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

Antwortheader:

Parameter Wert
Operation-Location Verknüpfen Sie eine Ressource, um den Status des Vorgangs abzurufen. Beispiel: https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=2018-08-31.

Code: 400 Ungültige Anforderung. Das Löschen befindet sich nicht in allowedCustomerOperations Liste für dieses SaaS-Abonnement.

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: 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 besteht, wenden Sie sich an Microsoft-Support.

Verwandte Inhalte