Dela via

API:er för SaaS-uppfyllandeåtgärder v2 på Microsofts kommersiella marknadsplats

  • Artikel

Not

För att kunna anropa Api:er för SaaS-uppfyllandeåtgärder måste du skapa en utgivares auktoriseringstoken med rätt resurs-ID. Lär dig hur du hämta utgivarens auktoriseringstoken

I den här artikeln beskrivs version 2 av API:erna för SaaS-uppfyllandeåtgärder.

Åtgärder är användbara för att svara på alla begäranden som kommer via webhooken som en del av åtgärderna ChangePlan, ChangeQuantity och Reinstate. Detta ger en möjlighet att acceptera eller avvisa en begäran genom att korrigera den webhook-åtgärden med lyckade eller misslyckade med hjälp av API:erna nedan.

Detta gäller endast webhook-händelser som ChangePlan, ChangeQuantity och Reinstate som behöver en ACK. Ingen åtgärd krävs från den oberoende programvaruleverantören (ISV) för händelser för förnyelse, paus och avregistrering eftersom de endast är aviseringshändelser.

Lista utestående åtgärder

Hämta en lista över väntande åtgärder för den angivna SaaS-prenumerationen. Utgivaren bör bekräfta returnerade åtgärder genom att anropa Operation Patch API.

Hämta https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations?api-version=<ApiVersion>

Frågeparametrar:

Parameter Värde
ApiVersion Använd 2018-08-31.
subscriptionId Den unika identifieraren för den köpta SaaS-prenumerationen. Det här ID:t hämtas efter att du har löst auktoriseringstoken för den kommersiella marknadsplatsen med hjälp av Resolve API.

Begärandehuvuden:

Parameter Värde
content-type application/json
x-ms-requestid Ett unikt strängvärde för att spåra begäran från klienten, helst ett GUID. Om det här värdet inte anges genereras ett värde och anges i svarshuvudena.
x-ms-correlationid Ett unikt strängvärde för åtgärden på klienten. Den här parametern korrelerar alla händelser från klientåtgärden med händelser på serversidan. Om det här värdet inte anges genereras ett värde och anges i svarshuvudena.
authorization Formatet är "Bearer <access_token>" när tokenvärdet hämtas av utgivaren enligt beskrivningen i Hämta en token baserat på Microsoft Entra-appen.

Svarskoder:

Kod: 200 Returnerar väntande åtgärder för den angivna SaaS-prenumerationen.

Exempel på svarsnyttolast:

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

Returnerar tom json om inga åtgärder väntar.

Kod: 400 Felaktig begäran: verifieringsfel.

Kod: 401 Obehörig. Auktoriseringstoken är ogiltig eller har upphört att gälla. Begäran försöker komma åt en SaaS-prenumeration för ett erbjudande som publicerades med ett annat Microsoft Entra-app-ID än det som användes för att skapa autentiseringstoken.

Kod: 403 Förbjudet. Auktoriseringstoken är ogiltig, har inte angetts eller har inte fått tillräckliga behörigheter. Ange en giltig auktoriseringstoken.

Det här felet är ofta ett symptom på att inte utföra SaaS-registreringen korrekt.

Kod: 404 Hittades inte. Det går inte att hitta SaaS-prenumerationen med subscriptionId.

Kod: 500 Internt serverfel. Försök igen med API-anropet. Om felet kvarstår kontaktar du Microsoft-supporten.

Hämta åtgärdsstatus

Med det här API:et kan utgivaren spåra statusen för den angivna asynkrona åtgärden: Avregistrera, ChangePlaneller ChangeQuantity.

operationId för det här API-anropet kan hämtas från värdet som returneras av Operation-Location, anropet hämta väntande Operations API eller det <id> parametervärde som tas emot i ett webhook-anrop.

Hämta https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=<ApiVersion>

Frågeparametrar:

Parameter Värde
ApiVersion Använd 2018-08-31.
subscriptionId Den unika identifieraren för den köpta SaaS-prenumerationen. Det här ID:t hämtas efter att du har löst auktoriseringstoken för den kommersiella marknadsplatsen med hjälp av Resolve API.
operationId Den unika identifieraren för åtgärden som hämtas.

Begärandehuvuden:

