API Opérations de traitement SaaS v2 dans la place de marché commerciale Microsoft

  • Article

Cet article décrit la version 2 des API d’opérations de traitement SaaS.

Les opérations sont utiles pour répondre à toutes les demandes qui proviennent du webhook dans le cadre des actions ChangePlan, ChangeQuantity et Rétablir. Cela offre la possibilité d’accepter ou de rejeter une requête par patch qui effectue une opération webhook avec Réussite ou Échec à l’aide des API ci-dessous.

Cela s’applique uniquement aux événements webhook tels que ChangePlan, ChangeQuantity et Rétablir qui ont besoin d’un ACK. Aucune action n’est nécessaire auprès du fournisseur de logiciels indépendant (ISV) sur les événements Renouveler, Suspendre et Désabonner, car ils sont des événements de notification uniquement.

Liste des opérations en attente

Obtenir la liste des opérations en attente pour l’abonnement SaaS spécifié. L’éditeur doit accuser réception des opérations retournées en appelant l’API Patch d’opérations.

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

Paramètres de requête :

Paramètre Valeur
ApiVersion Utilisez 2018-08-31.
subscriptionId Identificateur unique de l’abonnement SaaS acheté. Cet ID est obtenu après résolution du jeton d’autorisation de la Place de marché à l’aide de l’API Résolution.

En-têtes de demande :

Paramètre Valeur
content-type application/json
x-ms-requestid Valeur de chaîne unique pour le suivi de la requête du client, de préférence un GUID. Si cette valeur n’est pas fournie, une valeur sera générée et fournie dans les en-têtes de réponse.
x-ms-correlationid Valeur de chaîne unique pour l’opération sur le client. Ce paramètre sert à corréler tous les événements de l’opération client avec les événements côté serveur. Si cette valeur n’est pas fournie, une valeur sera générée et fournie dans les en-têtes de réponse.
authorization Le format est "Bearer <access_token>" le moment où la valeur du jeton est récupérée par l’éditeur, comme expliqué dans Obtenir un jeton basé sur l’application Microsoft Entra.

Codes de réponse :

Code : 200 Renvoie les opérations en attente sur l’abonnement SaaS spécifié.

Exemple de charge utile de réponse :

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

Renvoie un objet json vide si aucune opération n’est en attente.

Code : 400 Demande incorrecte : échecs de validation.

Code : 403 Interdit. Le jeton d’autorisation n’est pas valide, a expiré ou n’a pas été fourni. La demande tente d’accéder à un abonnement SaaS pour une offre publiée avec un ID d’application Microsoft Entra différent de celui utilisé pour créer le jeton d’autorisation.

Cette erreur est souvent le symptôme de l’absence d’une inscription SaaS correcte.

Code : 404 Introuvable. L’abonnement SaaS avec subscriptionId lequel il est introuvable.

Code : erreur de serveur interne 500. Renouvelez l’appel d’API. Si l’erreur persiste, contactez le support technique Microsoft.

Obtenir l’état d’une opération

Cette API permet à l’éditeur de suivre l’état de l’opération asynchrone spécifiée : Unsubscribe, ChangePlan ou ChangeQuantity.

La valeur operationId pour cet appel d’API peut être récupérée à partir de la valeur retournée par Operation-Location, l’appel d’API pour obtenir les opérations en attente, ou la valeur de paramètre <id> reçue dans un appel webhook.

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

Paramètres de requête :

Paramètre Valeur
ApiVersion Utilisez 2018-08-31.
subscriptionId Identificateur unique de l’abonnement SaaS acheté. Cet ID est obtenu après résolution du jeton d’autorisation de la Place de marché à l’aide de l’API Résolution.
operationId Identificateur unique de l'opération en cours de récupération.

En-têtes de demande :

