使用应用商店服务运行广告市场活动

2025-06-10

使用 Microsoft Store 促销 API 以编程方式管理注册到你或你组织的合作伙伴中心帐户的应用的促销广告活动。通过此 API，你可以创建、更新和监视市场活动和其他相关资产，例如定位和创意。对于创建大量活动并希望避免使用合作伙伴中心的开发人员，此 API 特别有用。此 API 使用 Azure Active Directory（Azure AD）对来自应用或服务的调用进行身份验证。

以下步骤描述了端到端过程：

请确保已完成所有先决条件。
在 Microsoft 应用商店促销 API 中调用方法之前，请获取 Azure AD 访问令牌。获取令牌后，在令牌过期之前，在调用 Microsoft Store 促销 API 时，需要 60 分钟使用此令牌。令牌过期后，可以生成新令牌。
调用Microsoft应用商店促销 API。

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

注释

任何具有合作伙伴中心帐户的开发人员都可以使用Microsoft应用商店促销 API 管理其应用的广告市场活动。媒体机构还可以请求访问此 API，代表广告商运行广告活动。如果您是一家媒体机构，并希望了解更多有关此 API 的信息或请求访问，请将您的请求发送至 storepromotionsapi@microsoft.com。

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

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

在使用此 API 成功创建和启动广告市场活动之前，必须先在合作伙伴中心使用 广告市场活动 页面创建一个付费广告市场活动，并且必须在此页面上至少添加一个付款方式。执行此操作后，你将能够使用此 API 成功为广告市场活动创建可计费的投放渠道。使用此 API 创建的广告市场活动传递线将自动向合作伙伴中心 广告市场活动 页上选择的默认付款方式计费。
您（或您的组织）必须具有 Azure AD 目录，并且必须对该目录拥有全局管理员权限。如果已从 Microsoft 使用 Microsoft 365 或其他业务服务，则已有 Azure AD 目录。否则，可以在合作伙伴中心创建新的 Azure AD ，无需额外付费。
必须将 Azure AD 应用程序与合作伙伴中心帐户相关联，检索应用程序的租户 ID 和客户端 ID 并生成密钥。 Azure AD 应用程序表示要从中调用 Microsoft 应用商店促销 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 中的任何方法之前，你必须先获取一个 Azure AD 访问令牌，并将其传递到 API 中每个方法的 Authorization 标头。获取访问令牌后，在它到期前，你有 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 和密钥。对于“资源”参数，必须指定 https://manage.devcenter.microsoft.com。

访问令牌过期后，您可以按照此处的说明刷新它。

步骤 3：调用Microsoft应用商店促销 API

获得 Azure AD 访问令牌后，即可调用 Microsoft 应用商店促销 API。必须将访问令牌传递给每个方法的 Authorization 标头。

在 Microsoft Store 促销 API 的上下文中，广告活动包括一个活动对象，该对象包含有关活动的高级信息，以及表示广告活动的 投放线、目标配置文件和创意的其他对象。 API 包括由这些对象类型分组的不同方法集。要创建广告活动，通常需要为每个对象调用不同的 POST 方法。该 API 提供 GET 方法，用于检索任何对象，以及 PUT 方法，用于编辑市场活动、交付线和目标配置文件对象。

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

物体	DESCRIPTION
活动	此对象表示广告市场活动，它位于广告市场活动的对象模型层次结构的顶部。此对象标识您正在运行的营销活动类型（付费、内部或社区）、活动目标、活动的投放线路和其他详细信息。每个市场活动只能与一个应用相关联。有关与此对象相关的方法的详细信息，请参阅 “管理广告市场活动”。注意创建广告活动后，可以使用 Microsoft 应用商店分析 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;
        }
    }
}