Planifier les modifications d’un nouvel abonnement commercial à l’aide des API de l’Espace partenaires

S’applique à : Centre de partenaires

Cet article explique comment vous pouvez utiliser l’API de l’Espace partenaires pour planifier les modifications d’un nouvel abonnement commercial, qui n’ont lieu qu’au moment du renouvellement. Cette API prend en charge les nouveaux abonnements commerciaux, sous licence et logiciels.

Remarque

Les nouvelles expériences commerciales pour les services basés sur des licences incluent de nombreuses nouvelles fonctionnalités et sont disponibles pour tous les Fournisseur de solutions Cloud (CSP). Pour plus d’informations, consultez la Vue d’ensemble des nouvelles expériences commerciales.

La création de modifications programmées vous permet de modifier votre abonnement, automatiquement, lors du prochain renouvellement. En planifiant les modifications, vous pouvez choisir d’augmenter ou de diminuer le nombre de licences, de modifier la durée et la fréquence de facturation, et même de mettre à niveau la référence SKU. Les modifications de planification vous permettent d’apporter des modifications à votre abonnement lors du renouvellement, plutôt qu’immédiatement pendant la période en cours.

Important

Si vous effectuez une modification à mi-parcours (immédiate) avant votre date de renouvellement, toutes les modifications planifiées qui devaient avoir lieu lors du renouvellement sont supprimées.

Conditions préalables

  • Informations d’identification décrites dans l’authentification de l’Espace partenaires. Ce scénario prend en charge l'authentification avec des identifiants d'application autonomes ainsi que des identifiants combinés application+utilisateur.

  • ID du client (customer-tenant-id). Si vous ne connaissez pas l'identifiant du client, vous pouvez le rechercher dans le Centre de Partenaires en sélectionnant l'espace de travail Clients, puis le client dans la liste des clients, puis Compte. Dans la page Compte du client, recherchez l’ID Microsoft dans la section Informations sur le compte client. L’ID Microsoft est le même que l’ID de client (customer-tenant-id).

  • ID d’abonnement.

  • Le renouvellement automatique est activé sur l’abonnement.

Méthode du Centre Partenaire

Pour planifier les modifications d’un abonnement dans l’Espace partenaires :

  1. Sélectionnez un client.

  2. Sélectionnez l’abonnement pour lequel vous souhaitez planifier des modifications.

  3. Activez le renouvellement automatique.

  4. Sélectionnez Gérer le renouvellement.

  5. Apportez des modifications à l’abonnement afin qu’elles prennent effet lors du renouvellement.

  6. Sélectionnez OK pour fermer le panneau latéral.

  7. sélectionnez Soumettre pour enregistrer les modifications.

Remarque

Les renouvellements sont traités après le dernier jour d’un trimestre, à partir de 12h00 UTC le lendemain. Les renouvellements sont traités dans une file d’attente et peuvent prendre jusqu’à 24 heures.

C#

Pour planifier les modifications de l’abonnement d’un client :

  1. Obtenez l’abonnement par ID.
  2. Obtenez l’éligibilité à la transition pour le type d’éligibilité à la transition programmée.
  3. Créez un objet ScheduledNextTermInstructions et définissez-le sur la propriété de l’abonnement.
  4. Appelez la méthode Patch() pour mettre à jour l’abonnement avec les modifications planifiées.
var selectedSubscription = subscriptionOperations.Get();
selectedSubscription.ScheduledNextTermInstructions = new ScheduledNextTermInstructions
{
    Product = new ProductTerm
    {
        ProductId = changeToProductId,
        SkuId = changeToSkuId,
        AvailabilityId = changeToAvailabilityId,
        BillingCycle = changeToBillingCycle,
        TermDuration = changeToTermDuration,
    },
    Quantity = changeToQuantity,
    customTermEndDate = DateTime,
};
var updatedSubscription = subscriptionOperations.Patch(selectedSubscription);

Pour planifier des modifications pour l’abonnement d’un client, lorsque la modification planifiée souhaitée concerne un autre produit :

  1. Obtenez l’abonnement par ID.
  2. Obtenez l’éligibilité à la transition pour le type d’éligibilité à la transition programmée.
  3. Appelez la méthode Patch() pour mettre à jour l’abonnement avec les modifications planifiées.

Requête REST

Syntaxe de la requête

