Share via

API per le operazioni di evasione SaaS v2 nel marketplace commerciale Microsoft

  • Articolo

Questo articolo descrive la versione 2 delle API per le operazioni di evasione SaaS.

Le operazioni sono utili per rispondere alle richieste che provengono dal webhook come parte delle azioni ChangePlan, ChangeQuantity e Reinstate. In questo modo è possibile accettare o rifiutare una richiesta tramite patch che l'operazione webhook ha esito positivo o negativo usando le API seguenti.

Questo vale solo per gli eventi webhook, ad esempio ChangePlan, ChangeQuantity e Reinstate che necessitano di un ACK. Non è necessaria alcuna azione da parte del fornitore di software indipendente (ISV) negli eventi Renew, Suspend e Unsubscribe perché sono eventi di sola notifica.

Elencare le operazioni in sospeso

Ottenere l'elenco delle operazioni in sospeso per la sottoscrizione SaaS specificata. Il server di pubblicazione deve confermare le operazioni restituite chiamando l'API Operation Patch.

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

Parametri di query:

Parametro Valore
ApiVersion Usare 2018-08-31.
subscriptionId Identificatore univoco della sottoscrizione SaaS acquistata. Questo ID viene ottenuto dopo aver risolto il token di autorizzazione del marketplace commerciale usando l'API Resolve.

Intestazioni della richiesta:

Parametro Valore
content-type application/json
x-ms-requestid Valore stringa univoco per tenere traccia della richiesta dal client, preferibilmente un GUID. Se questo valore non viene specificato, ne viene generato uno e fornito nelle intestazioni della risposta.
x-ms-correlationid Valore stringa univoco per l'operazione sul client. Questo parametro mette in correlazione tutti gli eventi dell'operazione del client con gli eventi sul lato server. Se questo valore non viene specificato, ne viene generato uno e fornito nelle intestazioni della risposta.
authorization Il formato è "Bearer <access_token>" quando il valore del token viene recuperato dall'editore, come illustrato in Ottenere un token basato sull'app Microsoft Entra.

Codici di risposta:

Codice: 200 Restituisce operazioni in sospeso nella sottoscrizione SaaS specificata.

Esempio di payload della risposta:

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

Restituisce json vuoto se non sono presenti operazioni in sospeso.

Codice: 400 Richiesta non valida: errori di convalida.

Codice: 403 Accesso negato. Il token di autorizzazione non è valido, è scaduto o non è stato specificato. La richiesta sta tentando di accedere a una sottoscrizione SaaS per un'offerta pubblicata con un ID app Microsoft Entra diverso da quello usato per creare il token di autorizzazione.

Questo errore è spesso un sintomo di non eseguire correttamente la registrazione SaaS.

Codice: 404 Non trovato. La sottoscrizione SaaS con subscriptionId non viene trovata.

Codice: errore interno del server 500. Ripetere la chiamata API. Se l'errore persiste, contattare il supporto tecnico Microsoft.

Ottenere lo stato dell'operazione

Questa API consente al server di pubblicazione di tenere traccia dello stato dell'operazione asincrona specificata: Annullare la sottoscrizione, ChangePlan o ChangeQuantity.

L'oggetto operationId per questa chiamata API può essere recuperato dal valore restituito da Operation-Location, dalla chiamata all'API Operazioni in sospeso o dal valore del <id> parametro ricevuto in una chiamata webhook.

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

Parametri di query:

Parametro Valore
ApiVersion Usare 2018-08-31.
subscriptionId Identificatore univoco della sottoscrizione SaaS acquistata. Questo ID viene ottenuto dopo aver risolto il token di autorizzazione del marketplace commerciale usando l'API Resolve.
operationId Identificatore univoco dell'operazione da recuperare.

Intestazioni della richiesta:

