Запуск рекламных кампаний с помощью служб Store

Используйте API рекламных акций Microsoft Store для программной разработки рекламных кампаний для приложений, зарегистрированных в вашей учетной записи или учетной записи вашей организации в Центре партнеров. Этот API позволяет создавать, обновлять и отслеживать кампании и другие связанные ресурсы, такие как целевые и творческие решения. Этот 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 или другие бизнес-службы от Майкрософт, у вас уже есть каталог 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, который передается в заголовок Authorization каждого метода в API. После получения маркера доступа у вас есть 60 минут, чтобы использовать его до истечения срока действия. После истечения срока действия маркера можно обновить маркер, чтобы продолжить использовать его в дальнейших вызовах API.

Чтобы получить маркер доступа, следуйте инструкциям в статье Service to Service Calls Using Client Credentials для отправки 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 укажите идентификатор клиента, идентификатор арендатора и ключ приложения, полученные из Центра партнеров в предыдущем разделе. Для параметра ресурса необходимо указать https://manage.devcenter.microsoft.com.

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

Шаг 3. Вызов API рекламных акций Microsoft Store

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

В контексте 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;
        }
    }
}

Связанные разделы

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