Partager via

API d’opérations d’exécution SaaS v2 sur la place de marché commerciale Microsoft

Remarque

Pour pouvoir appeler les API d’opérations d’exécution SaaS, vous devez créer un jeton d’autorisation de l’éditeur à l’aide de l’ID de ressource correct. Découvrez comment obtenir le jeton d’autorisation de l’éditeur

Cet article décrit la version 2 des API d’opérations d’exécution SaaS.

Les opérations sont utiles pour répondre à toutes les demandes qui proviennent du webhook dans le cadre des actions ChangePlan, ChangeQuantity et Reinstate. Cela permet d’accepter ou de rejeter une demande par le correctif de cette opération de webhook avec Success ou Failure à l’aide des API suivantes.

Cela ne s’applique qu’aux événements de webhook tels que ChangePlan, ChangeQuantity et Reinstate qui nécessitent un accusé de réception. Aucune action n’est requise de la part de l’éditeur de logiciels indépendant (ISV) sur les événements de renouvellement, de suspension et de désabonnement, car il s’agit d’événements de notification uniquement.

Énumérer les opérations en cours

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

Avoir 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 L’identifiant unique de l’abonnement SaaS acheté. Cet ID est obtenu après la résolution du jeton d’autorisation de la place de marché commerciale à l’aide de l’API Resolve.

En-têtes de requête HTTP :

Paramètre Valeur
content-type application/json
x-ms-requestid Valeur de chaîne unique pour le suivi de la demande du client, de préférence un GUID. Si cette valeur n’est pas fournie, une valeur est 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 met en corrélation tous les événements de l’opération cliente avec les événements côté serveur. Si cette valeur n’est pas fournie, une valeur est générée et fournie dans les en-têtes de réponse.
authorization Le format est "Bearer <access_token>" lorsque 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 json vide si aucune opération n’est en attente.

Code : 400 Requête incorrecte : échecs de validation.

Code : 401 Non autorisé. Le jeton d’autorisation n’est pas valide ou a expiré. 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’authentification.

Code : 403 Interdit. Le jeton d’autorisation n’est pas valide, n’a pas été fourni ou n’a pas été fourni avec des autorisations suffisantes. Assurez-vous de fournir un jeton d’autorisation valide.

Cette erreur est souvent le symptôme d’un défaut d’effectuer correctement l’enregistrement SaaS .

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

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

Obtenir l’état de l’opération

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

Le operationId pour cet appel d’API peut être récupéré à partir de la valeur renvoyée par Operation-Location, de l’appel d’API get pending Operations ou de la <id> valeur de paramètre reçue dans un appel de webhook.

Avoir 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 L’identifiant unique de l’abonnement SaaS acheté. Cet ID est obtenu après la résolution du jeton d’autorisation de la place de marché commerciale à l’aide de l’API Resolve.
operationId Identificateur unique de l’opération en cours d’extraction.

En-têtes de requête HTTP :

Paramètre Valeur
content-type application/json
x-ms-requestid Valeur de chaîne unique pour le suivi de la demande du client, de préférence un GUID. Si cette valeur n’est pas fournie, une valeur est 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 met en corrélation tous les événements de l’opération cliente avec les événements côté serveur. Si cette valeur n’est pas fournie, une valeur est générée et fournie dans les en-têtes de réponse.
authorization Jeton d’accès unique qui identifie l’éditeur qui effectue cet appel d’API. Le format est "Bearer <access_token>" lorsque 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 : 401 Non autorisé. Le jeton d’autorisation n’est pas valide ou a expiré. 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’authentification.

Code : 403 Interdit. Le jeton d’autorisation n’est pas valide, n’a pas été fourni ou n’a pas été fourni avec des autorisations suffisantes. Assurez-vous de fournir un jeton d’autorisation valide.

Cette erreur est souvent le symptôme d’un défaut d’effectuer correctement l’enregistrement SaaS .

Code : 404 Introuvable.

  • L’abonnement avec subscriptionId est introuvable.
  • Operation with operationId n’est pas trouvé.

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

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

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

Le operationId pour cet appel d’API peut être récupéré à partir de la valeur renvoyée par Operation-Location, de l’appel d’API get pending Operations ou de la <id> valeur de paramètre reçue dans un appel de webhook.

Rapiécer 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 L’identifiant unique de l’abonnement SaaS acheté. Cet ID est obtenu après la résolution du jeton d’autorisation de la place de marché commerciale à l’aide de l’API Resolve.
operationId Identificateur unique de l’opération en cours d’achèvement.

En-têtes de requête HTTP :

Paramètre Valeur
content-type application/json
x-ms-requestid Valeur de chaîne unique pour le suivi de la demande du client, de préférence un GUID. Si cette valeur n’est pas fournie, une valeur est 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 met en corrélation tous les événements de l’opération cliente avec les événements côté serveur. Si cette valeur n’est pas fournie, une valeur est générée et fournie dans les en-têtes de réponse.
authorization Jeton d’accès unique qui identifie l’éditeur qui effectue cet appel d’API. Le format est "Bearer <access_token>" lorsque 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 charge utile de demande :

{
  "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 de la réalisation d’une opération côté partenaire. Par exemple, cette réponse pourrait signaler l’achèvement d’un changement de siège ou de plans du côté de l’éditeur.

Code : 401 Non autorisé. Le jeton d’autorisation n’est pas valide ou a expiré. 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’authentification.

Code : 403 Interdit. Le jeton d’autorisation n’est pas valide, n’a pas été fourni ou n’a pas été fourni avec des autorisations suffisantes. Assurez-vous de fournir un jeton d’autorisation valide.

Cette erreur est souvent le symptôme d’un défaut d’effectuer correctement l’enregistrement SaaS .

Code : 404 Introuvable.

  • L’abonnement avec subscriptionId est introuvable.
  • Operation with operationId n’est pas trouvé.

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

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

Contenu connexe