SaaS-uitvoeringsabonnement-API's v2 op de commerciële marketplace van Microsoft

Artikel
06/14/2024

In dit artikel wordt versie 2 van de API's van het SaaS-uitvoeringsabonnement beschreven.

Notitie

Als u SAAS-uitvoeringsabonnement-API's wilt kunnen aanroepen, moet u het autorisatietoken van een uitgever maken met de juiste resource-id. Meer informatie over het ophalen van het autorisatietoken van de uitgever

Een aangeschaft abonnement oplossen

Met het eindpunt voor oplossen kan de uitgever het aankoopidentificatietoken inwisselen via de commerciële marketplace (ook wel token in Gekocht maar nog niet geactiveerd) naar een permanente aangeschafte SaaS-abonnements-id en de bijbehorende details.

Wanneer een klant wordt omgeleid naar de URL van de landingspagina van de partner, wordt het klantidentificatietoken doorgegeven als de tokenparameter in deze URL-aanroep. De partner zal dit token naar verwachting gebruiken en een aanvraag indienen om dit op te lossen. Het ANTWOORD van de Resolve-API bevat de Id van het SaaS-abonnement en andere details om de aankoop uniek te identificeren. Het token dat is opgegeven bij de url-aanroep van de landingspagina, is 24 uur geldig. Als het token dat u ontvangt is verlopen, raden we u aan de volgende richtlijnen aan de eindgebruiker op te geven:

"Deze aankoop kan niet worden geïdentificeerd. Open dit SaaS-abonnement opnieuw in Azure Portal of in Microsoft 365-beheer Center en selecteer opnieuw Account configureren of Account beheren.

Het aanroepen van de Resolve-API retourneert abonnementsgegevens en -statussen voor SaaS-abonnementen in alle ondersteunde statussen.

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

Queryparameters:

Parameter	Weergegeven als
`ApiVersion`	Gebruik 2018-08-31.

Aanvraagheaders:

Parameter	Weergegeven als
`content-type`	`application/json`
`x-ms-requestid`	Een unieke tekenreekswaarde voor het bijhouden van de aanvraag van de client, bij voorkeur een GUID. Als deze waarde niet is opgegeven, wordt er een gegenereerd en opgegeven in de antwoordheaders.
`x-ms-correlationid`	Een unieke tekenreekswaarde voor bewerking op de client. Deze parameter correleert alle gebeurtenissen van de clientbewerking met gebeurtenissen aan de serverzijde. Als deze waarde niet wordt opgegeven, wordt er een gegenereerd en opgegeven in de antwoordheaders
`authorization`	Een uniek toegangstoken waarmee de uitgever deze API-aanroep identificeert. De notatie is `"Bearer <access_token>"` wanneer de tokenwaarde wordt opgehaald door de uitgever, zoals wordt uitgelegd in Een token ophalen op basis van de Microsoft Entra-app.
`x-ms-marketplace-token`	De parameter van het aankoopidentificatietoken om op te lossen. Het token wordt doorgegeven in de url-aanroep van de landingspagina wanneer de klant wordt omgeleid naar de website van de SaaS-partner (bijvoorbeeld: `https://contoso.com/signup?token=<token><authorization_token>`). De tokenwaarde die wordt gecodeerd, maakt deel uit van de URL van de landingspagina, dus deze moet worden gedecodeerd voordat deze wordt gebruikt als parameter in deze API-aanroep. Hier volgt een voorbeeld van een gecodeerde tekenreeks in de URL: `contoso.com/signup?token=ab%2Bcd%2Fef`, waar token zich bevindt `ab%2Bcd%2Fef`. Hetzelfde token gedecodeerd is: `Ab+cd/ef`

Antwoordcodes:

Code: 200 retourneert unieke SaaS-abonnements-id's op basis van de x-ms-marketplace-token opgegeven.

Voorbeeld van antwoordtekst:

