Exécuter des campagnes Active Directory à l’aide des services StoreRun ad campaigns using Store services

Utilisez l' API Microsoft Store promotions pour gérer par programme les campagnes publicitaires promotionnelles pour les applications qui sont inscrites auprès de votre compte espace partenaires de votre organisation ou de votre organisation.Use the Microsoft Store promotions API to programmatically manage promotional ad campaigns for apps that are registered to your or your organization's Partner Center account. Cette API vous permet de créer, mettre à jour et surveiller vos campagnes et d’autres ressources associées, telles que le ciblage et les éléments créatifs.This API enables you to create, update and monitor your campaigns and other related assets such as targeting and creatives. Cette API est particulièrement utile pour les développeurs qui créent de grands volumes de campagnes et qui souhaitent le faire sans l’aide de l’espace partenaires.This API is especially useful for developers who create large volumes of campaigns, and who want to do so without using Partner Center. Cette API utilise Azure Active Directory (Azure AD) pour authentifier les appels en provenance de votre application ou service.This API uses Azure Active Directory (Azure AD) to authenticate the calls from your app or service.

Les étapes suivantes décrivent le processus de bout en bout :The following steps describe the end-to-end process:

  1. Vérifiez que vous avez rempli toutes les conditions préalables.Make sure that you have completed all the prerequisites.
  2. Avant d’appeler une méthode dans l’API Microsoft Store promotions, obtenez un jeton d’accès Azure ad.Before you call a method in the Microsoft Store promotions API, obtain an Azure AD access token. Une fois que vous avez obtenu un jeton, vous avez 60 minutes pour utiliser ce jeton dans les appels à l’API Microsoft Store promotions avant l’expiration du jeton.After you obtain a token, you have 60 minutes to use this token in calls to the Microsoft Store promotions API before the token expires. Une fois le jeton arrivé à expiration, vous pouvez en générer un nouveau.After the token expires, you can generate a new token.
  3. Appelez l’API Microsoft Store promotions.Call the Microsoft Store promotions API.

Vous pouvez également créer et gérer des campagnes Active Directory à l’aide de l’espace partenaires. vous pouvez également accéder aux campagnes de publicité que vous créez par programme par le biais de l’API Microsoft Store promotions dans l’espace partenaires.You can alternatively create and manage ad campaigns using Partner Center, and any ad campaigns that you create programmatically via the Microsoft Store promotions API can also be accessed in Partner Center. Pour plus d’informations sur la gestion des campagnes Active Directory dans l’espace partenaires, consultez créer une campagne publicitaire pour votre application.For more information about managing ad campaigns in Partner Center, see Create an ad campaign for your app.

Notes

Tout développeur disposant d’un compte espace partenaires peut utiliser l’API Microsoft Store promotions pour gérer les campagnes Active Directory pour ses applications.Any developer with a Partner Center account can use the Microsoft Store promotions API to manage ad campaigns for their apps. Les agences multimédias peuvent également demander l’accès à cette API pour exécuter des campagnes AD pour le compte de leurs annonceurs.Media agencies can also request access to this API to run ad campaigns on behalf of their advertisers. Si vous êtes une Agence multimédia qui souhaite en savoir plus sur cette API ou en demander l’accès, envoyez votre demande à storepromotionsapi@microsoft.com .If you are a media agency who wants to know more about this API or request access to it, send your request to storepromotionsapi@microsoft.com.

Étape 1 : remplir les conditions préalables à l’utilisation de l’API Microsoft Store promotionsStep 1: Complete prerequisites for using the Microsoft Store promotions API

