Запуск рекламных кампаний с помощью служб Store
Используйте API рекламных акций Microsoft Store для программного управления рекламными кампаниями для приложений, зарегистрированных в вашей или учетной записи Центра партнеров вашей организации. Этот API позволяет создавать, обновлять и отслеживать кампании и другие связанные ресурсы, такие как целевые и творческие решения. Этот API особенно полезен для разработчиков, создающих большие объемы кампаний, и которые хотят сделать это без использования Центра партнеров. Этот API использует Azure Active Directory (Azure AD) для проверки подлинности вызовов из приложения или службы.
Следующие шаги описывают сквозной процесс.
- Убедитесь, что вы выполнили все предварительные требования.
- Перед вызовом метода в API продвижения в Microsoft Store получите маркер доступа Azure AD. После получения маркера у вас есть 60 минут для использования этого маркера в вызовах API рекламных акций Microsoft Store до истечения срока действия маркера. После истечения срока действия маркера можно создать новый маркер.
- ВызовИТЕ 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 с учетной записью Центра партнеров и получить необходимые значения:
В Центре партнеров свяжите учетную запись Центра партнеров своей организации с каталогом Azure AD организации.
Затем на странице "Пользователи" в разделе параметров учетной записи Центра партнеров добавьте приложение Azure AD, представляющее приложение или службу, которую вы будете использовать для управления рекламными кампаниями для учетной записи Центра партнеров. Убедитесь, что этому приложению назначена роль Менеджер. Если приложение еще не существует в каталоге Azure AD, можно создать новое приложение Azure AD в Центре партнеров.
Вернитесь на страницу Пользователи, щелкните имя приложения Azure AD, чтобы перейти к параметрам приложения, и скопируйте идентификатор арендатора и идентификатор клиента.
Щелкните Добавить новый ключ. На следующем экране скопируйте значение в поле Ключ. Покинув эту страницу, вы больше не сможете получить доступ к этим сведениям. Дополнительные сведения см. в разделе Управление ключами для приложения 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. Необходимо передать маркер доступа в заголовок авторизации каждого метода.
В контексте API рекламных акций Microsoft Store рекламная кампания состоит из объекта кампании, содержащего высокоуровневую информацию о кампании, а также дополнительные объекты, представляющие линии доставки, целевые профили и творческие решения для рекламной кампании. API включает различные наборы методов, сгруппированных по этим типам объектов. Для создания кампании обычно вызывается другой метод POST для каждого из этих объектов. API также предоставляет методы GET, которые можно использовать для получения любых объектов и методов PUT, которые можно использовать для изменения кампании, линии доставки и назначения объектов профиля.
Дополнительные сведения об этих объектах и их связанных методах см. в следующей таблице.
| Объект | Description |
|---|---|
| Кампании | Этот объект представляет рекламную кампанию и находится в верхней части иерархии объектной модели для рекламных кампаний. Этот объект определяет тип запущенной кампании (платный, дом или сообщество), цель кампании, линии доставки для кампании и другие сведения. Каждая кампания может быть связана только с одним приложением. Дополнительные сведения о методах, связанных с этим объектом, см. в разделе "Управление рекламными кампаниями". Примечание. После создания рекламной кампании можно получить данные о производительности для кампании с помощью метода получения данных о производительности рекламной кампании в API аналитики Microsoft Store. |
| Линии доставки | Каждая кампания имеет одну или несколько линий доставки, которые используются для покупки запасов и доставки рекламы. Для каждой линии доставки вы можете задать целевую цену, задать цену на ставку и решить, сколько вы хотите потратить, задав бюджет и связываясь с творческими объектами, которые вы хотите использовать. Дополнительные сведения о методах, связанных с этим объектом, см. в разделе "Управление линиями доставки для рекламных кампаний". |
| Целевые профили | Каждая линия доставки имеет один профиль целевого объекта, указывающий пользователей, географии и типы инвентаризации, которые вы хотите использовать. Целевые профили можно создавать как шаблон и совместно использовать между линиями доставки. Дополнительные сведения о методах, связанных с этим объектом, см. в разделе "Управление профилями целевого назначения для рекламных кампаний". |
| Творческие возможности | Каждая линия доставки имеет один или несколько творческих объектов, представляющих рекламу, которая отображается клиентам в рамках кампании. Творческий объект может быть связан с одной или несколькими линиями доставки, даже в рекламных кампаниях, если он всегда представляет одно и то же приложение. Дополнительные сведения о методах, связанных с этим объектом, см. в разделе "Управление творческими средствами для рекламных кампаний". |
На следующей схеме показана связь между кампаниями, линиями доставки, профилями целевого назначения и творческими решениями.
Пример кода
В следующем примере кода показано, как получить маркер доступа Azure AD и вызвать API рекламных акций Microsoft Store из консольного приложения C#. Чтобы использовать этот пример кода, назначьте идентификатор клиента, 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;
}
}
}
См. также
- Управление рекламными кампаниями
- Управление линиями доставки для рекламных кампаний
- Управление профилями целевого назначения для рекламных кампаний
- Управление творческими предложениями для рекламных кампаний
- Получение данных о производительности рекламной кампании