{
  "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 Ongeldige aanvraag. x-ms-marketplace-token ontbreekt, is ongeldig, ongeldig of verlopen.

Code: 403 Verboden. Het autorisatietoken is ongeldig, verlopen of is niet opgegeven. De aanvraag probeert toegang te krijgen tot een SaaS-abonnement voor een aanbieding die is gepubliceerd met een andere Microsoft Entra-app-id van degene die wordt gebruikt om het autorisatietoken te maken.

Deze fout is vaak een symptoom van het niet correct uitvoeren van de SaaS-registratie .

Code: 500 Interne serverfout. Voer de API-aanroep opnieuw uit. Neem contact op met Microsoft Ondersteuning als de fout zich blijft voordoen.

Een abonnement activeren

Nadat het SaaS-account is geconfigureerd voor een eindgebruiker, moet de uitgever de API Voor het activeren van het abonnement aanroepen aan de microsoft-zijde. De klant wordt alleen gefactureerd als deze API-aanroep is geslaagd.

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

Queryparameters:

Parameter	Weergegeven als
`ApiVersion`	Gebruik 2018-08-31.
`subscriptionId`	De unieke id van het aangeschafte SaaS-abonnement. Deze id wordt verkregen na het omzetten van het autorisatietoken voor de commerciële marketplace met behulp van de Resolve-API.

Aanvraagheaders:

Parameter	Weergegeven als
`content-type`	`application/json`
`x-ms-requestid`	Een unieke tekenreekswaarde voor het bijhouden van de aanvraag van de client, bij voorkeur een GUID. Als deze waarde niet is opgegeven, wordt er een gegenereerd en opgegeven in de antwoordheaders.
`x-ms-correlationid`	Een unieke tekenreekswaarde voor bewerking op de client. Deze tekenreeks correleert alle gebeurtenissen van de clientbewerking met gebeurtenissen aan de serverzijde. Als deze waarde niet is opgegeven, wordt er een gegenereerd en opgegeven in de antwoordheaders.
`authorization`	Een uniek toegangstoken waarmee de uitgever deze API-aanroep identificeert. De notatie is `"Bearer <access_token>"` wanneer de tokenwaarde wordt opgehaald door de uitgever, zoals wordt uitgelegd in Een token ophalen op basis van de Microsoft Entra-app.

Antwoordcodes:

Code: 200 Aanvraag om het abonnement bij te werken en als 'Geabonneerd' te markeren, wordt ontvangen. Onafhankelijke softwareleveranciers (ISV's) kunnen na enkele minuten controleren op de status van het abonnement (lees verder voor de bewerking Ophalen om de abonnementsstatus te controleren). Hiermee krijgt u het definitieve antwoord of het abonnement is bijgewerkt. Als u zich niet kunt abonneren, wordt automatisch een webhook 'Afmelden' verzonden.

Er is geen antwoordtekst voor deze oproep.

Code: 400 Ongeldige aanvraag: validatie is mislukt.

Het SaaS-abonnement heeft de status Onderbroken .

Deze fout is vaak een symptoom van het niet correct uitvoeren van de SaaS-registratie .

Code: 404 Niet gevonden. Het SaaS-abonnement heeft de status Afmelden .

Code: 500 Interne serverfout. Voer de API-aanroep opnieuw uit. Neem contact op met Microsoft Ondersteuning als de fout zich blijft voordoen.

Lijst met alle abonnementen ophalen

Met deze API wordt een lijst opgehaald met alle aangeschafte SaaS-abonnementen voor alle aanbiedingen die de uitgever publiceert in de commerciële marketplace. SaaS-abonnementen in alle mogelijke statussen worden geretourneerd. Afgemelde SaaS-abonnementen worden ook geretourneerd omdat deze informatie niet aan de zijde van Microsoft wordt verwijderd.

De API retourneert gepagineerde resultaten van 100 per pagina.

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

Queryparameters:

Parameter	Weergegeven als
`ApiVersion`	Gebruik 2018-08-31.
`continuationToken`	Optionele parameter. Als u de eerste pagina met resultaten wilt ophalen, laat u leeg. Gebruik de waarde die wordt geretourneerd in `@nextLink` de parameter om de volgende pagina op te halen.

Aanvraagheaders:

Parameter	Weergegeven als
`content-type`	`application/json`
`x-ms-requestid`	Een unieke tekenreekswaarde voor het bijhouden van de aanvraag van de client, bij voorkeur een GUID. Als deze waarde niet is opgegeven, wordt er een gegenereerd en opgegeven in de antwoordheaders.
`x-ms-correlationid`	Een unieke tekenreekswaarde voor bewerking op de client. Deze parameter correleert alle gebeurtenissen van de clientbewerking met gebeurtenissen aan de serverzijde. Als deze waarde niet is opgegeven, wordt er een gegenereerd en opgegeven in de antwoordheaders.
`authorization`	Een uniek toegangstoken waarmee de uitgever wordt geïdentificeerd die deze API-aanroep maakt. De notatie is `"Bearer <access_token>"` wanneer de tokenwaarde wordt opgehaald door de uitgever, zoals wordt uitgelegd in Een token ophalen op basis van de Microsoft Entra-app.

Antwoordcodes:

Code: 200 Retourneert de lijst met alle bestaande abonnementen voor alle aanbiedingen van deze uitgever, op basis van het autorisatietoken van de uitgever.

Voorbeeld van antwoordtekst:

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

Als er geen aangeschafte SaaS-abonnementen voor deze uitgever worden gevonden, wordt er een lege antwoordtekst geretourneerd.

Code: 403 Verboden. Het autorisatietoken is niet beschikbaar, ongeldig of verlopen.

Deze fout is vaak een symptoom van het niet correct uitvoeren van de SaaS-registratie .

Code: 500 Interne serverfout. Voer de API-aanroep opnieuw uit. Neem contact op met Microsoft Ondersteuning als de fout zich blijft voordoen.

Abonnement nemen

Met deze API wordt een opgegeven aangeschaft SaaS-abonnement opgehaald voor een SaaS-aanbieding die de uitgever publiceert in de commerciële marketplace. Gebruik deze aanroep om alle beschikbare informatie voor een specifiek SaaS-abonnement op te halen op basis van de bijbehorende id in plaats van de API aan te roepen die wordt gebruikt voor het ophalen van een lijst met alle abonnementen.

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

Queryparameters:

Parameter	Weergegeven als
`ApiVersion`	Gebruik 2018-08-31.
`subscriptionId`	De unieke id van het aangeschafte SaaS-abonnement. Deze id wordt verkregen na het omzetten van het autorisatietoken voor de commerciële marketplace met behulp van de Resolve-API.

Aanvraagheaders:

Parameter	Weergegeven als
`content-type`	`application/json`
`x-ms-requestid`	Een unieke tekenreekswaarde voor het bijhouden van de aanvraag van de client, bij voorkeur een GUID. Als deze waarde niet is opgegeven, wordt er een gegenereerd en opgegeven in de antwoordheaders.
`x-ms-correlationid`	Een unieke tekenreekswaarde voor bewerking op de client. Deze parameter correleert alle gebeurtenissen van de clientbewerking met gebeurtenissen aan de serverzijde. Als deze waarde niet is opgegeven, wordt er een gegenereerd en opgegeven in de antwoordheaders.
`authorization`	Een uniek toegangstoken waarmee de uitgever wordt geïdentificeerd die deze API-aanroep maakt. De notatie is `"Bearer <access_token>"` wanneer de tokenwaarde wordt opgehaald door de uitgever, zoals wordt uitgelegd in Een token ophalen op basis van de Microsoft Entra-app.

Antwoordcodes:

Code: 200 retourneert details voor een SaaS-abonnement op basis van de subscriptionId opgegeven.

Voorbeeld van antwoordtekst:

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

Deze fout is vaak een symptoom van het niet correct uitvoeren van de SaaS-registratie .

Code: 404 Niet gevonden. Het SaaS-abonnement met het opgegeven subscriptionId abonnement kan niet worden gevonden.

Code: 500 Interne serverfout. Voer de API-aanroep opnieuw uit. Neem contact op met Microsoft Ondersteuning als de fout zich blijft voordoen.

Beschikbare abonnementen weergeven

Met deze API worden alle abonnementen voor een SaaS-aanbieding opgehaald die is geïdentificeerd door een subscriptionId specifieke aankoop van deze aanbieding. Gebruik deze aanroep om een lijst op te halen met alle privé- en openbare abonnementen die de begunstigde van een SaaS-abonnement kan bijwerken voor het abonnement. De geretourneerde plannen zijn beschikbaar in dezelfde geografie als het reeds aangeschafte abonnement.

Deze aanroep retourneert een lijst met abonnementen die beschikbaar zijn voor die klant, naast de abonnement die al is gekocht. De lijst kan worden gepresenteerd aan een eindgebruiker op de uitgeversite. Een eindgebruiker kan het abonnement wijzigen in een van de abonnementen in de geretourneerde lijst. Het wijzigen van het plan in een plan dat niet in de lijst staat, werkt niet.

Met deze API wordt ook de actieve privé-aanbiedings-id opgehaald die is gekoppeld (als u de API aanroept met planId-filter). Bij het aanroepen van api's met planId-filter worden de id-GUID's van de actieve privéaanbieding weergegeven in de hoofdtekst van het antwoord onder het knooppunt SourceOffers. De planId die is doorgegeven in de filterparameter, moet overeenkomen met de planId die de klant heeft gekocht.

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

Queryparameters:

Parameter	Weergegeven als
`ApiVersion`	Gebruik 2018-08-31.
`subscriptionId`	De unieke id van het aangeschafte SaaS-abonnement. Deze id wordt verkregen na het omzetten van het autorisatietoken voor de commerciële marketplace met behulp van de Resolve-API.
`planId (Optional)`	Plan-id van een specifiek plan dat u wilt ophalen. Dit is optioneel en als genegeerd alle plannen retourneert.

Aanvraagheaders:

Parameter	Weergegeven als
`content-type`	`application/json`
`x-ms-requestid`	Een unieke tekenreekswaarde voor het bijhouden van de aanvraag van de client, bij voorkeur een GUID. Als deze waarde niet is opgegeven, wordt er een gegenereerd en opgegeven in de antwoordheaders.
`x-ms-correlationid`	Een unieke tekenreekswaarde voor bewerking op de client. Deze parameter correleert alle gebeurtenissen van de clientbewerking met gebeurtenissen aan de serverzijde. Als deze waarde niet is opgegeven, wordt er een gegenereerd en opgegeven in de antwoordheaders.
`authorization`	Een uniek toegangstoken waarmee de uitgever wordt geïdentificeerd die deze API-aanroep maakt. De notatie is `"Bearer <access_token>"` wanneer de tokenwaarde wordt opgehaald door de uitgever, zoals wordt uitgelegd in Een token ophalen op basis van de Microsoft Entra-app.

Antwoordcodes:

Code: 200 retourneert een lijst met alle beschikbare abonnementen voor een bestaand SaaS-abonnement, inclusief het abonnement dat al is gekocht.

Als u een ongeldige (optionele) planId doorgeeft, wordt een lege lijst met plannen geretourneerd.

Voorbeeld van antwoordtekst:

{
  "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 niet gevonden. subscriptionId is niet gevonden.

Code: 403 Verboden. Het autorisatietoken is ongeldig, verlopen of is niet opgegeven. De aanvraag probeert mogelijk toegang te krijgen tot een SaaS-abonnement voor een aanbieding die is afgemeld of gepubliceerd met een andere Microsoft Entra-app-id van degene die wordt gebruikt om het autorisatietoken te maken.

Deze fout is vaak een symptoom van het niet correct uitvoeren van de SaaS-registratie .

Code: 500 Interne serverfout. Voer de API-aanroep opnieuw uit. Neem contact op met Microsoft Ondersteuning als de fout zich blijft voordoen.

Het plan voor het abonnement wijzigen

Gebruik deze API om het bestaande abonnement dat is gekocht voor een SaaS-abonnement bij te werken naar een nieuw abonnement (openbaar of privé). De uitgever moet deze API aanroepen wanneer een plan wordt gewijzigd aan de zijde van de uitgever voor een SaaS-abonnement dat is gekocht in de commerciële marketplace.

Deze API kan alleen worden aangeroepen voor actieve abonnementen. Elk plan kan worden gewijzigd in elk ander bestaand plan (openbaar of privé) maar niet op zichzelf. Voor privéplannen moet de tenant van de klant worden gedefinieerd als onderdeel van de doelgroep van het plan in partnercentrum.

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

Queryparameters:

Parameter	Weergegeven als
`ApiVersion`	Gebruik 2018-08-31.
`subscriptionId`	De unieke id van het aangeschafte SaaS-abonnement. Deze id wordt verkregen na het omzetten van het autorisatietoken voor de commerciële marketplace met behulp van de Resolve-API.

Aanvraagheaders:

Parameter	Weergegeven als
`content-type`	`application/json`
`x-ms-requestid`	Een unieke tekenreekswaarde voor het bijhouden van de aanvraag van de client, bij voorkeur een GUID. Als deze waarde niet is opgegeven, wordt er een gegenereerd en opgegeven in de antwoordheaders.
`x-ms-correlationid`	Een unieke tekenreekswaarde voor bewerking op de client. Deze parameter correleert alle gebeurtenissen van de clientbewerking met gebeurtenissen aan de serverzijde. Als deze waarde niet is opgegeven, wordt er een gegenereerd en opgegeven in de antwoordheaders.
`authorization`	Een uniek toegangstoken waarmee de uitgever wordt geïdentificeerd die deze API-aanroep maakt. De notatie is `"Bearer <access_token>"` wanneer de tokenwaarde wordt opgehaald door de uitgever, zoals wordt uitgelegd in Een token ophalen op basis van de Microsoft Entra-app.

Voorbeeld van nettolading aanvragen:

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

Antwoordcodes:

Code: 202 De aanvraag voor het wijzigen van het plan is asynchroon geaccepteerd en verwerkt. De partner zal naar verwachting de URL van de bewerkingslocatie peilen om te bepalen of de aanvraag voor het wijzigingsplan is geslaagd of mislukt. Polling moet elke paar seconden worden uitgevoerd totdat de uiteindelijke status Mislukt, Geslaagd of Conflict wordt ontvangen voor de bewerking. De uiteindelijke bewerkingsstatus moet snel worden geretourneerd, maar kan in sommige gevallen enkele minuten duren.

De partner ontvangt ook een webhookmelding wanneer de actie gereed is om te worden voltooid aan de kant van de commerciële marketplace. Alleen dan moet de uitgever het plan aan de zijde van de uitgever wijzigen.

Antwoordheaders:

Parameter	Weergegeven als
`Operation-Location`	URL om de status van de bewerking op te halen. Bijvoorbeeld `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=2018-08-31`

Code: 400 Ongeldige aanvraag: validatiefouten.

Het aangevraagde plan kan niet worden gevonden of het abonnement is niet beschikbaar voor de gebruiker.
Het aangevraagde plan is hetzelfde als het geabonneerde abonnement.
De status van het SaaS-abonnement is niet geabonneerd.
Het SaaS-abonnement dat wordt bijgewerkt, wordt aangeschaft door een Cloud Solution Provider (CSP). U moet samenwerken met de CSP-provider om deze actie uit te voeren.

Code: 403 Verboden. Het autorisatietoken is ongeldig, verlopen of is niet opgegeven. De aanvraag probeert toegang te krijgen tot een SaaS-abonnement voor een aanbieding die is gepubliceerd met een Microsoft Entra-app-id die verschilt van het abonnement dat wordt gebruikt om het autorisatietoken te maken.

Deze fout is vaak een symptoom van het niet correct uitvoeren van de SaaS-registratie .

Code: 404 Niet gevonden. Het SaaS-abonnement met de opgegeven subscriptionId kan niet worden gevonden.

Code: 500 Interne serverfout. Voer de API-aanroep opnieuw uit. Neem contact op met Microsoft Ondersteuning als de fout zich blijft voordoen.

Notitie

Het plan of de hoeveelheid seats kan tegelijk worden gewijzigd, niet beide.

Deze API kan alleen worden aangeroepen nadat u expliciete goedkeuring voor de wijziging van de eindgebruiker hebt gekregen.

Het aantal seats in het SaaS-abonnement wijzigen

Gebruik deze API om het aantal aangeschafte seats voor een SaaS-abonnement bij te werken (te verhogen of te verlagen). De uitgever moet deze API aanroepen wanneer het aantal seats wordt gewijzigd van de uitgeverszijde voor een SaaS-abonnement dat is gemaakt in de commerciële marketplace.

De hoeveelheid zitplaatsen mag niet groter zijn dan de hoeveelheid die is toegestaan in het huidige abonnement. In dit geval moet de uitgever het plan wijzigen voordat de hoeveelheid seats wordt gewijzigd.

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

Queryparameters:

Parameter	Weergegeven als
`ApiVersion`	Gebruik 2018-08-31.
`subscriptionId`	Een unieke id van het aangeschafte SaaS-abonnement. Deze id wordt verkregen na het omzetten van het autorisatietoken voor de commerciële marketplace met behulp van de Resolve-API.

Aanvraagheaders:

Parameter	Weergegeven als
`content-type`	`application/json`
`x-ms-requestid`	Een unieke tekenreekswaarde voor het bijhouden van de aanvraag van de client, bij voorkeur een GUID. Als deze waarde niet is opgegeven, wordt er een gegenereerd en opgegeven in de antwoordheaders.
`x-ms-correlationid`	Een unieke tekenreekswaarde voor bewerking op de client. Deze parameter correleert alle gebeurtenissen van de clientbewerking met gebeurtenissen aan de serverzijde. Als deze waarde niet is opgegeven, wordt er een gegenereerd en opgegeven in de antwoordheaders.
`authorization`	Een uniek toegangstoken waarmee de uitgever wordt geïdentificeerd die deze API-aanroep maakt. De notatie is `"Bearer <access_token>"` wanneer de tokenwaarde wordt opgehaald door de uitgever, zoals wordt uitgelegd in Een token ophalen op basis van de Microsoft Entra-app.

Voorbeeld van nettolading aanvragen:

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

Antwoordcodes:

Code: 202 De aanvraag om de hoeveelheid te wijzigen is geaccepteerd en asynchroon verwerkt. De partner zal naar verwachting de URL van de bewerkingslocatie peilen om te bepalen of de aanvraag voor wijzigingshoeveelheid is geslaagd of mislukt. Polling moet elke paar seconden worden uitgevoerd totdat de uiteindelijke status Mislukt, Geslaagd of Conflict wordt ontvangen voor de bewerking. De uiteindelijke bewerkingsstatus moet snel worden geretourneerd, maar kan in sommige gevallen enkele minuten duren.

De partner ontvangt ook een webhookmelding wanneer de actie gereed is om te worden voltooid aan de kant van de commerciële marketplace. Alleen dan moet de uitgever de hoeveelheidswijziging aan de kant van de uitgever aanbrengen.

Antwoordheaders:

Parameter	Weergegeven als
`Operation-Location`	Maak een koppeling naar een resource om de status van de bewerking op te halen. Bijvoorbeeld: `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=2018-08-31`.

Code: 400 Ongeldige aanvraag: validatiefouten.

De nieuwe hoeveelheid valt niet binnen het toegestane bereik.
De nieuwe hoeveelheid ontbreekt of 0.
De nieuwe hoeveelheid is gelijk aan de huidige hoeveelheid.
De status van het SaaS-abonnement is niet geabonneerd.
Het SaaS-abonnement dat wordt bijgewerkt, wordt aangeschaft door een Cloud Solution Provider (CSP). U moet samenwerken met de CSP-provider om deze actie uit te voeren.

Code: 403 Verboden. Het autorisatietoken is ongeldig, verlopen of is niet opgegeven. De aanvraag probeert toegang te krijgen tot een SaaS-abonnement voor een aanbieding die is gepubliceerd met een Microsoft Entra-app-id die verschilt van het abonnement dat wordt gebruikt om het autorisatietoken te maken.

Deze fout is vaak een symptoom van het niet correct uitvoeren van de SaaS-registratie .

Code: 404 Niet gevonden. Het SaaS-abonnement met de opgegeven subscriptionId kan niet worden gevonden.

Code: 500 Interne serverfout. Voer de API-aanroep opnieuw uit. Neem contact op met Microsoft Ondersteuning als de fout zich blijft voordoen.

Notitie

Slechts een plan of hoeveelheid kan tegelijk worden gewijzigd, niet beide.

Deze API kan alleen worden aangeroepen nadat de eindgebruiker expliciet goedkeuring heeft gekregen voor de wijziging.

Een abonnement opzeggen

Gebruik deze API om een opgegeven SaaS-abonnement af te melden. De uitgever hoeft deze API niet te gebruiken en we raden klanten aan om naar de commerciële marketplace te worden omgeleid om SaaS-abonnementen te annuleren.

Als de uitgever besluit om de annulering van een SaaS-abonnement dat is gekocht in de commerciële marketplace aan de zijde van de uitgever te implementeren, moet deze API worden aangeroepen. Na het voltooien van deze aanroep wordt de status van het abonnement afgemeld aan de Microsoft-zijde.

De klant wordt niet gefactureerd als een abonnement binnen 72 uur na aankoop wordt geannuleerd.

De klant wordt gefactureerd als een abonnement na de voorgaande respijtperiode wordt geannuleerd. De klant heeft direct na annulering geen toegang meer tot het SaaS-abonnement aan de Microsoft-zijde.

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

Queryparameters:

Parameter	Weergegeven als
`ApiVersion`	Gebruik 2018-08-31.
`subscriptionId`	De unieke id van het aangeschafte SaaS-abonnement. Deze id wordt verkregen na het omzetten van het autorisatietoken voor de commerciële marketplace met behulp van de Resolve-API.

Aanvraagheaders:

Parameter	Weergegeven als
`content-type`	`application/json`
`x-ms-requestid`	Een unieke tekenreekswaarde voor het bijhouden van de aanvraag van de client, bij voorkeur een GUID. Als deze waarde niet is opgegeven, wordt er een gegenereerd en opgegeven in de antwoordheaders.
`x-ms-correlationid`	Een unieke tekenreekswaarde voor bewerking op de client. Deze parameter correleert alle gebeurtenissen van de clientbewerking met gebeurtenissen aan de serverzijde. Als deze waarde niet is opgegeven, wordt er een gegenereerd en opgegeven in de antwoordheaders.
`authorization`	Een uniek toegangstoken waarmee de uitgever deze API-aanroep identificeert. De notatie is `"Bearer <access_token>"` wanneer de tokenwaarde wordt opgehaald door de uitgever, zoals wordt uitgelegd in Een token ophalen op basis van de Microsoft Entra-app.

Antwoordcodes:

Code: 202 De aanvraag voor afmelding is asynchroon geaccepteerd en verwerkt. De partner zal naar verwachting de URL van de bewerkingslocatie peilen om te bepalen of deze aanvraag is geslaagd of mislukt. Polling moet elke paar seconden worden uitgevoerd totdat de uiteindelijke status Mislukt, Geslaagd of Conflict wordt ontvangen voor de bewerking. De uiteindelijke bewerkingsstatus moet snel worden geretourneerd, maar kan in sommige gevallen enkele minuten duren.

De partner ontvangt ook een webhookmelding wanneer de actie is voltooid aan de kant van de commerciële marketplace. Alleen dan moet de uitgever het abonnement opzeggen aan de zijde van de uitgever.

Code: 200 Het abonnement heeft al de status Afmelden.

Antwoordheaders:

Parameter	Weergegeven als
`Operation-Location`	Maak een koppeling naar een resource om de status van de bewerking op te halen. Bijvoorbeeld: `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=2018-08-31`.

Code: 400 Ongeldige aanvraag. Verwijderen staat niet in allowedCustomerOperations de lijst voor dit SaaS-abonnement.

Code: 403 Verboden. Het autorisatietoken is ongeldig, verlopen of is niet beschikbaar.

Deze fout is vaak een symptoom van het niet correct uitvoeren van de SaaS-registratie .

Code: 404 Niet gevonden. Het SaaS-abonnement met subscriptionId is niet gevonden.

Code: 409

Verwijderen kan niet worden voltooid omdat het abonnement is vergrendeld vanwege een of meer bewerkingen die in behandeling zijn.

Code: 500 Interne serverfout. Voer de API-aanroep opnieuw uit. Neem contact op met Microsoft Ondersteuning als de fout zich blijft voordoen.

Zie de service-API's van de commerciële marketplace voor meer opties voor SaaS-aanbiedingen in de commerciële marketplace
De clients controleren en gebruiken voor verschillende programmeertalen en voorbeelden
Zie Een webhook implementeren in de SaaS-service voor testrichtlijnen

Delen via

SaaS-uitvoeringsabonnement-API's v2 op de commerciële marketplace van Microsoft

Een aangeschaft abonnement oplossen

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

Een abonnement activeren

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

Lijst met alle abonnementen ophalen

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

Abonnement nemen

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

Beschikbare abonnementen weergeven

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

Het plan voor het abonnement wijzigen

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

Het aantal seats in het SaaS-abonnement wijzigen

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

Een abonnement opzeggen

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

Feedback

Aanvullende resources

Delen via

SaaS-uitvoeringsabonnement-API's v2 op de commerciële marketplace van Microsoft

Een aangeschaft abonnement oplossen

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

Een abonnement activeren

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

Lijst met alle abonnementen ophalen

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

Abonnement nemen

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

Beschikbare abonnementen weergeven

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

Het plan voor het abonnement wijzigen

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

Het aantal seats in het SaaS-abonnement wijzigen

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

Een abonnement opzeggen

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

Gerelateerde inhoud

Feedback

Aanvullende resources

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

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

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

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

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

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

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

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