Avant de commencer à écrire du code pour appeler l’API de promotions Microsoft Store, assurez-vous que vous avez rempli les conditions préalables suivantes.Before you start writing code to call the Microsoft Store promotions API, make sure that you have completed the following prerequisites.

  • Avant de pouvoir créer et démarrer correctement une campagne publicitaire à l’aide de cette API, vous devez d’abord créer une campagne publicitaire payante à l’aide de la page campagnes publicitaires dans l’espace partenaires. vous devez ajouter au moins un instrument de paiement sur cette page.Before you can successfully create and start an ad campaign using this API, you must first create one paid ad campaign using the Ad campaigns page in Partner Center, and you must add at least one payment instrument on this page. Après cela, vous serez en mesure de créer avec succès des lignes de livraison facturables pour les campagnes Active Directory à l’aide de cette API.After you do this, you will be able to successfully create billable delivery lines for ad campaigns using this API. Les lignes de livraison des campagnes de publicité que vous créez à l’aide de cette API facturent automatiquement l’instrument de paiement par défaut choisi dans la page campagnes publicitaires de l’espace partenaires.Delivery lines for ad campaigns you create using this API will automatically bill the default payment instrument chosen on the Ad campaigns page in Partner Center.

  • Vous (ou votre organisation) devez disposer d’un annuaire Azure AD et de l’autorisation Administrateur général sur l’annuaire.You (or your organization) must have an Azure AD directory and you must have Global administrator permission for the directory. Si vous utilisez déjà Microsoft 365 ou d’autres services professionnels de Microsoft, vous disposez déjà d’un annuaire Azure AD.If you already use Microsoft 365 or other business services from Microsoft, you already have Azure AD directory. Dans le cas contraire, vous pouvez créer un nouveau Azure ad dans l’espace partenaires sans frais supplémentaires.Otherwise, you can create a new Azure AD in Partner Center for no additional charge.

  • Vous devez associer une application Azure AD à votre compte espace partenaires, récupérer l’ID de locataire et l’ID client pour l’application et générer une clé.You must associate an Azure AD application with your Partner Center account, retrieve the tenant ID and client ID for the application and generate a key. L’application Azure AD représente l’application ou le service à partir duquel vous souhaitez appeler l’API Microsoft Store promotions.The Azure AD application represents the app or service from which you want to call the Microsoft Store promotions API. Il vous faut l’ID tenant, l’ID client et la clé pour obtenir un jeton d’accès Azure AD à transmettre à l’API.You need the tenant ID, client ID and key to obtain an Azure AD access token that you pass to the API.

    Notes

    Vous ne devez effectuer cette tâche qu’une seule fois.You only need to perform this task one time. Une fois que vous les avez, vous pouvez réutiliser l’ID tenant, l’ID client et la clé chaque fois que vous devez créer un jeton d’accès Azure AD.After you have the tenant ID, client ID and key, you can reuse them any time you need to create a new Azure AD access token.

Pour associer une application Azure AD à votre compte espace partenaires et récupérer les valeurs requises :To associate an Azure AD application with your Partner Center account and retrieve the required values:

  1. Dans l’Espace partenaires, associez le compte Espace partenaires de votre organisation à l’annuaire Azure AD de votre organisation.In Partner Center, associate your organization's Partner Center account with your organization's Azure AD directory.

  2. Ensuite, dans la page utilisateurs de la section paramètres du compte de l’espace partenaires, Ajoutez l’application Azure ad qui représente l’application ou le service que vous allez utiliser pour gérer les campagnes de promotion de votre compte espace partenaires.Next, from the Users page in the Account settings section of Partner Center, add the Azure AD application that represents the app or service that you will use to manage promotion campaigns for your Partner Center account. Veillez à attribuer à cette application le rôle Gestionnaire.Make sure you assign this application the Manager role. Si l’application n’existe pas encore dans votre annuaire Azure AD, vous pouvez créer une application Azure AD dans l’Espace partenaires.If the application doesn't exist yet in your Azure AD directory, you can create a new Azure AD application in Partner Center.

  3. Revenez à la page Utilisateurs, cliquez sur le nom de votre application Azure AD pour accéder à ses paramètres, puis copiez les valeurs ID tenant et ID client.Return to the Users page, click the name of your Azure AD application to go to the application settings, and copy down the Tenant ID and Client ID values.

  4. Cliquez sur Ajouter une nouvelle clé.Click Add new key. Sur l’écran suivant, copiez la valeur Clé.On the following screen, copy down the Key value. Vous ne pourrez plus accéder à cette information une fois que vous aurez quitté cette page.You won't be able to access this info again after you leave this page. Pour plus d’informations, voir Gérer les clés pour une application Azure AD.For more information, see Manage keys for an Azure AD application.

Étape 2 : Obtenir un jeton d’accès Azure ADStep 2: Obtain an Azure AD access token

Avant d’appeler l’une des méthodes de l’API Microsoft Store promotions, vous devez d’abord obtenir un jeton d’accès Azure AD que vous transmettez à l’en-tête authorization de chaque méthode de l’API.Before you call any of the methods in the Microsoft Store promotions API, you must first obtain an Azure AD access token that you pass to the Authorization header of each method in the API. Une fois que vous avez récupéré le jeton d’accès, vous avez 60 minutes pour l’utiliser avant qu’il n’expire.After you obtain an access token, you have 60 minutes to use it before it expires. Une fois le jeton arrivé à expiration, vous pouvez l’actualiser pour pouvoir continuer à l’utiliser dans d’autres appels à l’API.After the token expires, you can refresh the token so you can continue to use it in further calls to the API.

Pour obtenir le jeton d’accès, suivez les instructions présentées dans l’article 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.To obtain the access token, follow the instructions in Service to Service Calls Using Client Credentials to send an HTTP POST to the https://login.microsoftonline.com/<tenant_id>/oauth2/token endpoint. Voici un exemple de requête.Here is a sample request.

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://manage.devcenter.microsoft.com

