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

  • Artikel

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 åtgärdskorrigerings-API:et.

Få 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: 403 Förbjudet. Auktoriseringstoken är ogiltig, har upphört att gälla eller har inte angetts. Begäran försöker komma åt en SaaS-prenumeration för ett erbjudande som publiceras med ett annat Microsoft Entra-app-ID än det som användes för att skapa auktoriseringstoken.

Det här felet är ofta ett symptom på att SaaS-registreringen inte utförs 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. Kontakta Microsofts support om felet kvarstår.

Hämta åtgärdsstatus

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

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

Få 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: 403 Förbjudet. Auktoriseringstoken är ogiltig, har upphört att gälla eller har inte angetts. Begäran försöker komma åt en SaaS-prenumeration för ett erbjudande som publiceras med ett annat Microsoft Entra-app-ID än det som användes för att skapa auktoriseringstoken.

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

Kod: 404 Hittades inte.

  • Det går inte att hitta prenumerationen med subscriptionId .
  • Det gick inte att hitta åtgärden med operationId .

Kod: 500 Internt serverfel. Försök igen med API-anropet. Kontakta Microsofts support om felet kvarstår.

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.

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

Patch 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: 403

  • Förbjudet. Auktoriseringstoken är inte tillgänglig, är ogiltig eller har upphört att gälla. Begäran kanske försöker komma åt en prenumeration som inte tillhör den aktuella utgivaren.
  • Förbjudet. Auktoriseringstoken är ogiltig, har upphört att gälla eller har inte angetts. Begäran försöker komma åt en SaaS-prenumeration för ett erbjudande som publiceras med ett annat Microsoft Entra-app-ID än det som användes för att skapa auktoriseringstoken.

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

Kod: 404 Hittades inte.

  • Det går inte att hitta prenumerationen med subscriptionId .
  • Det gick inte att hitta åtgärden med operationId .

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

Kod: 500 Internt serverfel. Försök igen med API-anropet. Kontakta Microsofts support om felet kvarstår.

Nästa steg