Méthode URI de la requête
RAPIÉCER [https://blogs.technet.microsoft.com/askperf/2008/11/18/disabling-unnecessary-services-a-word-to-the-wise/]() {baseURL}/v1/customers/{customer-tenant-id}/subscriptions/{subscription-id} HTTP/1.1

Paramètre d’URI

Ce tableau répertorie les paramètres de requête requis pour appeler l’API.

Nom Catégorie Obligatoire Descriptif
customer-tenant-ID guid O Un GUID correspondant au client.
identifiant-de-l’abonnement guid O Un GUID correspondant à l’abonnement.

En-têtes de requête

Pour plus d’informations, consultez En-têtes REST de l’Espace Partenaires.

Corps de la requête

Une ressource d’abonnement complète est requise dans le corps de la demande, avec la scheduledNextTermInstructions propriété définie. Pour planifier les modifications de votre abonnement, assurez-vous que la propriété AutoRenewEnabled est définie sur true.

Pour les offres avec ID de disponibilité en fin de commercialisation avec conversions (EndofSaleWithConversions) :

  1. GetTransitionEligibility renvoie CatalogItemID.

    a) Assurez-vous de définir le type d’éligibilité sur « Planifié », sinon la valeur par défaut sera « Immédiat ».

  2. Utilisez CatalogItemID pour extraire availabilityID.

Si vous utilisez GET Availabilityabilities pour déterminer la disponibilité des instructions NextTerm programmées et si tous les termes sont à l’état EOS, vous recevrez une liste vide. La meilleure façon de déterminer les chemins d’accès valides consiste à appeler l’API GetTransitionEligibilty pour renvoyer les options valides.

Terrain Catégorie Obligatoire Descriptif
scheduledNextTermInstructions objet O Définit les instructions pour la prochaine échéance de l’abonnement. La propriété contient l’objet product et le quantity champ.

Utilisation de scheduledActions pour définir les instructions pour la période suivante (modifications planifiées)

Les termes de service étendus introduisent une nouvelle façon de définir des instructions de fin de terme. Le nouvel élément scheduledActions offre aux partenaires un moyen unique de définir les mises à jour du prochain terme, notamment l’annulation, le renouvellement vers des durées de service prolongées ou le renouvellement vers d’autres options de fin de contrat. Les partenaires peuvent définir les instructions scheduledActions RenewToNewTerm au lieu des instructions scheduledNextTermInstructions précédentes. Vous trouverez plus d’informations sur l’utilisation de scheduledActions pour définir les instructions de terme suivantes dans la documentation sur le terme de service étendu.

Les partenaires qui utilisent scheduledActions doivent éviter également de passer scheduledNextTermInstructions lors de la mise à jour des abonnements éligibles pour les conditions de service étendues. Les partenaires peuvent choisir de passer les deux doivent se rendre compte que seules les actions planifiées sont prises en compte. Les partenaires peuvent continuer à passer uniquement scheduledNextTermInstructions pour définir les instructions pour le prochain terme.

Important

Évitez de transmettre des instructions pour la prochaine période à la fois dans les scheduledActions et dans les nextTermInstructions. Utilisez l’un ou l’autre. Si les deux sont fournis, les instructions « scheduledActions » sont utilisées par défaut.

Demander à l’aide d’actions planifiées

{
  "autoRenewEnabled": true,
  "scheduledActions": [
    {
      "scheduledType": "TermEnd",
      "actionType": "RenewToNewTerm",
      "instructions": {
        "product": {
          "productId": "CFQ7TTC0LHXH",
          "skuId": "0001",
          "availabilityId": "CFQ7TTC0LHXH",
          "billingCycle": "annual",
          "termDuration": "P1Y",
          "promotionId": "39NFJQT20KJ2:0001:39NFJQT1Q5KK"
        },
        "quantity": 25,
        "customTermEndDate": "2027-11-31T23:59:59.000Z"
      }
    }
  ]
}

Réponse à l’aide d’actions planifiées

{
  "autoRenewEnabled": true,
  "scheduledNextTermInstructions" : {
     "product": {
        "productId": "CFQ7TTC0LHXH",
        "skuId": "0001",
        "availabilityId": "CFQ7TTC0LHXH",
        "billingCycle": "annual",
        "termDuration": "P1Y",
        "promotionId": "39NFJQT20KJ2:0001:39NFJQT1Q5KK"
      },
      "quantity": 25,
      "customTermEndDate": "2027-11-31T23:59:59.000Z"
  },
  "scheduledActions":   "scheduledActions": [
    {
      "scheduledType": "TermEnd",
      "actionType": "RenewToNewTerm",
      "instructions": {
        "product": {
          "productId": "CFQ7TTC0LHXH",
          "skuId": "0001",
          "availabilityId": "CFQ7TTC0LHXH",
          "billingCycle": "annual",
          "termDuration": "P1Y",
          "promotionId": "39NFJQT20KJ2:0001:39NFJQT1Q5KK"
        },
        "quantity": 25,
        "customTermEndDate": "2027-11-31T23:59:59.000Z"
      }
    }
  ]
}

Demande utilisant des instructions planifiées pour le prochain terme

