Проведение рекламных кампаний с помощью служб МагазинаRun ad campaigns using Store services

Используйте API Microsoft Storeных рекламных акций , чтобы программно управлять рекламными кампаниями рекламных акций для приложений, зарегистрированных в учетной записи центра партнеров или вашей организации.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. С помощью этого API можно создавать, обновлять и отслеживать ваши кампании и связанные с ними ресурсы, такие как таргетинг и оформление рекламы.This API enables you to create, update and monitor your campaigns and other related assets such as targeting and creatives. Этот API особенно полезен для разработчиков, создающих большие объемы кампаний и желающих сделать это без использования центра партнеров.This API is especially useful for developers who create large volumes of campaigns, and who want to do so without using Partner Center. Для проверки подлинности вызовов из приложения или службы в этом интерфейсе используется служба Azure Active Directory (Azure AD).This API uses Azure Active Directory (Azure AD) to authenticate the calls from your app or service.

Далее описан весь процесс.The following steps describe the end-to-end process:

  1. Убедитесь, что вы выполнили все необходимые условия.Make sure that you have completed all the prerequisites.
  2. Перед вызовом метода API промоакций Microsoft Store, получите маркер доступа Azure AD.Before you call a method in the Microsoft Store promotions API, obtain an Azure AD access token. После получения маркера доступа у вас будет 60 минут, чтобы использовать его в вызовах к API промоакций Microsoft Store до окончания срока действия маркера.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. После истечения срока действия маркера можно сформировать новый маркер.After the token expires, you can generate a new token.
  3. Вызовите API промоакций Microsoft Store.Call the Microsoft Store promotions API.

Вы также можете создавать кампании AD и управлять ими с помощью центра партнеров, а любые кампании, создаваемые программно с помощью API Microsoft Storeных рекламных акций, могут быть доступны в центре партнеров.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. Дополнительные сведения об управлении кампаниями AD в центре партнеров см. в статье Создание рекламной кампании для приложения.For more information about managing ad campaigns in Partner Center, see Create an ad campaign for your app.

Примечание

Любой разработчик с учетной записью центра партнеров может использовать API Microsoft Storeных рекламных акций для управления обработкой рекламных кампаний в своих приложениях.Any developer with a Partner Center account can use the Microsoft Store promotions API to manage ad campaigns for their apps. Рекламные агентства также могут запросить доступ к данному API-интерфейса для проведения кампаний от лица своих клиентов.Media agencies can also request access to this API to run ad campaigns on behalf of their advertisers. Если вы являетесь представителем рекламного агентства, который хочет получить больше информации о данном API-интерфейсе или запросить доступ к нему, то отправьте запрос на 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.

Шаг 1. Выполнение необходимых условий для использования API промоакций Microsoft StoreStep 1: Complete prerequisites for using the Microsoft Store promotions API

Перед тем как начать писать код для вызова API промоакций Microsoft Store, убедитесь, что выполнены следующие необходимые условия.Before you start writing code to call the Microsoft Store promotions API, make sure that you have completed the following prerequisites.

  • Перед тем как вы сможете успешно создать и запустить кампанию AD с помощью этого API, необходимо сначала создать одну платную кампанию AD, используя страницу " кампании AD " в центре партнеров, и на этой странице необходимо добавить хотя бы один платежный инструмент.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. После выполнения этих действий можно создавать платные строки поставки для рекламных кампаний с помощью этого API.After you do this, you will be able to successfully create billable delivery lines for ad campaigns using this API. Строки доставки для кампаний AD, создаваемых с помощью этого API, автоматически выставляют платежное средство по умолчанию, выбранное на странице " кампании по рекламе " в центре партнеров.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.

  • У вас (или вашей организации) должен иметься каталог Azure AD, а также у вас должен быть доступ уровня глобального администратора к этому каталогу.You (or your organization) must have an Azure AD directory and you must have Global administrator permission for the directory. Если вы уже используете Microsoft 365 или другие бизнес-службы Майкрософт, у вас уже есть каталог Azure AD.If you already use Microsoft 365 or other business services from Microsoft, you already have Azure AD directory. В противном случае вы можете создать новую службу Azure AD в центре партнеров без дополнительной платы.Otherwise, you can create a new Azure AD in Partner Center for no additional charge.

  • Необходимо связать приложение Azure AD с учетной записью центра партнеров, получить идентификатор клиента и идентификатор клиента для приложения и создать ключ.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. Приложение Azure AD представляет собой приложение или службу, из которой отправляются вызовы к API промоакций Microsoft Store.The Azure AD application represents the app or service from which you want to call the Microsoft Store promotions API. Для получения маркера доступа Azure AD, передаваемого в API, необходимы идентификатор арендатора, идентификатор и ключ клиента.You need the tenant ID, client ID and key to obtain an Azure AD access token that you pass to the API.

    Примечание

    Эту операцию необходимо выполнить только один раз.You only need to perform this task one time. После получения идентификатора арендатора, идентификатора и ключа клиента их можно повторно использовать в любой момент, когда потребуется создать новый маркер доступа 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.

