使用Microsoft Store 服務執行廣告行銷活動Run ad campaigns using Store services

使用Microsoft Store 促銷 API ,以程式設計方式管理已向或您組織的合作夥伴中心帳戶註冊之應用程式的促銷廣告活動。Use the Microsoft Store promotions API to programmatically manage promotional ad campaigns for apps that are registered to your or your organization's Partner Center account. 這個 API 可讓您用來建立、更新及監視您的行銷活動,以及其他相關資產,例如目標和廣告素材。This API enables you to create, update and monitor your campaigns and other related assets such as targeting and creatives. 此 API 特別適用于建立大量活動的開發人員,以及想要在不使用合作夥伴中心的情況下執行此動作的使用者。This API is especially useful for developers who create large volumes of campaigns, and who want to do so without using Partner Center. 這個 API 使用 Azure Active Directory (Azure AD) 來驗證您應用程式或服務的呼叫。This API uses Azure Active Directory (Azure AD) to authenticate the calls from your app or service.

下列步驟說明端對端的程序:The following steps describe the end-to-end process:

  1. 請確定您已經完成所有先決條件Make sure that you have completed all the prerequisites.
  2. 在呼叫 Microsoft Store 促銷 API 中的方法之前,請先取得 Azure AD 存取權杖Before you call a method in the Microsoft Store promotions API, obtain an Azure AD access token. 取得權杖之後,在權杖到期之前,您有 60 分鐘的時間可以使用這個權杖呼叫 Microsoft Store 促銷 API。After you obtain a token, you have 60 minutes to use this token in calls to the Microsoft Store promotions API before the token expires. 權杖到期之後,您可以產生新的權杖。After the token expires, you can generate a new token.
  3. 呼叫 Microsoft Store 促銷 APICall the Microsoft Store promotions API.

您也可以使用合作夥伴中心來建立和管理廣告行銷活動,而且您透過 Microsoft Store 促銷 API 以程式設計方式建立的任何廣告活動也可以在合作夥伴中心存取。You can alternatively create and manage ad campaigns using Partner Center, and any ad campaigns that you create programmatically via the Microsoft Store promotions API can also be accessed in Partner Center. 如需在合作夥伴中心管理廣告行銷活動的詳細資訊,請參閱為您的應用程式建立廣告行銷活動For more information about managing ad campaigns in Partner Center, see Create an ad campaign for your app.

注意

任何具有合作夥伴中心帳戶的開發人員都可以使用 Microsoft Store 促銷 API 來管理其應用程式的廣告活動。Any developer with a Partner Center account can use the Microsoft Store promotions API to manage ad campaigns for their apps. 媒體代理商也可要求存取這個 API,代表廣告客戶執行廣告行銷活動。Media agencies can also request access to this API to run ad campaigns on behalf of their advertisers. 如果您是想要深入了解或要求存取這個 API 的媒體代理商,請將您的要求傳送至 storepromotionsapi@microsoft.com。If you are a media agency who wants to know more about this API or request access to it, send your request to storepromotionsapi@microsoft.com.

步驟 1︰完成使用 Microsoft Store 促銷 API 的先決條件Step 1: Complete prerequisites for using the Microsoft Store promotions API

開始撰寫程式碼以呼叫 Microsoft Store 促銷 API 之前,請先確定您已完成下列先決條件。Before you start writing code to call the Microsoft Store promotions API, make sure that you have completed the following prerequisites.

  • 您必須先使用合作夥伴中心的 [廣告活動] 頁面建立一個付費廣告行銷活動,而且您必須在此頁面上至少新增一個付款條件,才能順利建立及開始使用此 API 的 ad 活動。Before you can successfully create and start an ad campaign using this API, you must first create one paid ad campaign using the Ad campaigns page in Partner Center, and you must add at least one payment instrument on this page. 執行此動作之後,您就可以使用此 API 成功地建立廣告行銷活動的可計費廣告播送行。After you do this, you will be able to successfully create billable delivery lines for ad campaigns using this API. 您使用此 API 所建立之 ad 活動的傳遞程式碼,會自動以合作夥伴中心的 [廣告活動] 頁面上選擇的預設付款條件為帳單。Delivery lines for ad campaigns you create using this API will automatically bill the default payment instrument chosen on the Ad campaigns page in Partner Center.

  • 您 (或您的組織) 必須擁有 Azure AD 目錄,而且您必須具備目錄的全域系統管理員權限。You (or your organization) must have an Azure AD directory and you must have Global administrator permission for the directory. 如果您已經使用 Office 365 或其他 Microsoft 所提供的商務服務,您就已經擁有 Azure AD 目錄。If you already use Office 365 or other business services from Microsoft, you already have Azure AD directory. 否則,您可以在合作夥伴中心建立新的 Azure AD ,而不需要額外付費。Otherwise, you can create a new Azure AD in Partner Center for no additional charge.

  • 您必須將 Azure AD 應用程式與您的合作夥伴中心帳戶建立關聯、抓取應用程式的租使用者識別碼和用戶端識別碼,並產生金鑰。You must associate an Azure AD application with your Partner Center account, retrieve the tenant ID and client ID for the application and generate a key. Azure AD 應用程式代表您要呼叫 Microsoft Store 促銷 API 的 App 或服務。The Azure AD application represents the app or service from which you want to call the Microsoft Store promotions API. 您需要租用戶識別碼、用戶端識別碼和金鑰,才能取得傳遞給 API 的 Azure AD 存取權杖。You need the tenant ID, client ID and key to obtain an Azure AD access token that you pass to the API.

    注意

    您只需要執行此工作一次。You only need to perform this task one time. 有了租用戶識別碼、用戶端識別碼和金鑰,每當您必須建立新的 Azure AD 存取權杖時,就可以重複使用它們。After you have the tenant ID, client ID and key, you can reuse them any time you need to create a new Azure AD access token.

