ストア サービスを使用した広告キャンペーンの実行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. トークンを取得した後、Microsoft Store プロモーション API の呼び出しでこのトークンを使用できるのは、その有効期限が切れるまでの 60 分間です。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 プロモーション API を呼び出しますCall the Microsoft Store promotions API.

また、パートナーセンターを使用して ad キャンペーンを作成して管理することもできます。また、Microsoft Store 昇格 API を使用してプログラムで作成した ad キャンペーンは、パートナーセンターでもアクセスできます。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. パートナーセンターで ad キャンペーンを管理する方法の詳細については、「 アプリの ad キャンペーンを作成する」を参照してください。For more information about managing ad campaigns in Partner Center, see Create an ad campaign for your app.

注意

パートナーセンターアカウントを持つ開発者は、Microsoft Store 昇格 API を使用して、アプリの ad キャンペーンを管理できます。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 について詳しい情報を希望される場合、またはこの 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 キャンペーンを正常に作成して開始するには、まず、 パートナーセンターの [ ad キャンペーン ] ページを使用して1つの有料広告キャンペーンを作成し、このページで少なくとも1つの支払い方法を追加する必要があります。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. Microsoft 365 または Microsoft の他のビジネス サービスをすでに使用している場合、Azure AD ディレクトリをすでに所有しています。If you already use Microsoft 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 アプリケーションをパートナーセンターアカウントに関連付けて、アプリケーションのテナント ID とクライアント ID を取得し、キーを生成する必要があります。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 の呼び出し元のアプリまたはサービスを表します。The Azure AD application represents the app or service from which you want to call the Microsoft Store promotions API. API に渡す Azure AD アクセス トークンを取得するには、テナント ID、クライアント ID、キーが必要です。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. テナント ID、クライアント ID、キーがあれば、新しい 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 アプリケーションの名前をクリックしてアプリケーション設定に移動し、テナント IDクライアント ID の値を書き留めます。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] と [クライアント _ id ] と [クライアント _ シークレット] の [テナント _ id ] の値について、前のセクションでパートナーセンターから取得したアプリケーションのテナント id、クライアント id、キーを指定します。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.com を指定します。For 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 プロモーション API を呼び出すStep 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.

ObjectObject 説明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. 1 つのキャンペーンに関連づけることができるのは、1 つのアプリのみです。Each campaign can be associated with only one app.

このオブジェクトについて詳しくは、「広告キャンペーンの管理」をご覧ください。For more information about the methods related to this object, see Manage ad campaigns.

Note   メモ  Ad キャンペーンを作成した後、 Microsoft Store ANALYTICS APIの [ ad キャンペーンのパフォーマンスデータを取得] メソッドを使用して、キャンペーンのパフォーマンスデータを取得できます。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 キャンペーンごとに、インベントリの購入と広告の配信に使用する配信ラインが 1 つ以上あります。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 配信ラインごとに、1 つのターゲット プロファイルを用意します。ターゲット プロファイルでは、対象にするユーザー、地域、およびインベントリの種類を指定します。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 配信ラインごとに、キャンペーンの一環でお客様に表示される広告を表すクリエイティブが 1 つ以上あります。Every delivery line has one or more creatives that represent the ads that are shown to customers as part of the campaign. クリエイティブは、常に同じアプリを表す場合は、同一の広告キャンペーンでなくても、1 つ以上の配信ラインに関連付けることができます。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. このコード例を使う場合は、変数 tenantIdclientIdclientSecret、および appID を自分のシナリオに合った適切な値に割り当ててください。To use this code example, assign the tenantId, clientId, clientSecret, and appID variables to the appropriate values for your scenario. この例では、Microsoft Store プロモーション API から返される JSON データを逆シリアル化するときに、Newtonsoft の Json.NET パッケージが必要になります。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;
        }
    }
}