PATCH https://api.partnercenter.microsoft.com/v1/customers/<customer-tenant-id>/subscriptions/<subscription-id> HTTP/1.1
Authorization: Bearer <token>
Accept: application/json
MS-RequestId: ca7c39f7-1a80-43bc-90d8-ee7d1cad3831
MS-CorrelationId: aaaa0000-bb11-2222-33cc-444444dddddd
If-Match: <etag>
Content-Type: application/json
Content-Length: 1029
Expect: 100-continue
Connection: Keep-Alive

{
    "id": "6e7aa601-629e-461b-8933-0898c3cc3c7c",
    "offerId": "DZH318Z0BXWC:0001:DZH318Z0BMJX",
    "offerName": "offer Name",
    "friendlyName": "friendly Name",
    "quantity": 1,
    "customTermEndDate": "2019-01-09T00:21:45.9263727",
    "unitType": "License(s)",
    "hasPurchasableAddons": false,
    "creationDate": "2019-01-04T01:00:12.6647304Z",
    "effectiveStartDate": "2019-01-09T00:21:45.9263727+00:00",
    "commitmentEndDate": "2019-02-08T00:21:45.9263727+00:00",
    "status": "active",
    "autoRenewEnabled": true,
    "scheduledNextTermInstructions": { 
      "product": { 
         "productId":  "DG7GMGF0DVSV", 
         "skuId":  "000P", 
         "availabilityId":  "DG7GMGF0F3Q9", 
         "billingCycle":  "Annual", 
         "termDuration":  "P3Y",
         "promotionId": "39NFJQT1PFPJ:000H:39NFJQT1Q5DK"
        }, 
      "quantity":  1 
      "customTermEndDate" : "2019-01-09T00:21:45.9263727",
     },  // original value = null 
    "isTrial": false,
    "billingType": "license",
    "billingCycle": "monthly",
    "termDuration": "P1M",
    "refundOptions": [{
        "type": "Full",
        "expiresAt": "2019-01-10T00:21:45.9263727+00:00"
    }],
    "isMicrosoftProduct": false,
    "partnerId": "",
    "contractType": "subscription",
    "publisherName": "publisher Name",
    "orderId": "ImxjLNL4_fOc-2KoyOxGTZcrlIquzls11",
    "attributes": {"objectType": "Subscription"},
}

Réponse REST

Si la demande aboutit, cette méthode retourne les propriétés de ressource Subscription mises à jour dans le corps de la réponse.

Réussite de la réponse et codes d’erreur

Chaque réponse est accompagnée d’un code d’état HTTP qui indique la réussite ou l’échec, ainsi que d’autres informations de débogage. Utilisez un outil de suivi réseau pour lire ce code, le type d’erreur et d’autres paramètres. Pour obtenir la liste complète, consultez Codes d’erreur.

Réponse utilisant les instructions planifiées du prochain terme

HTTP/1.1 200 OK
Content-Length: 1322
Content-Type: application/json; charset=utf-8
MS-RequestId: ca7c39f7-1a80-43bc-90d8-ee7d1cad3831
MS-CorrelationId: aaaa0000-bb11-2222-33cc-444444dddddd
X-Locale: en-US

{
    "id": "6e7aa601-629e-461b-8933-0898c3cc3c7c",
    "offerId": "DZH318Z0BXWC:0001:DZH318Z0BMJX",
    "offerName": "offer Name",
    "friendlyName": "friendly Name",
    "quantity": 1,
    "customTermEndDate": "2019-01-09T00:21:45.9263727",
    "unitType": "License(s)",
    "hasPurchasableAddons": false,
    "creationDate": "2019-01-04T01:00:12.6647304Z",
    "effectiveStartDate": "2019-01-09T00:21:45.9263727+00:00",
    "commitmentEndDate": "2019-02-08T00:21:45.9263727+00:00",
    "status": "active",
    "autoRenewEnabled": true,
    "scheduledNextTermInstructions": { 
      "product": { 
         "productId":  "DG7GMGF0DVSV", 
         "skuId":  "000P", 
         "availabilityId":  "DG7GMGF0F3Q9", 
         "billingCycle":  "Annual", 
         "termDuration":  "P3Y",
         "promotionId": "39NFJQT1PFPJ:000H:39NFJQT1Q5DK"
        }, 
      "quantity":  1 
      "customTermEndDate": "2019-01-09T00:21:45.9263727",
     },  // original value = null 
    "isTrial": false,
    "billingType": "license",
    "billingCycle": "monthly",
    "termDuration": "P1M",
    "refundOptions": [{
        "type": "Full",
        "expiresAt": "2019-01-10T00:21:45.9263727+00:00"
    }],
    "isMicrosoftProduct": false,
    "partnerId": "",
    "contractType": "subscription",
    "publisherName": "publisher Name",
    "orderId": "ImxjLNL4_fOc-2KoyOxGTZcrlIquzls11",
    "attributes": {"objectType": "Subscription"},
}
  • Last updated on