Parameter Värde
content-type application/json
x-ms-requestid Ett unikt strängvärde för att spåra begäran från klienten, helst ett GUID. Om det här värdet inte anges genereras ett värde och anges i svarshuvudena.
x-ms-correlationid Ett unikt strängvärde för åtgärden på klienten. Den här parametern korrelerar alla händelser från klientåtgärden med händelser på serversidan. Om det här värdet inte anges genereras ett värde och anges i svarshuvudena.
authorization En unik åtkomsttoken som identifierar utgivaren som gör det här API-anropet. Formatet är "Bearer <access_token>" när tokenvärdet hämtas av utgivaren enligt beskrivningen i Hämta en token baserat på Microsoft Entra-appen.

Svarskoder:

Kod: 200 Hämtar information om den angivna SaaS-åtgärden.

Exempel på svarsnyttolast:

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": ""
}

Kod: 401 Obehörig. Auktoriseringstoken är ogiltig eller har upphört att gälla. Begäran försöker komma åt en SaaS-prenumeration för ett erbjudande som publicerades med ett annat Microsoft Entra-app-ID än det som användes för att skapa autentiseringstoken.

Kod: 403 Förbjudet. Auktoriseringstoken är ogiltig, har inte angetts eller har inte fått tillräckliga behörigheter. Ange en giltig auktoriseringstoken.

Det här felet är ofta ett symptom på att inte utföra SaaS-registreringen korrekt.

Kod: 404 Hittades inte.

  • Det går inte att hitta en prenumeration med subscriptionId.
  • Åtgärden med operationId hittades inte.

Kod: 500 Internt serverfel. Försök igen med API-anropet. Om felet kvarstår kontaktar du Microsoft-supporten.

Uppdatera status för en åtgärd

Använd det här API:et för att uppdatera statusen för en väntande åtgärd för att ange att åtgärden lyckades eller misslyckades på utgivarsidan.

operationId för det här API-anropet kan hämtas från värdet som returneras av Operation-Location, anropet hämta väntande Operations API eller det <id> parametervärde som tas emot i ett webhook-anrop.

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

Frågeparametrar:

Parameter Värde
ApiVersion Använd 2018-08-31.
subscriptionId Den unika identifieraren för den köpta SaaS-prenumerationen. Det här ID:t hämtas efter att du har löst auktoriseringstoken för den kommersiella marknadsplatsen med hjälp av Resolve API.
operationId Den unika identifieraren för den åtgärd som slutförs.

Begärandehuvuden:

Parameter Värde
content-type application/json
x-ms-requestid Ett unikt strängvärde för att spåra begäran från klienten, helst ett GUID. Om det här värdet inte anges genereras ett värde och anges i svarshuvudena.
x-ms-correlationid Ett unikt strängvärde för åtgärden på klienten. Den här parametern korrelerar alla händelser från klientåtgärden med händelser på serversidan. Om det här värdet inte anges genereras ett värde och anges i svarshuvudena.
authorization En unik åtkomsttoken som identifierar utgivaren som gör det här API-anropet. Formatet är "Bearer <access_token>" när tokenvärdet hämtas av utgivaren enligt beskrivningen i Hämta en token baserat på Microsoft Entra-appen.

Exempel på begärandenyttolast:

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

Svarskoder:

Kod: 200 Ett anrop för att informera om slutförandet av en åtgärd på partnersidan. Det här svaret kan till exempel signalera att antalet platser eller planer på utgivarsidan har slutförts.

Kod: 401 Obehörig. Auktoriseringstoken är ogiltig eller har upphört att gälla. Begäran försöker komma åt en SaaS-prenumeration för ett erbjudande som publicerades med ett annat Microsoft Entra-app-ID än det som användes för att skapa autentiseringstoken.

Kod: 403 Förbjudet. Auktoriseringstoken är ogiltig, har inte angetts eller har inte fått tillräckliga behörigheter. Ange en giltig auktoriseringstoken.

Det här felet är ofta ett symptom på att inte utföra SaaS-registreringen korrekt.

Kod: 404 Hittades inte.

  • Det går inte att hitta en prenumeration med subscriptionId.
  • Åtgärden med operationId hittades inte.

Kod: 409 Konflikt. En nyare uppdatering har till exempel redan slutförts.

Kod: 500 Internt serverfel. Försök igen med API-anropet. Om felet kvarstår kontaktar du Microsoft-supporten.

Relaterat innehåll