Pour la valeur _ ID de locataire dans l’URI de publication et les paramètres * _ ID client* et clé * _ secrète client* , spécifiez l’ID de locataire, l’ID client et la clé de votre application que vous avez récupéré dans l’espace partenaires dans la section précédente.For the tenant_id value in the POST URI and the client_id and client_secret parameters, specify the tenant ID, client ID and the key for your application that you retrieved from Partner Center in the previous section. Pour le paramètre resource, vous devez spécifier https://manage.devcenter.microsoft.com.For the resource parameter, you must specify https://manage.devcenter.microsoft.com.

Une fois votre jeton d’accès arrivé à expiration, vous pouvez l’actualiser en suivant les instructions fournies ici.After your access token expires, you can refresh it by following the instructions here.

Étape 3 : appeler l’API Microsoft Store promotionsStep 3: Call the Microsoft Store promotions API

Une fois que vous disposez d’un jeton d’accès Azure AD, vous êtes prêt à appeler l’API Microsoft Store promotions.After you have an Azure AD access token, you are ready to call the Microsoft Store promotions API. Vous devez transmettre le jeton d’accès à l’en-tête Authorization de chaque méthode.You must pass the access token to the Authorization header of each method.

Dans le contexte de l’API de promotion Microsoft Store, une campagne publicitaire se compose d’un objet campagne qui contient des informations de haut niveau sur la campagne, et d’objets supplémentaires qui représentent les lignes de livraison, les profils de ciblageet les éléments créatifs pour la campagne publicitaire.In the context of the Microsoft Store promotions API, an ad campaign consists of a campaign object that contains high-level information about the campaign, and additional objects that represent the delivery lines, targeting profiles, and creatives for the ad campaign. L’API comprend différents jeux de méthodes qui sont regroupés en fonction de ces types d’objets.The API includes different sets of methods that are grouped by these object types. Pour créer une campagne, vous appelez généralement une méthode de publication différente pour chacun de ces objets.To create a campaign, you typically call a different POST method for each of these objects. L’API fournit également des méthodes d’extraction que vous pouvez utiliser pour récupérer des objets et des méthodes PUT que vous pouvez utiliser pour modifier les objets de la campagne, de la ligne de livraison et du ciblage.The API also provides GET methods you can use to retrieve any object and PUT methods you can use to edit campaign, delivery line, and targeting profile objects.

Pour plus d’informations sur ces objets et leurs méthodes associées, consultez le tableau suivant.For more information about these objects and their related methods, see the following table.

ObjectObject DescriptionDescription
CampagnesCampaigns Cet objet représente la campagne Active Directory et se trouve en haut de la hiérarchie du modèle objet pour les campagnes Active Directory.This object represents the ad campaign, and it sits at the top of the object model hierarchy for ad campaigns. Cet objet identifie le type de campagne que vous exécutez (payant, maison ou communauté), l’objectif de campagne, les lignes de livraison pour la campagne et d’autres détails.This object identifies the type of campaign you are running (paid, house, or community), the campaign objective, the delivery lines for the campaign, and other details. Chaque campagne peut être associée à une seule application.Each campaign can be associated with only one app.

Pour plus d’informations sur les méthodes associées à cet objet, consultez gérer des campagnes ad.For more information about the methods related to this object, see Manage ad campaigns.

Note   Remarque   Après avoir créé une campagne publicitaire, vous pouvez récupérer les données de performances de la campagne à l’aide de la méthode obtenir les données de performance de la campagne Active Directory dans l' API Microsoft Store Analytics.Note  After you create an ad campaign, you can retrieve performance data for the campaign by using the Get ad campaign performance data method in the Microsoft Store analytics API.
Lignes de livraisonDelivery lines Chaque campagne possède une ou plusieurs lignes de livraison qui sont utilisées pour acheter un inventaire et livrer vos annonces.Every campaign has one or more delivery lines that are used to buy inventory and deliver your ads. Pour chaque ligne de livraison, vous pouvez définir le ciblage, définir le prix de votre offre et déterminer le montant que vous souhaitez dépenser en définissant un budget et en établissant un lien vers les éléments créatifs que vous souhaitez utiliser.For each delivery line, you can set targeting, set your bid price, and decide how much you want to spend by setting a budget and linking to creatives you want to use.

Pour plus d’informations sur les méthodes associées à cet objet, consultez gérer les lignes de livraison pour les campagnes de publicité.For more information about the methods related to this object, see Manage delivery lines for ad campaigns.
Ciblage des profilsTargeting profiles Chaque ligne de livraison a un profil de ciblage qui spécifie les utilisateurs, les zones géographiques et les types d’inventaire que vous souhaitez cibler.Every delivery line has one targeting profile that specifies the users, geographies and inventory types that you want to target. Les profils de ciblage peuvent être créés en tant que modèle et partagés entre les lignes de livraison.Targeting profiles can be created as a template and shared across delivery lines.