Parametro Valore
content-type application/json
x-ms-requestid Valore stringa univoco per tenere traccia della richiesta dal client, preferibilmente un GUID. Se questo valore non viene specificato, ne viene generato uno e fornito nelle intestazioni della risposta.
x-ms-correlationid Valore stringa univoco per l'operazione sul client. Questo parametro mette in correlazione tutti gli eventi dell'operazione del client con gli eventi sul lato server. Se questo valore non viene specificato, ne viene generato uno e fornito nelle intestazioni della risposta.
authorization Token di accesso univoco che identifica l'autore che effettua questa chiamata API. Il formato è "Bearer <access_token>" quando il valore del token viene recuperato dall'editore, come illustrato in Ottenere un token basato sull'app Microsoft Entra.

Codici di risposta:

Codice: 200 Ottiene i dettagli per l'operazione SaaS specificata.

Esempio di payload della risposta:

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

Codice: 403 Accesso negato. Il token di autorizzazione non è valido, è scaduto o non è stato specificato. La richiesta sta tentando di accedere a una sottoscrizione SaaS per un'offerta pubblicata con un ID app Microsoft Entra diverso da quello usato per creare il token di autorizzazione.

Questo errore è spesso un sintomo di non eseguire correttamente la registrazione SaaS.

Codice: 404 Non trovato.

  • La sottoscrizione con subscriptionId non viene trovata.
  • L'operazione con operationId non viene trovata.

Codice: errore interno del server 500. Ripetere la chiamata API. Se l'errore persiste, contattare il supporto tecnico Microsoft.

Aggiornare lo stato di un'operazione

Usare questa API per aggiornare lo stato di un'operazione in sospeso per indicare l'esito positivo o negativo dell'operazione sul lato editore.

L'oggetto operationId per questa chiamata API può essere recuperato dal valore restituito da Operation-Location, dalla chiamata all'API Operazioni in sospeso o dal valore del <id> parametro ricevuto in una chiamata webhook.

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

Parametri di query:

Parametro Valore
ApiVersion Usare 2018-08-31.
subscriptionId Identificatore univoco della sottoscrizione SaaS acquistata. Questo ID viene ottenuto dopo aver risolto il token di autorizzazione del marketplace commerciale usando l'API Resolve.
operationId Identificatore univoco dell'operazione da completare.

Intestazioni della richiesta:

Parametro Valore
content-type application/json
x-ms-requestid Valore stringa univoco per tenere traccia della richiesta dal client, preferibilmente un GUID. Se questo valore non viene specificato, ne viene generato uno e fornito nelle intestazioni della risposta.
x-ms-correlationid Valore stringa univoco per l'operazione sul client. Questo parametro mette in correlazione tutti gli eventi dell'operazione del client con gli eventi sul lato server. Se questo valore non viene specificato, ne viene generato uno e fornito nelle intestazioni della risposta.
authorization Token di accesso univoco che identifica l'autore che effettua questa chiamata API. Il formato è "Bearer <access_token>" quando il valore del token viene recuperato dall'editore, come illustrato in Ottenere un token basato sull'app Microsoft Entra.

Esempio di payload della richiesta:

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

Codici di risposta:

Codice: 200 Una chiamata per informare il completamento di un'operazione sul lato partner. Ad esempio, questa risposta potrebbe segnalare il completamento della modifica di postazioni o piani sul lato editore.

Codice: 403

  • Non consentito. Il token di autorizzazione non è disponibile, non è valido o è scaduto. La richiesta potrebbe tentare di accedere a una sottoscrizione che non appartiene al server di pubblicazione corrente.
  • Non consentito. Il token di autorizzazione non è valido, è scaduto o non è stato specificato. La richiesta sta tentando di accedere a una sottoscrizione SaaS per un'offerta pubblicata con un ID app Microsoft Entra diverso da quello usato per creare il token di autorizzazione.

Questo errore è spesso un sintomo di non eseguire correttamente la registrazione SaaS.

Codice: 404 Non trovato.

  • La sottoscrizione con subscriptionId non viene trovata.
  • L'operazione con operationId non viene trovata.

Codice: 409 Conflitto. Ad esempio, un aggiornamento più recente è già soddisfatto.

Codice: errore interno del server 500. Ripetere la chiamata API. Se l'errore persiste, contattare il supporto tecnico Microsoft.

Passaggi successivi