Чтобы связать приложение Azure AD с учетной записью центра партнеров и получить необходимые значения:To associate an Azure AD application with your Partner Center account and retrieve the required values:

  1. В Центре партнеров свяжите учетную запись Центра партнеров своей организации с каталогом Azure AD организации.In Partner Center, associate your organization's Partner Center account with your organization's Azure AD directory.

  2. Затем на странице Пользователи в разделе " Параметры учетной записи " центра партнеров добавьте приложение Azure AD , которое представляет приложение или службу, которые будут использоваться для управления кампаниями по маркетингу для учетной записи центра партнеров.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. Убедитесь, что этому приложению назначена роль Менеджер.Make sure you assign this application the Manager role. Если приложение еще не существует в каталоге Azure AD, можно создать новое приложение Azure AD в Центре партнеров.If the application doesn't exist yet in your Azure AD directory, you can create a new Azure AD application in Partner Center.

  3. Вернитесь на страницу Пользователи, щелкните имя приложения Azure AD, чтобы перейти к параметрам приложения, и скопируйте идентификатор арендатора и идентификатор клиента.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. Щелкните Добавить новый ключ.Click Add new key. На следующем экране скопируйте значение в поле Ключ.On the following screen, copy down the Key value. Покинув эту страницу, вы больше не сможете получить доступ к этим сведениям.You won't be able to access this info again after you leave this page. Дополнительные сведения см. в разделе Управление ключами для приложения Azure AD.For more information, see Manage keys for an Azure AD application.

Шаг 2. Получение маркера доступа Azure ADStep 2: Obtain an Azure AD access token

Перед тем как можно будет вызвать любой из методов в API промоакций Microsoft Store, сначала необходимо получить маркер доступа Azure AD и передать его в заголовок Авторизация каждого метода в 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. После получения маркера доступа у вас будет 60 минут, чтобы использовать его до истечения срока действия.After you obtain an access token, you have 60 minutes to use it before it expires. После истечения срока действия маркера вы можете обновить его, чтобы дальше использовать в последующих вызовах к API.After the token expires, you can refresh the token so you can continue to use it in further calls to the API.

Для получения маркера доступа следуйте инструкциям в разделе Вызовы между службами с помощью учетных данных клиентов, чтобы отправить HTTP-запрос POST в конечную точку 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. Ниже приведен пример запроса.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

В поле * _ идентификатор* клиента в URI POST и в параметрах * _ секрета* клиента и * _ идентификатора* клиента укажите идентификатор клиента, идентификатор клиента и ключ для приложения, полученные из центра партнеров в предыдущем разделе.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. Для параметра resource укажите значение https://manage.devcenter.microsoft.com.For the resource parameter, you must specify https://manage.devcenter.microsoft.com.

После истечения срока действия маркера доступа вы можете обновить его, следуя инструкциям, приведенным здесь.After your access token expires, you can refresh it by following the instructions here.

Шаг 3. Вызов интерфейса API промоакций Microsoft StoreStep 3: Call the Microsoft Store promotions API

После получения маркера доступа Azure AD вы можете вызвать API-интерфейс промоакций Microsoft Store.After you have an Azure AD access token, you are ready to call the Microsoft Store promotions API. Необходимо передать маркер доступа в заголовок Authorization каждого метода.You must pass the access token to the Authorization header of each method.

