Delen via

SaaS-uitvoeringsbewerkingen-API's v2 in de commerciële marketplace van Microsoft

  • Artikel

Notitie

Als u SaaS-uitvoerings-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

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

Bewerkingen zijn handig om te reageren op aanvragen die via de webhook worden verzonden als onderdeel van ChangePlan- en ChangeQuantity- en Herstelacties. Dit biedt een mogelijkheid om een aanvraag te accepteren of af te wijzen per patch die webhookbewerking met succes of mislukt met behulp van de onderstaande API's.

Dit geldt alleen voor webhookgebeurtenissen zoals ChangePlan, ChangeQuantity en Reinstate die een ACK nodig hebben. Er is geen actie nodig van de onafhankelijke softwareleverancier (ISV) voor gebeurtenissen vernieuwen, onderbreken en afmelden, omdat ze alleen op de hoogte zijn van gebeurtenissen.

Openstaande bewerkingen weergeven

Haal een lijst op met de bewerkingen die in behandeling zijn voor het opgegeven SaaS-abonnement. De uitgever moet geretourneerde bewerkingen bevestigen door de Operation Patch-API aan te roepen.

Toevoegen https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations?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 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 bewerkingen die in behandeling zijn voor het opgegeven SaaS-abonnement.

Voorbeeld van nettolading van antwoord:

{
  "operations": [
    {
      "id": "<guid>", //Operation ID, should be provided in the operations patch API call
      "activityId": "<guid>", //not relevant
      "subscriptionId": "<guid>", // subscriptionId of the SaaS subscription that is being reinstated
      "offerId": "offer1", // purchased offer ID
      "publisherId": "contoso",
      "planId": "silver", // purchased plan ID
      "quantity": 20, // purchased amount of seats, will be empty is not relevant
      "action": "Reinstate",
      "timeStamp": "2018-12-01T00:00:00", // UTC
      "status": "InProgress" // the only status that can be returned in this case
    }
  ]
}

Retourneert lege json als er geen bewerkingen in behandeling zijn.

Code: 400 Ongeldige aanvraag: validatiefouten.

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: 404 Niet gevonden. Het SaaS-abonnement met subscriptionId is niet gevonden.

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

Bewerkingsstatus ophalen

Met deze API kan de uitgever de status van de opgegeven asynchrone bewerking bijhouden: Afmelden, ChangePlan of ChangeQuantity.

De operationId voor deze API-aanroep kan worden opgehaald uit de waarde die wordt geretourneerd door Operation-Location, de get pending Operations API-aanroep of de <id> parameterwaarde die is ontvangen in een webhook-aanroep.

Toevoegen https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?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.
operationId De unieke id van de bewerking die wordt opgehaald.

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: 200 Haalt details op voor de opgegeven SaaS-bewerking.

Voorbeeld van nettolading van antwoord:

Response body:
{
  "id  ": "<guid>", //Operation ID, should be provided in the patch operation API call
  "activityId": "<guid>", //not relevant
  "subscriptionId": "<guid>", // subscriptionId of the SaaS subscription for which this operation is relevant
  "offerId": "offer1", // purchased offer ID
  "publisherId": "contoso",
  "planId": "silver", // purchased plan ID
  "quantity": 20, // purchased amount of seats
  "action": "ChangePlan", // Can be ChangePlan, ChangeQuantity or Reinstate
  "timeStamp": "2018-12-01T00:00:00", // UTC
  "status": "InProgress", // Possible values: NotStarted, InProgress, Failed, Succeeded, Conflict (new quantity / plan is the same as existing)
  "errorStatusCode": "",
  "errorMessage": ""
}

Code: 403 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: 404 Niet gevonden.

  • Abonnement met subscriptionId is niet gevonden.
  • Bewerking met operationId is niet gevonden.

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

De status van een bewerking bijwerken

Gebruik deze API om de status van een bewerking in behandeling bij te werken om aan te geven dat de bewerking is geslaagd of mislukt aan de zijde van de uitgever.

De operationId voor deze API-aanroep kan worden opgehaald uit de waarde die wordt geretourneerd door Operation-Location, de get pending Operations API-aanroep of de <id> parameterwaarde die is ontvangen in een webhook-aanroep.

Lap https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?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.
operationId De unieke id van de bewerking die wordt voltooid.

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:

{
  "status": "Success" // Allowed Values: Success/Failure. Indicates the status of the operation on ISV side.
}

Antwoordcodes:

Code: 200 Een aanroep om de voltooiing van een bewerking aan de partnerzijde te melden. Dit antwoord kan bijvoorbeeld duiden op de voltooiing van de wijziging van seats of plannen aan de zijde van de uitgever.

Code: 403

  • Verboden. Het autorisatietoken is niet beschikbaar, is ongeldig of verlopen. De aanvraag probeert mogelijk toegang te krijgen tot een abonnement dat niet tot de huidige uitgever behoort.
  • 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: 404 Niet gevonden.

  • Abonnement met subscriptionId is niet gevonden.
  • Bewerking met operationId is niet gevonden.

Code: 409 Conflict. Er is bijvoorbeeld al een nieuwere update voltooid.

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

Gerelateerde inhoud