Pour plus d’informations sur les méthodes associées à cet objet, consultez gérer les profils de ciblage pour les campagnes Active Directory.For more information about the methods related to this object, see Manage targeting profiles for ad campaigns.
Éléments créatifsCreatives Chaque ligne de livraison comporte une ou plusieurs éléments créatifs qui représentent les publicités présentées aux clients dans le cadre de la campagne.Every delivery line has one or more creatives that represent the ads that are shown to customers as part of the campaign. Un élément créatif peut être associé à une ou plusieurs lignes de livraison, même dans des campagnes ad, à condition qu’il représente toujours la même application.A creative may be associated with one or more delivery lines, even across ad campaigns, provided it always represents the same app.

Pour plus d’informations sur les méthodes associées à cet objet, consultez gérer les éléments créatifs pour les campagnes ad.For more information about the methods related to this object, see Manage creatives for ad campaigns.

Le diagramme suivant illustre la relation entre les campagnes, les lignes de livraison, les profils de ciblage et les éléments créatifs.The following diagram illustrates the relationship between campaigns, delivery lines, targeting profiles, and creatives.

Hiérarchie des campagnes Active Directory

Exemple de codeCode example

L’exemple de code suivant montre comment obtenir un jeton d’accès Azure AD et appeler l’API Microsoft Store promotions à partir d’une application console C#.The following code example demonstrates how to obtain an Azure AD access token and call the Microsoft Store promotions API from a C# console app. Pour utiliser cet exemple de code, affectez les variables tenantId, clientId, clientSecret, et appID aux valeurs appropriées pour votre scénario.To use this code example, assign the tenantId, clientId, clientSecret, and appID variables to the appropriate values for your scenario. Cet exemple nécessite que le package JSON.net de Newtonsoft désérialise les données JSON retournées par l’API de promotions Microsoft Store.This example requires the Json.NET package from Newtonsoft to deserialize the JSON data returned by the Microsoft Store promotions API.

using Newtonsoft.Json;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;

namespace TestPromotionsAPI
{
    class Program
    {
        static void Main(string[] args)
        {
            string tenantId = "<your tenant ID>";
            string clientId = "<your client ID>";
            string clientSecret = "<your secret>";

            string scope = "https://manage.devcenter.microsoft.com";

            // Retrieve an Azure AD access token
            string accessToken = GetClientCredentialAccessToken(
                    tenantId,
                    clientId,
                    clientSecret,
                    scope).Result;

            int pageSize = 100;
            int startPageIndex = 0;

            // This is your app's Store ID. This ID is available on
            // the App identity page of the Dev Center dashboard.
            string appID = "<your app's Store ID>";


            // Call the Windows Store promotions API
            CallPromotionsAPI(accessToken, appID, pageSize, startPageIndex);

            Console.Read();
        }

        private static void CallPromotionsAPI(string accessToken, string appID, int fetch, int skip)
        {
            string requestURI;

            // Get ad campaigns.
            requestURI = string.Format(
                "https://manage.devcenter.microsoft.com/v1.0/my/promotion/campaign?applicationId={0}&fetch={1}&skip={2}&campaignSetSortColumn=createdDateTime",
                appID, fetch, skip);

            HttpRequestMessage requestMessage = new HttpRequestMessage(HttpMethod.Get, requestURI);
            requestMessage.Headers.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);

            WebRequestHandler handler = new WebRequestHandler();
            HttpClient httpClient = new HttpClient(handler);

            HttpResponseMessage response = httpClient.SendAsync(requestMessage).Result;

            Console.WriteLine(response);
            Console.WriteLine(response.Content.ReadAsStringAsync().Result);

            response.Dispose();
        }

        public static async Task<string> GetClientCredentialAccessToken(string tenantId, string clientId, string clientSecret, string scope)
        {
            string tokenEndpointFormat = "https://login.microsoftonline.com/{0}/oauth2/token";
            string tokenEndpoint = string.Format(tokenEndpointFormat, tenantId);

            dynamic result;
            using (HttpClient client = new HttpClient())
            {
                string tokenUrl = tokenEndpoint;
                using (
                    HttpRequestMessage request = new HttpRequestMessage(
                        HttpMethod.Post,
                        tokenUrl))
                {
                    string content =
                        string.Format(
                            "grant_type=client_credentials&client_id={0}&client_secret={1}&resource={2}",
                            clientId,
                            clientSecret,
                            scope);

                    request.Content = new StringContent(content, Encoding.UTF8, "application/x-www-form-urlencoded");

                    using (HttpResponseMessage response = await client.SendAsync(request))
                    {
                        string responseContent = await response.Content.ReadAsStringAsync();
                        result = JsonConvert.DeserializeObject(responseContent);
                    }
                }
            }

            return result.access_token;
        }
    }
}