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

Используйте API рекламных акций Microsoft Store для программного управления рекламными кампаниями для приложений, зарегистрированных в вашей учетной записи Центра партнеров или вашей организации. С помощью этого API можно создавать, обновлять и отслеживать ваши кампании и связанные с ними ресурсы, такие как таргетинг и оформление рекламы. Этот API особенно полезен для разработчиков, которые создают большие объемы кампаний и хотят сделать это без использования Центра партнеров. Для проверки подлинности вызовов из приложения или службы в этом интерфейсе используется служба Azure Active Directory (Azure AD).

Далее описан весь процесс.

1. Убедитесь, что вы выполнили все необходимые условия.
2. Перед вызовом метода API промоакций Microsoft Store, получите маркер доступа Azure AD. После получения маркера доступа у вас будет 60 минут, чтобы использовать его в вызовах к API промоакций Microsoft Store до окончания срока действия маркера. После истечения срока действия маркера можно сформировать новый маркер.
3. Вызовите API промоакций Microsoft Store.

Вы также можете создавать рекламные кампании и управлять ими с помощью Центра партнеров, а любые рекламные кампании, создаваемые программным способом с помощью API рекламных акций Microsoft Store, также можно получить в Центре партнеров. Дополнительные сведения об управлении рекламными кампаниями в Центре партнеров см. в статье Создание рекламной кампании для приложения.

Примечание

Любой разработчик с учетной записью Центра партнеров может использовать API рекламных акций Microsoft Store для управления рекламными кампаниями для своих приложений. Рекламные агентства также могут запросить доступ к данному API-интерфейса для проведения кампаний от лица своих клиентов. Если вы являетесь представителем рекламного агентства, который хочет получить больше информации о данном API-интерфейсе или запросить доступ к нему, то отправьте запрос на storepromotionsapi@microsoft.com.

Шаг 1. Выполнение необходимых условий для использования API промоакций Microsoft Store

Перед тем как начать писать код для вызова API промоакций Microsoft Store, убедитесь, что выполнены следующие необходимые условия.

• Прежде чем успешно создать и запустить рекламную кампанию с помощью этого API, необходимо сначала создать одну платную рекламную кампанию с помощью страницы Рекламные кампании в Центре партнеров и добавить хотя бы один платежный инструмент на эту страницу. После выполнения этих действий можно создавать платные строки поставки для рекламных кампаний с помощью этого API. Линии доставки для рекламных кампаний, создаваемых с помощью этого API, будут автоматически выставлять счет за средство оплаты по умолчанию, выбранное на странице Рекламные кампании в Центре партнеров.

• У вас (или вашей организации) должен иметься каталог Azure AD, а также у вас должен быть доступ уровня глобального администратора к этому каталогу. Если вы уже используете Microsoft 365 или другие бизнес-службы Microsoft, у вас уже есть каталог Azure AD. В противном случае вы можете создать новую Azure AD в Центре партнеров без дополнительной платы.

• Необходимо связать Azure AD приложение с учетной записью Центра партнеров, получить идентификатор клиента и идентификатор клиента для приложения и создать ключ. Приложение Azure AD представляет собой приложение или службу, из которой отправляются вызовы к API промоакций Microsoft Store. Для получения маркера доступа Azure AD, передаваемого в API, необходимы идентификатор арендатора, идентификатор и ключ клиента.

  Примечание

  Эту операцию необходимо выполнить только один раз. После получения идентификатора арендатора, идентификатора и ключа клиента их можно повторно использовать в любой момент, когда потребуется создать новый маркер доступа Azure AD.

Чтобы связать приложение Azure AD с учетной записью Центра партнеров и получить необходимые значения:

1. В Центре партнеров свяжите учетную запись Центра партнеров своей организации с каталогом Azure AD организации.

2. Затем на странице Пользователи в разделе Параметры учетной записи Центра партнеров добавьте приложение Azure AD, представляющее приложение или службу, которые будут использоваться для управления рекламными кампаниями для вашей учетной записи Центра партнеров. Убедитесь, что этому приложению назначена роль Менеджер. Если приложение еще не существует в каталоге Azure AD, можно создать новое приложение Azure AD в Центре партнеров.

3. Вернитесь на страницу Пользователи, щелкните имя приложения Azure AD, чтобы перейти к параметрам приложения, и скопируйте идентификатор арендатора и идентификатор клиента.

4. Щелкните Добавить новый ключ. На следующем экране скопируйте значение в поле Ключ. Покинув эту страницу, вы больше не сможете получить доступ к этим сведениям. Дополнительные сведения см. в разделе Управление ключами для приложения Azure AD.

