Vue d’ensemble de l’API de soumission d’offres privées

Article
07/26/2023

Les offres privées permettent aux éditeurs et aux clients de réaliser des transactions sur un ou plusieurs produits sur la Place de marché Azure en créant des prix limités dans le temps avec des conditions personnalisées. Les API de soumission d’offres privées permettent aux éditeurs de créer et de gérer par programmation des offres privées pour les clients et/ou les partenaires CSP. Cette API utilise l’ID Microsoft Entra pour authentifier les appels à partir de votre application ou service.

Il existe trois types principaux d’offres privées disponibles dans l’Espace partenaires et pris en charge par l’API de soumission d’offre privée :

Éditeur de logiciels indépendants vers une offre privée client : également appelée offre privée client dans l’Espace partenaires. Il s’agit d’une transaction personnalisée entre un éditeur de logiciels indépendants et un client spécifique avec des conditions et des tarifs personnalisés pour un produit spécifique dans Place de marché Azure. En savoir plus sur l’offre privée des éditeurs de logiciels indépendants pour le client.
Offre privée fournisseur de logiciels indépendants vers fournisseur de solutions Cloud – Également appelée offre privée partenaires CSP dans l’Espace partenaires. Ce type d’offre privée permet à ISV de spécifier une marge limitée dans le temps pour créer un prix de gros pour son partenaire CSP. En savoir plus sur l’offre privée du partenaire ISV vers csp.
Offre privée multipartie (MPO) : offre personnalisée configurée conjointement par un éditeur de logiciels indépendants et un partenaire de vente préféré d’un client spécifique avec des conditions et des tarifs personnalisés pour des produits spécifiques dans Place de marché Azure. L’ISV définit le prix de gros réduit mis à la disposition du partenaire, le partenaire vendeur peut ensuite ajouter du balisage au-dessus du prix de gros pour arriver au prix final du client et présenter l’offre au client pour l’acceptation et l’achat. L’acceptation et l’achat du MPO suivent le même flux que les offres privées des éditeurs de logiciels indépendants. En savoir plus sur l’offre privée multipartie.

Terminologie

Originator MPO : MPO est une collaboration entre l’ISV et le partenaire vendeur sur la même transaction personnalisée pour un client spécifique, la partie qui crée d’abord le MPO est désignée « originator » de l’offre, généralement l’ISV des produits inclus dans le MPO. Il ne peut y avoir qu’un seul originateur pour n’importe quel MPO donné.
Vendeur MPO – Le partenaire vendeur qui prépare l’offre avec le prix final du client et présente l’offre au client est le vendeur du MPO. Il ne peut y avoir qu’un seul vendeur pour n’importe quel MPO donné.
Produit : unité unique représentant une offre dans la Place de marché Azure. Il existe un produit par page d’offre.
Plan : version unique d’un produit particulier. Il peut y avoir plusieurs plans pour un produit donné qui représentent différents niveaux de tarification ou conditions.
Travail : tâche créée lors de la création d’une requête dans cette API. Lorsque vous utilisez cette API pour gérer des offres privées et des offres privées multipartes, un travail est créé pour effectuer la requête. Une fois le travail terminé, vous pouvez obtenir plus d’informations sur l’offre privée pertinente (multipartie).

Scénarios pris en charge

Préparer l’utilisation de cette API

Avant d’écrire du code pour appeler l’API d’offres privées, vérifiez que vous avez rempli les conditions suivantes. Les mêmes conditions préalables s’appliquent à tous les partenaires de publication.

Étape 1 : Répondre aux conditions pour l’utilisation de l’API d’ingestion de produits Microsoft (une seule fois)

Vous ou votre organisation devez disposer d’une autorisation d’annuaire Microsoft Entra et d’administrateur général. Si vous utilisez déjà Microsoft 365 ou d’autres services professionnels de Microsoft, vous disposez déjà d’un annuaire Microsoft Entra. Si ce n’est pas le cas, vous pouvez créer gratuitement un ID Microsoft Entra dans l’Espace partenaires.

Vous devez associer une application Microsoft Entra ID à votre compte Espace partenaires et obtenir votre ID de locataire, votre ID client et votre clé. Vous avez besoin de ces valeurs pour obtenir le jeton d’accès Microsoft Entra que vous utiliserez dans les appels à l’API des offres privées.

Étape 2 : Obtenir un jeton d’accès Microsoft Entra (à chaque fois)

