使用 Microsoft Store 服务开展广告活动

项目
04/06/2023

使用 Microsoft Store 促销 API，针对已注册到你的或组织的合作伙伴中心帐户的应用以编程方式管理促销广告活动。Microsoft Store 你可借助此 API 创建、更新和监控你的活动和其他相关资产，如目标市场设定和创意。该 API 尤其适用于创建了大量活动的开发人员，及希望不借助合作伙伴中心创建活动的开发人员。此 API 使用 Azure Active Directory (Azure AD) 验证来自应用或服务的调用。

以下步骤介绍端到端过程：

确保已完成所有先决条件。
在 Microsoft Store 促销 API 中调用某个方法之前，请先获取 Azure AD 访问令牌。获取访问令牌后，可以在 60 分钟的令牌有效期内，使用该令牌调用 Microsoft Store 促销 API。该令牌到期后，可以重新生成一个。
调用 Microsoft Store 促销 API。

或者，你可以使用合作伙伴中心创建和管理广告活动，也可以在合作伙伴中心中访问通过 Microsoft Store 促销 API 以编程方式创建的任何广告活动。有关在合作伙伴中心中管理广告活动的详细信息，请参阅为你的应用创建广告活动。

注意

任何拥有合作伙伴中心帐户的开发人员均可使用 Microsoft Store 促销 API 管理其应用的广告活动。媒体机构还可以请求访问该 API 代表他们的广告商开展广告活动。如果你是希望了解该 API 详情或请求其访问权限的媒体机构，请将请求发送至 storepromotionsapi@microsoft.com。

步骤 1：完成使用 Microsoft Store 促销 API 的先决条件

在开始编写调用 Microsoft Store 促销 API 的代码之前，确保已完成以下先决条件。

使用此 API 成功创建和启动广告活动之前，你必须先在合作伙伴中心中使用广告市场活动页面创建一个付费广告活动，并且必须在此页面上添加至少一种付款方式。完成以上操作之后，你就能够使用此 API 为广告活动成功创建计费投放渠道。使用此 API 创建的广告活动的投放渠道将按照在合作伙伴中心中的广告市场活动页面中选择的默认付款方式自动进行计费。
你（或你的组织）必须有一个 Azure AD 目录，并且必须对该目录拥有全局管理员权限。如果你已使用 Microsoft 365 或 Microsoft 的其他业务服务，表示你已经具有 Azure AD 目录。否则，你可以免费在合作伙伴中心中创建新的 Azure AD。
你必须将 Azure AD 应用程序与你的合作伙伴中心帐户相关联、检索应用程序的租户 ID 和客户端 ID 并生成密钥。 Azure AD 应用程序是指要从中调用 Microsoft Store 促销 API 的应用或服务。需要使用该租户 ID、客户端 ID 和密钥来获取要传递给 API 的 Azure AD 访问令牌。

注意

你只需执行一次此任务。获取租户 ID、客户端 ID 和密钥后，每当需要创建新的 Azure AD 访问令牌时，都可以重复使用它们。

若要将 Azure AD 应用程序与你的合作伙伴中心帐户相关联并检索所需值：

在合作伙伴中心，将组织的合作伙伴中心帐户与组织的 Azure AD 目录相关联。
然后，从合作伙伴中心的“帐户设置”部分的“用户”页面添加 Azure AD 应用程序，这里的应用程序表示应用或服务并且将用于管理你的合作伙伴中心帐户的促销活动。确保为此应用程序分配“管理者”角色。如果你的 Azure AD 目录中尚不包含该应用程序，可以在合作伙伴中心创建新的 Azure AD 应用程序。
返回到“用户”页，单击 Azure AD 应用程序的名称转到“应用程序设置”，然后复制“租户 ID”和“客户端 ID”值。
单击“添加新密钥”。在下一个屏幕上，复制“密钥”值。离开此页后，不再可以访问此信息。有关详细信息，请参阅管理 Azure AD 应用程序的密钥。