В контексте API промоакций Microsoft Store рекламная кампания состоит из объекта кампания, который содержит общие сведения о кампании, и дополнительных объектов, представляющих каналы доставки, целевые профили и элементы рекламной кампании.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. API-интерфейс содержит различные методы, которые сгруппированы по типам объектов.The API includes different sets of methods that are grouped by these object types. Чтобы создать кампанию, обычно следует вызвать отдельный POST-метод для каждого из этих объектов.To create a campaign, you typically call a different POST method for each of these objects. API также предоставляет GET-методы , используемые для получения любого объекта, и методы PUT, которые применяются для изменения объектов кампании, каналов доставки и целевых профилей.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.

Дополнительные сведения об этих объектах и связанных с ними методах см. в следующей таблице.For more information about these objects and their related methods, see the following table.

ОбъектObject ОписаниеDescription
КампанииCampaigns Этот объект представляет рекламную кампанию, и он размещается в верхней части иерархии объектов модели для рекламных кампаний.This object represents the ad campaign, and it sits at the top of the object model hierarchy for ad campaigns. Этот объект определяет тип проводимой кампании (платная, локальная или для сообщества), цель кампании, каналы доставки и другие сведения.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. Каждая кампания может быть связана только с одним приложением.Each campaign can be associated with only one app.

Дополнительные сведения о методах, связанных с данным объектом, см. в разделе Управление рекламными кампаниями.For more information about the methods related to this object, see Manage ad campaigns.

Примечание.     После создания рекламной кампании можно получить данные о производительности для кампании с помощью метода получения данных о производительности кампании "получить AD " в Microsoft Store Analytics API.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.
Каналы доставкиDelivery lines Каждая кампания имеет один или несколько каналов доставки, которые применяются для покупки инвентаря и доставки вашей рекламы.Every campaign has one or more delivery lines that are used to buy inventory and deliver your ads. Для каждого канала доставки можно задать целевую аудиторию, цену заявки, установить бюджет на допустимые траты и связать канал с нужными элементами рекламы.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.

Дополнительные сведения о методах, связанных с этим объектом, см. в разделе управление каналами доставки для рекламных кампаний.For more information about the methods related to this object, see Manage delivery lines for ad campaigns.
Целевые профилиTargeting profiles Каждый канал доставки имеет один целевой профиль, в котором описываются пользователи, регионы и типы инвентаря, которые вас интересуют.Every delivery line has one targeting profile that specifies the users, geographies and inventory types that you want to target. Целевые профили могут создаваться как шаблоны и совместно применяться в разных каналах доставки.Targeting profiles can be created as a template and shared across delivery lines.

Дополнительные сведения о методах, связанных с этим объектом, см. в разделе Управление целевыми профилями для рекламных кампаний.For more information about the methods related to this object, see Manage targeting profiles for ad campaigns.
Рекламные элементыCreatives Каждый канал доставки имеет один или несколько рекламных элементов — это объявления, которые отображаются пользователям в рамках кампании.Every delivery line has one or more creatives that represent the ads that are shown to customers as part of the campaign. Рекламный элемент может быть связан с одним или несколькими каналами доставки (даже в разных рекламных кампаниях) при условии, что элемент всегда представляет одно и тоже приложение.A creative may be associated with one or more delivery lines, even across ad campaigns, provided it always represents the same app.

Дополнительные сведения о методах, связанных с этим объектом, см. в разделе управление рекламными элементами для кампаний.For more information about the methods related to this object, see Manage creatives for ad campaigns.

На следующей схеме показана связь между кампаниями, каналами доставки, целевыми профилями и рекламными элементами.The following diagram illustrates the relationship between campaigns, delivery lines, targeting profiles, and creatives.

Иерархия рекламной кампании

Пример кодаCode example

В следующем примере кода показано, как получить маркер доступа Azure AD и вызвать API промоакций Microsoft Store из консольного приложения 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. Чтобы использовать этот пример кода, назначьте переменным tenantId, clientId, clientSecret и appID соответствующие вашему сценарию значения.To use this code example, assign the tenantId, clientId, clientSecret, and appID variables to the appropriate values for your scenario. Для этого примера требуется пакет Json.NET от Newtonsoft для десериализации JSON-данных, возвращаемых API промоакций 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;
        }
    }
}