Avant d’appeler l’une des méthodes de l’API de soumission du Microsoft Store, vous avez besoin d’un jeton d’accès Microsoft Entra pour passer à l’en-tête d’autorisation de chaque méthode de l’API. Vous avez 60 minutes pour utiliser un jeton avant son expiration. Après expiration, vous pouvez actualiser un jeton afin de pouvoir continuer à l’utiliser lors de nouveaux appels à l’API.

Pour obtenir le jeton d’accès, consultez Appels de service à service à l’aide des informations d’identification du client pour envoyer une requête HTTP POST au point de terminaison https://login.microsoftonline.com/<tenant_id>/oauth2/token. Voici un exemple de requête :

POST https://login.microsoftonline.com/<tenant_id>/oauth2/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded; charset=utf-8
grant_type=client_credentials
&client_id=<your_client_id>
&client_secret=<your_client_secret>
&resource=https://graph.microsoft.com/

Pour la valeur tenant_id dans l’URI POST ainsi que pour les paramètres client_id et client_secret, spécifiez l’ID de locataire, l’ID client et la clé de l’application, que vous avez récupérés à partir de l’Espace partenaires au cours de la section précédente. Pour le paramètre de ressource, vous devez spécifier https://graph.microsoft.com/.

Rechercher des ID de produit, de plan et d’offre privée

Identifiant	Où les trouver
client_id	Consultez Associer une application Microsoft Entra à votre compte Espace partenaires.
tenant_id	Consultez Associer une application Microsoft Entra à votre compte Espace partenaires.
client_secret	Consultez Associer une application Microsoft Entra à votre compte Espace partenaires.
productId	Consultez Récupérer des produits dans cet article.
planId	Consultez Récupérer des plans pour un produit spécifique dans cet article.
privateofferId	Consultez Récupérer des offres privées dans cet article.

Récupérer des produits

Une offre privée est basée sur un produit existant dans votre compte Espace partenaires. Pour afficher la liste des produits associés à votre compte Espace partenaires, utilisez cet appel d’API :

GET https://graph.microsoft.com/rp/product-ingestion/product?$version=2022-07-01

La réponse apparaît dans l’exemple de format suivant :

{
  "value": [
    {
      "$schema": "https://schema.mp.microsoft.com/schema/product/2022-07-01",
      "id": "string",
      "identity": {
        "externalId": "string"
      },
      "type": "enum",
      "alias": "string"
    }
  ],
  "@nextLink": "opaque_uri"
}

Récupérer des plans pour un produit spécifique

Pour les produits qui contiennent plusieurs plans, vous pouvez créer une offre privée basée sur un plan spécifique. Si c’est le cas, vous avez besoin de l’ID de ce plan. Obtenez la liste des plans (comme des variantes ou des références SKU) pour le produit à l’aide de l’appel d’API suivant :

GET https://graph.microsoft.com/rp/product-ingestion/plan?product=<product-id>&$version=2022-07-01

La réponse apparaît dans l’exemple de format suivant :

{
  "value": [
    {
      "$schema": "https://schema.mp.microsoft.com/schema/plan/2022-07-01",
      "product": "string",
      "id": "string",
      "identity": {
        "externalId": "string"
      },
      "alias": "string"
    }
  ]
}

Récupérer des offres privées

Pour afficher la liste de toutes les offres privées, y compris les offres privées multipartes, associées à votre compte, utilisez l’appel d’API suivant :

GET https://graph.microsoft.com/rp/product-ingestion/private-offer/query?$version=2023-07-15

Comment utiliser l’API

L’API d’offre privée vous permet de créer et de gérer des offres privées associées aux produits et plans au sein de votre compte Espace partenaires. Voici un résumé du modèle d’appel classique lors de l’utilisation de cette API.

Étape 1 : Effectuer la requête

Lorsque vous effectuez un appel d’API pour créer, supprimer, retirer ou mettre à niveau une offre privée, un nouveau travail est créé pour terminer la tâche demandée. La réponse de l’API contient un jobId associé au travail.

Étape 2 : Interroger l’état du travail

À l’aide de jobId à partir de la réponse d’API initiale, interrogez pour obtenir l’état du travail. L’état du travail est en cours d’exécution ou terminé. Une fois le travail terminé, le résultat est Réussi ou Échec. Pour éviter les problèmes de performances, n’interrogez pas un travail plus d’une fois par minute.