步骤 2：获取 Azure AD 访问令牌

在 Microsoft Store 促销 API 中调用任何方法之前，首先必须获取将传递给该 API 中每个方法的 Authorization 标头的 Azure AD 访问令牌。获取访问令牌后，你有 60 分钟的时间来使用它，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

对于 POST URI 中的 tenant_id 值以及 client_id 和 client_secret 参数，请指定在上一部分中从合作伙伴中心中为应用程序检索的租户 ID、客户端 ID 和密钥。对于 resource 参数，必须指定 https://manage.devcenter.microsoft.com。

在你的访问令牌到期后，你可按照此处的说明刷新令牌。

步骤 3：调用 Microsoft Store 促销 API

获取 Azure AD 访问令牌后，可以随时调用 Microsoft Store 促销 API。你必须将访问令牌传递到每个方法的 Authorization 标头。

在 Microsoft Store 促销 API 的上下文中，广告活动涵盖了包含活动相关高级信息的活动对象，以及代表广告活动投放渠道、目标市场配置文件 和创意的其他对象。 API 包括按所述对象类型分组的不同方法。通常需要针对每一对象调用不同 POST 方法，从而创建活动。该 API 还提供了可用于检索任何对象的 GET 方法，以及可用于编辑活动、投放渠道和目标市场配置文件对象的 PUT 方法。

有关这些对象及其相关方法的详细信息，请参阅下表。

对象	说明
营销活动	此对象代表广告活动，位于广告活动对象模型层次结构的顶部。此对象标识了你目前开展的活动类型（付费广告、自家广告或社区广告）、活动目标、活动的投放渠道及其他详细信息。每项活动可能仅与一个应用相关联。有关此对象相关方法的详细信息，请参阅管理广告活动。注意：创建广告活动后，可以通过使用 Microsoft Store 分析 API 中的获取广告活动性能数据方法检索广告活动的性能数据。
投放渠道	每项广告活动具有一个或多个投放渠道，用于购买存货和投放广告。你可以针对每个投放渠道设定目标市场、标价，并通过设定预算及与你希望启用的创意连接来判断你的预期费用。有关此对象相关方法的详细信息，请参阅管理广告活动的投放渠道。
目标市场定位配置文件	每个投放渠道都有一份目标市场定位配置文件，指明了你设定的用户、地区和库存类型目标。可创建目标市场配置文件作为模板，并在各投放渠道之间共享。有关此对象相关方法的详细信息，请参阅管理广告活动的目标市场配置文件。
创意	每个投放渠道都有一个或多个创意，作为广告活动的一部分向客户展示广告。如果某一创意始终代表同一应用，则其可能与一个投放渠道或各广告活动间的多个投放渠道相关。有关此对象相关方法的详细信息，请参阅管理广告活动的创意。

下图说明了活动、投放渠道、目标市场配置文件和创意之间的关系。

广告活动层次结构

代码示例

以下代码示例演示如何获取 Azure AD 访问令牌以及如何从 C# 控制台应用调用 Microsoft Store 促销 API。若要使用此代码示例，请将 tenantId、clientId、clientSecret 和 appID 变量分配给你的方案的相应值。此示例需要 Newtonsoft 中的 Json.NET 程序包，以便反序列化 Microsoft Store 促销 API 返回的 JSON 数据。

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

通过

使用 Microsoft Store 服务开展广告活动

步骤 1：完成使用 Microsoft Store 促销 API 的先决条件

步骤 2：获取 Azure AD 访问令牌

步骤 3：调用 Microsoft Store 促销 API

代码示例

反馈

其他资源

通过

使用 Microsoft Store 服务开展广告活动

步骤 1：完成使用 Microsoft Store 促销 API 的先决条件

步骤 2：获取 Azure AD 访问令牌

步骤 3：调用 Microsoft Store 促销 API

代码示例

相关主题

反馈

其他资源