若要將 Azure AD 應用程式與您的合作夥伴中心帳戶產生關聯,並抓取所需的值:To associate an Azure AD application with your Partner Center account and retrieve the required values:

  1. 在合作夥伴中心,將組織的合作夥伴中心帳戶與組織的 Azure AD 目錄建立關聯In Partner Center, associate your organization's Partner Center account with your organization's Azure AD directory.

  2. 接下來,從合作夥伴中心的 [帳戶設定] 區段中的 [使用者] 頁面,新增代表您將用來管理合作夥伴中心帳戶促銷活動之應用程式或服務的Azure AD 應用程式Next, from the Users page in the Account settings section of Partner Center, add the Azure AD application that represents the app or service that you will use to manage promotion campaigns for your Partner Center account. 請確定您指派此應用程式 [管理員] 角色。Make sure you assign this application the Manager role. 如果您的 Azure AD 目錄中尚未存在該應用程式,您可以在合作夥伴中心建立新的 Azure AD 應用程式If the application doesn't exist yet in your Azure AD directory, you can create a new Azure AD application in Partner Center.

  3. 返回 [使用者] 頁面,按一下您 Azure AD 應用程式的名稱來移至應用程式設定,然後複製 [租用戶識別碼][用戶端識別碼] 的值。Return to the Users page, click the name of your Azure AD application to go to the application settings, and copy down the Tenant ID and Client ID values.

  4. 按一下 [加入新的金鑰]Click Add new key. 在下列畫面中,複製 [金鑰] 的值。On the following screen, copy down the Key value. 您離開這個頁面之後就無法再存取此資訊。You won't be able to access this info again after you leave this page. 如需詳細資訊,請參閱管理 Azure AD 應用程式的金鑰For more information, see Manage keys for an Azure AD application.

步驟 2:取得 Azure AD 存取權杖Step 2: Obtain an Azure AD access token

在 Microsoft Store 促銷 API 中呼叫任何方法之前,您必須先取得傳遞至 API 中每個方法的 Authorization 標頭的 Azure AD 存取權杖。Before you call any of the methods in the Microsoft Store promotions API, you must first obtain an Azure AD access token that you pass to the Authorization header of each method in the API. 在您取得存取權杖之後,您在權杖到期之前有 60 分鐘的時間可以使用權杖。After you obtain an access token, you have 60 minutes to use it before it expires. 權杖到期之後,您可以重新整理權杖以便在後續呼叫 API 時繼續使用。After the token expires, you can refresh the token so you can continue to use it in further calls to the API.

若要取得存取權杖,請按照使用用戶端認證的服務對服務呼叫中的指示,將 HTTP POST 傳送至 https://login.microsoftonline.com/<tenant_id>/oauth2/token 端點。To obtain the access token, follow the instructions in Service to Service Calls Using Client Credentials to send an HTTP POST to the https://login.microsoftonline.com/<tenant_id>/oauth2/token endpoint. 以下是範例要求。Here is a sample request.

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] 和 [用戶端_識別碼] 和 [用戶端 _密碼] 參數中的租使用者_識別碼值,指定您在上一節中從合作夥伴中心抓取之應用程式的租使用者識別碼、用戶端識別碼和金鑰。For the tenant_id value in the POST URI and the client_id and client_secret parameters, specify the tenant ID, client ID and the key for your application that you retrieved from Partner Center in the previous section. 對於 resource 參數,您必須指定 https://manage.devcenter.microsoft.comFor the resource parameter, you must specify https://manage.devcenter.microsoft.com.

存取權杖到期之後,您可以按照這裡的指示,重新整理權杖。After your access token expires, you can refresh it by following the instructions here.

步驟 3:呼叫 Microsoft Store 促銷 APIStep 3: Call the Microsoft Store promotions API

有了 Azure AD 存取權杖之後,就可以呼叫 Microsoft Store 促銷 API。After you have an Azure AD access token, you are ready to call the Microsoft Store promotions API. 您必須將存取權杖傳送給每個方法的 Authorization 標頭。You must pass the access token to the Authorization header of each method.