jobStatus	Description
NotStarted	Le travail n’a pas encore démarré ; il s’agit d’une partie de la réponse sur la requête initiale.
En cours d’exécution	Le travail est toujours en cours d’exécution.
Terminée	Le travail a été terminé. Pour plus d’informations, consultez jobResult .
jobResult	Description
Pending	Le travail n’est pas encore terminé.
Réussi	Le travail a été effectué avec succès. Ce travail retourne également une ressourceURI qui fait référence à l’offre privée liée au travail. Utilisez ce ressourceURI pour obtenir les détails complets d’une offre privée.
Échec	Le travail a échoué. Cela retourne également toutes les erreurs pertinentes pour vous aider à déterminer la cause de l’échec.

Pour plus d’informations, consultez Interroger l’état d’un travail existant.

Étape 3 : Obtenir des informations à partir de travaux terminés

Un travail réussi retourne un resourceUri référençant l’offre privée appropriée. Utilisez cet URI de ressource pour obtenir plus de détails sur l’offre privée à l’avenir, comme privateofferId.

Un travail ayant échoué contient des erreurs qui fournissent des détails sur la raison pour laquelle le travail a échoué et comment résoudre le problème.

Pour plus d’informations, consultez Obtenir les détails d’une offre privée existante.

Comment les éditeurs de logiciels indépendants et les partenaires vendeurs doivent utiliser l’API pour une offre privée multipartie

Les éditeurs de logiciels indépendants et le partenaire vendeur peuvent utiliser les mêmes API pour la création et la gestion d’un MPO donné. Toutefois, les ressources d’un MPO qui peuvent affecter l’API dépendent si l’appelant de l’API est l’ÉDITEUR de logiciels indépendants (originateur) ou le partenaire vendeur (vendeur) du MPO. Le même flux de publication de partenaire/vendeur et les mêmes règles d’entreprise régissant l’Espace partenaires sont miroir dans l’API. Voici une vue d’ensemble :

Opération d’API	ISV (Originator)	Partenaire vendeur (vendeur)
Créer	L’audience prévue est le partenaire vendeur(vendeur) lorsque l’appel d’API est publié, le client final ne verra pas l’offre privée tant que le partenaire vendeur n’a pas soumis Ressources modifiables : Dates d'entrée en vigueur Bénéficiaire prévu (client) Vente d’un partenaire pour collaborer sur l’offre, limitée à 1 par offre privée Contacts ISV supplémentaires à avertir de l’état de l’offre privée Conditions générales personnalisées des éditeurs de logiciels indépendants Produits/plans inclus dans l’offre privée Durée(s) du contrat pour chaque produit/plan Quantités incluses pour chaque produit (le cas échéant) Attributs de plan sans spécification (le cas échéant) Prix de gros réduit disponible pour le partenaire vendeur sur les produits/plans inclus Notes de vente isv	L’audience prévue est le client final lorsque l’appel d’API est publié Ressources modifiables : Conditions générales personnalisées du partenaire de vente Préparé par Ajustement du client (pourcentage de balisage) au-dessus du prix de gros isv pour chaque produit/plan inclus dans l’offre privée, cela détermine le prix final du client final Contacts partenaires de vente supplémentaires à avertir de l’état de l’offre privée Vente de notes de vente de partenaires
Supprimer	Pris en charge pour les offres privées en état brouillon	Non pris en charge
Abandonner	Pris en charge pour les offres privées publiées par l’ÉDITEUR de logiciels indépendants mais pas encore publiés par le partenaire vendeur ou s’ils sont retirés par le partenaire vendeur	Pris en charge pour les offres privées publiées et disponibles pour les clients finaux, mais pas encore acceptées

Opération d’API

ISV (Originator)

Partenaire vendeur (vendeur)

Créer

L’audience prévue est le partenaire vendeur(vendeur) lorsque l’appel d’API est publié, le client final ne verra pas l’offre privée tant que le partenaire vendeur n’a pas soumis

Ressources modifiables :

Dates d'entrée en vigueur
Bénéficiaire prévu (client)
Vente d’un partenaire pour collaborer sur l’offre, limitée à 1 par offre privée
Contacts ISV supplémentaires à avertir de l’état de l’offre privée
Conditions générales personnalisées des éditeurs de logiciels indépendants
Produits/plans inclus dans l’offre privée
Durée(s) du contrat pour chaque produit/plan
Quantités incluses pour chaque produit (le cas échéant)
Attributs de plan sans spécification (le cas échéant)
Prix de gros réduit disponible pour le partenaire vendeur sur les produits/plans inclus
Notes de vente isv

L’audience prévue est le client final lorsque l’appel d’API est publié