使用 Store 服務執行廣告行銷活動

發行項
04/01/2024

使用 Microsoft Store 促銷 API，以程式設計方式管理註冊至您或貴組織合作夥伴中心帳戶的應用程式促銷廣告行銷活動。此 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 或要求存取此 API 的媒體公司，請將您的要求傳送至 storepromotionsapi@microsoft.com。

步驟 1：完成使用 Microsoft Store 促銷 API 的必要條件

開始撰寫程式碼以呼叫 Microsoft Store 促銷 API 之前，請確定您已完成下列必要條件。

您必須先使用合作夥伴中心的 [廣告行銷活動] 頁面建立一個付費廣告行銷活動，而且您必須在此頁面上新增至少一個付款方式，才能成功建立並開始廣告行銷活動。完成此動作之後，您將能夠使用此 API 成功為廣告行銷活動建立可計費的廣告播送行。您使用此 API 建立的廣告行銷活動廣告播送行，會自動向合作夥伴中心的 [廣告行銷活動] 頁面上選擇的預設付款方式計費。
您 (或貴組織) 必須擁有 Azure AD 目錄，而且您必須具有該目錄的全域管理員權限。如果您已經使用 Microsoft 365 或 Microsoft 的其他商務服務，則您已有 Azure AD 目錄。否則，您可以在合作夥伴中心建立新的 Azure AD，無需額外付費。
您必須將 Azure AD 應用程式與您的合作夥伴中心帳戶建立關聯、擷取應用程式的租用戶識別碼和用戶端識別碼，並產生金鑰。 Azure AD 應用程式代表您想要從中呼叫 Microsoft Store 促銷 API 的應用程式或服務。您需要租用戶識別碼、用戶端識別碼和金鑰，才能取得傳遞至 API 的 Azure AD 存取權杖。

注意

您只需要執行此工作一次。擁有租用戶識別碼、用戶端識別碼和金鑰之後，您可以隨時重複使用，以建立新的 Azure AD 存取權限。

若要將 Azure AD 應用程式與您的合作夥伴中心帳戶建立關聯，並擷取所需的值：

在合作夥伴中心中，將組織的合作夥伴中心帳戶與組織的 Azure AD 目錄建立關聯。
接下來，從合作夥伴中心的帳戶設定區段中的 [使用者] 頁面，新增 Azure AD 應用程式，代表您要用來管理合作夥伴中心帳戶促銷行銷活動的應用程式或服務。請確定為此應用程式指派管理員角色。如果應用程式尚不存在於 Azure AD 目錄中，您可以在合作夥伴中心建立新的 Azure AD 應用程式。
返回 [使用者] 頁面，按一下 Azure AD 應用程式的名稱以移至應用程式設定，然後複製 [租用戶識別碼] 和 [用戶端識別碼] 值。
按一下 [新增金鑰]。在後續的畫面上，複製 [金鑰] 值。離開此頁面之後，您將無法再次存取此資訊。如需詳細資訊，請參閱管理 Azure AD 應用程式的金鑰。

步驟 2：取得 Azure AD 存取權杖

在呼叫 Microsoft Store 促銷 API 中的任何方法之前，您必須先為傳遞至 API 中每個方法的授權標題取得 Azure AD 存取權杖。取得存取權杖之後，您在其到期之前有 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 參數，請在上一節中指定您從合作夥伴中心擷取的應用程式租用戶識別碼、用戶端識別碼和金鑰。針對 resource 參數，您必須指定 https://manage.devcenter.microsoft.com。

您的存取權杖過期後，您可以按照此處的指示重新整理。

步驟 3：呼叫 Microsoft Store 促銷 API

擁有 Azure AD 存取權杖之後，您就可以呼叫 Microsoft Store 促銷 API。您必須將存取權杖傳遞至每個方法的授權標題。

在 Microsoft Store 促銷 API 的內容中，廣告行銷活動的組成是由包含包含行銷活動高階資訊的行銷活動物件，以及代表廣告行銷活動的廣告播送行、受眾設定檔和創意內容。 API 包含由這些物件類型分組的不同方法集合。若要建立行銷活動，您通常會針對每個物件呼叫不同的 POST 方法。 API 也提供 GET 方法，可用來擷取任何物件，以及可用來編輯行銷活動、廣告播送行和受眾設定檔物件的 PUT 方法。

如需這些物件及其相關方法的詳細資訊，請參閱下列資料表。

Object	描述
廣告活動	此物件代表廣告行銷活動，且位於廣告行銷活動的物件模型階層頂端。此物件會識別您正在執行的行銷活動類型 (付費、房屋或社群)、行銷活動目標、行銷活動的廣告播送行，以及其他詳細資料。每個行銷活動只能與一個應用程式相關聯。如需有關此物件的方法詳細資訊，請參閱管理廣告行銷活動。注意：建立廣告行銷活動之後，您可以使用 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;
        }
    }
}

共用方式為

使用 Store 服務執行廣告行銷活動

步驟 1：完成使用 Microsoft Store 促銷 API 的必要條件

步驟 2：取得 Azure AD 存取權杖

步驟 3：呼叫 Microsoft Store 促銷 API

程式碼範例

意見反應

其他資源

共用方式為

使用 Store 服務執行廣告行銷活動

步驟 1：完成使用 Microsoft Store 促銷 API 的必要條件

步驟 2：取得 Azure AD 存取權杖

步驟 3：呼叫 Microsoft Store 促銷 API

程式碼範例

相關主題

意見反應

其他資源