Paramètre Valeur
content-type application/json
x-ms-requestid Valeur de chaîne unique pour le suivi de la requête du client, de préférence un GUID. Si cette valeur n’est pas fournie, une valeur sera générée et fournie dans les en-têtes de réponse.
x-ms-correlationid Valeur de chaîne unique pour l’opération sur le client. Ce paramètre sert à corréler tous les événements de l’opération client avec les événements côté serveur. Si cette valeur n’est pas fournie, une valeur sera générée et fournie dans les en-têtes de réponse.
authorization Jeton d’accès unique qui identifie le serveur de publication qui effectue cet appel d’API. Le format est "Bearer <access_token>" le moment où la valeur du jeton est récupérée par l’éditeur, comme expliqué dans Obtenir un jeton basé sur l’application Microsoft Entra.

Codes de réponse :

Code : 200 Obtient les détails de l’opération SaaS spécifiée.

Exemple de charge utile de réponse :

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 Interdit. Le jeton d’autorisation n’est pas valide, a expiré ou n’a pas été fourni. La demande tente d’accéder à un abonnement SaaS pour une offre publiée avec un ID d’application Microsoft Entra différent de celui utilisé pour créer le jeton d’autorisation.

Cette erreur est souvent le symptôme de l’absence d’une inscription SaaS correcte.

Code : 404 Introuvable.

  • L’abonnement avec subscriptionId lequel il est introuvable est introuvable.
  • L’opération avec operationId n’est pas trouvée.

Code : erreur de serveur interne 500. Renouvelez l’appel d’API. Si l’erreur persiste, contactez le support technique Microsoft.

Mettre à jour l’état d’une opération

Utilisez cette API afin de mettre à jour l’état d’une opération en attente pour indiquer la réussite ou l’échec de l’opération côté éditeur.

La valeur operationId pour cet appel d’API peut être récupérée à partir de la valeur retournée par Operation-Location, l’appel d’API pour obtenir les opérations en attente, ou la valeur de paramètre <id> reçue dans un appel webhook.

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

Paramètres de requête :

Paramètre Valeur
ApiVersion Utilisez 2018-08-31.
subscriptionId Identificateur unique de l’abonnement SaaS acheté. Cet ID est obtenu après résolution du jeton d’autorisation de la Place de marché à l’aide de l’API Résolution.
operationId Identificateur unique de l’opération terminée.

En-têtes de demande :

Paramètre Valeur
content-type application/json
x-ms-requestid Valeur de chaîne unique pour le suivi de la requête du client, de préférence un GUID. Si cette valeur n’est pas fournie, une valeur sera générée et fournie dans les en-têtes de réponse.
x-ms-correlationid Valeur de chaîne unique pour l’opération sur le client. Ce paramètre sert à corréler tous les événements de l’opération client avec les événements côté serveur. Si cette valeur n’est pas fournie, une valeur sera générée et fournie dans les en-têtes de réponse.
authorization Jeton d’accès unique qui identifie l’éditeur effectuant cet appel d’API. Le format est "Bearer <access_token>" le moment où la valeur du jeton est récupérée par l’éditeur, comme expliqué dans Obtenir un jeton basé sur l’application Microsoft Entra.

Exemple de demande de charge utile :

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

Codes de réponse :

Code : 200 Un appel pour informer la fin d’une opération côté partenaire. Par exemple, cette réponse peut signaler la fin de la modification de postes ou de plans côté éditeur.

Code : 403

  • Interdit. Le jeton d’autorisation n’est pas disponible, n’est pas valide ou a expiré. La demande peut tenter d’accéder à un abonnement qui n’appartient pas au serveur de publication actuel.
  • Interdit. Le jeton d’autorisation n’est pas valide, a expiré ou n’a pas été fourni. La demande tente d’accéder à un abonnement SaaS pour une offre publiée avec un ID d’application Microsoft Entra différent de celui utilisé pour créer le jeton d’autorisation.

Cette erreur est souvent le symptôme de l’absence d’une inscription SaaS correcte.

Code : 404 Introuvable.

  • L’abonnement avec subscriptionId lequel il est introuvable est introuvable.
  • L’opération avec operationId n’est pas trouvée.

Code : conflit 409. Par exemple, une mise à jour plus récente est déjà traitée.

Code : erreur de serveur interne 500. Renouvelez l’appel d’API. Si l’erreur persiste, contactez le support technique Microsoft.

Étapes suivantes