Шаг 2. Получение маркера доступа Azure AD

Перед тем как можно будет вызвать любой из методов в API промоакций Microsoft Store, сначала необходимо получить маркер доступа Azure AD и передать его в заголовок Авторизация каждого метода в API. После получения маркера доступа у вас будет 60 минут, чтобы использовать его до истечения срока действия. После истечения срока действия маркера вы можете обновить его, чтобы дальше использовать в последующих вызовах к API.

Для получения маркера доступа следуйте инструкциям в разделе Вызовы между службами с помощью учетных данных клиентов, чтобы отправить HTTP-запрос POST в конечную точку https://login.microsoftonline.com/<tenant_id>/oauth2/token. Ниже приведен пример запроса.

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

Для значения tenant_id в URI POST, а также параметров client_id и client_secret укажите идентификатор клиента, идентификатор клиента и ключ для приложения, полученные из Центра партнеров в предыдущем разделе. Для параметра resource укажите значение https://manage.devcenter.microsoft.com.

После истечения срока действия маркера доступа вы можете обновить его, следуя инструкциям, приведенным здесь.

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

После получения маркера доступа Azure AD вы можете вызвать API-интерфейс промоакций Microsoft Store. Необходимо передать маркер доступа в заголовок Authorization каждого метода.

В контексте API промоакций Microsoft Store рекламная кампания состоит из объекта кампания, который содержит общие сведения о кампании, и дополнительных объектов, представляющих каналы доставки, целевые профили и элементы рекламной кампании. API-интерфейс содержит различные методы, которые сгруппированы по типам объектов. Чтобы создать кампанию, обычно следует вызвать отдельный POST-метод для каждого из этих объектов. API также предоставляет GET-методы , используемые для получения любого объекта, и методы PUT, которые применяются для изменения объектов кампании, каналов доставки и целевых профилей.

Дополнительные сведения об этих объектах и связанных с ними методах см. в следующей таблице.

Объект	Описание
Кампании	Этот объект представляет рекламную кампанию, и он размещается в верхней части иерархии объектов модели для рекламных кампаний. Этот объект определяет тип проводимой кампании (платная, локальная или для сообщества), цель кампании, каналы доставки и другие сведения. Каждая кампания может быть связана только с одним приложением. Дополнительные сведения о методах, связанных с данным объектом, см. в разделе Управление рекламными кампаниями. Примечание После создания рекламной кампании можно получить данные о производительности кампании с помощью метода Получить данные о производительности рекламной кампании в API аналитики Microsoft Store.
Каналы доставки	Каждая кампания имеет один или несколько каналов доставки, которые применяются для покупки инвентаря и доставки вашей рекламы. Для каждого канала доставки можно задать целевую аудиторию, цену заявки, установить бюджет на допустимые траты и связать канал с нужными элементами рекламы. Дополнительные сведения о методах, связанных с этим объектом, см. в разделе управление каналами доставки для рекламных кампаний.
Целевые профили	Каждый канал доставки имеет один целевой профиль, в котором описываются пользователи, регионы и типы инвентаря, которые вас интересуют. Целевые профили могут создаваться как шаблоны и совместно применяться в разных каналах доставки. Дополнительные сведения о методах, связанных с этим объектом, см. в разделе Управление целевыми профилями для рекламных кампаний.
Рекламные элементы	Каждый канал доставки имеет один или несколько рекламных элементов — это объявления, которые отображаются пользователям в рамках кампании. Рекламный элемент может быть связан с одним или несколькими каналами доставки (даже в разных рекламных кампаниях) при условии, что элемент всегда представляет одно и тоже приложение. Дополнительные сведения о методах, связанных с этим объектом, см. в разделе управление рекламными элементами для кампаний.

На следующей схеме показана связь между кампаниями, каналами доставки, целевыми профилями и рекламными элементами.

Пример кода

В следующем примере кода показано, как получить маркер доступа Azure AD и вызвать API промоакций Microsoft Store из консольного приложения C#. Чтобы использовать этот пример кода, назначьте переменным tenantId, clientId, clientSecret и appID соответствующие вашему сценарию значения. Для этого примера требуется пакет Json.NET от Newtonsoft для десериализации JSON-данных, возвращаемых API промоакций Microsoft Store.

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;
        }
    }
}

Связанные темы

• Управление рекламными кампаниями
• Управление каналами доставки для рекламных кампаний
• Управление профилями таргетинга рекламных кампаний
• Управление рекламными элементами для кампаний
• Получение данных об эффективности рекламной кампании