在 Microsoft Store 中促銷 API 的內容中,廣告行銷活動包含 「行銷活動」 物件 (其中包含行銷活動的高階資訊),以及其他物件 (代表廣告行銷活動的 「廣告播送行」「目標設定檔」「廣告素材」 )。In the context of the Microsoft Store promotions API, an ad campaign consists of a campaign object that contains high-level information about the campaign, and additional objects that represent the delivery lines, targeting profiles, and creatives for the ad campaign. API 包括不同組的方法,依物件類型分組。The API includes different sets of methods that are grouped by these object types. 若要建立行銷活動,您通常針對每個物件呼叫不同 POST 方法。To create a campaign, you typically call a different POST method for each of these objects. API 也提供 GET 方法,可用來擷取任何物件,以及 PUT 方法,可以使用它來編輯行銷活動、廣告播送行及目標設定檔物件。The API also provides GET methods you can use to retrieve any object and PUT methods you can use to edit campaign, delivery line, and targeting profile objects.

如需有關這些物件與其相關方法的詳細資訊,請參閱下表。For more information about these objects and their related methods, see the following table.

物件Object 描述Description
行銷活動Campaigns 這個物件表示廣告行銷活動,它位於廣告行銷活動的物件模型階層頂端。This object represents the ad campaign, and it sits at the top of the object model hierarchy for ad campaigns. 這個物件辨識您正在執行之行銷活動的類型 (付費、內部或社群)、行銷活動目標、行銷活動的廣告播送行,以及其他詳細資料。This object identifies the type of campaign you are running (paid, house, or community), the campaign objective, the delivery lines for the campaign, and other details. 每個行銷活動只能與一個 app 相關聯。Each campaign can be associated with only one app.

如需有關這個物件的相關方法的詳細資訊,請參閱管理廣告行銷活動For more information about the methods related to this object, see Manage ad campaigns.

注意  建立廣告行銷活動之後,您可以使用 Microsoft Store 分析 API 中的取得廣告行銷活動績效資料方法,擷取行銷活動的績效資料。Note  After you create an ad campaign, you can retrieve performance data for the campaign by using the Get ad campaign performance data method in the Microsoft Store analytics API.
廣告播送行Delivery lines 每個行銷活動有一或多個廣告播送行用於購買庫存廣告,並播送您的廣告。Every campaign has one or more delivery lines that are used to buy inventory and deliver your ads. 對於每個廣告播送行,您可以設為目標,設定買方出價,以及設定預算和要使用之廣告素材的連結,決定要花多少費用。For each delivery line, you can set targeting, set your bid price, and decide how much you want to spend by setting a budget and linking to creatives you want to use.

如需有關這個物件的相關方法的詳細資訊,請參閱管理廣告行銷活動的廣告播送行For more information about the methods related to this object, see Manage delivery lines for ad campaigns.
鎖定設定檔Targeting profiles 每個廣告播送行有一個目標設定檔,指定您想要鎖定的使用者、地區和庫存廣告類型。Every delivery line has one targeting profile that specifies the users, geographies and inventory types that you want to target. 目標設定檔可以建立做為範本,並跨廣告播送行共用。Targeting profiles can be created as a template and shared across delivery lines.

如需有關這個物件的相關方法的詳細資訊,請參閱管理廣告行銷活動的目標設定檔For more information about the methods related to this object, see Manage targeting profiles for ad campaigns.
廣告素材Creatives 每個廣告播送行有一或多個廣告素材,代表行銷活動中對客戶顯示的廣告。Every delivery line has one or more creatives that represent the ads that are shown to customers as part of the campaign. 廣告素材可能會與一個或多個廣告播送行相關聯,甚至跨廣告行銷活動,但前提是它永遠代表相同 app。A creative may be associated with one or more delivery lines, even across ad campaigns, provided it always represents the same app.

如需有關這個物件的相關方法的詳細資訊,請參閱管理廣告行銷活動的廣告素材For more information about the methods related to this object, see Manage creatives for ad campaigns.

下圖顯示行銷活動、廣告播送行、目標設定檔及廣告素材之間的關係。The following diagram illustrates the relationship between campaigns, delivery lines, targeting profiles, and creatives.

廣告行銷活動階層

程式碼範例Code example

下列程式碼範例示範如何取得 Azure AD 存取權杖,並從 C# 主控台應用程式呼叫 Microsoft Store 促銷 API。The following code example demonstrates how to obtain an Azure AD access token and call the Microsoft Store promotions API from a C# console app. 若要使用此程式碼範例,請針對您的案例將 tenantIdclientIdclientSecretappID 變數指定為適當的值。To use this code example, assign the tenantId, clientId, clientSecret, and appID variables to the appropriate values for your scenario. 此範例需要 Newtonsoft 的 Json.NET 套件,以還原序列化 Microsoft Store 促銷 API 傳回的 JSON 資料。This example requires the Json.NET package from Newtonsoft to deserialize the JSON data returned by the Microsoft Store promotions API.

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