ストアサービスを使用した広告キャンペーンの実行

[アーティクル]
04/06/2023

"Microsoft Store プロモーション API" を使用すると、自分または自分の組織のパートナーセンターアカウントに登録されているアプリのプロモーション用の広告キャンペーンをプログラムで管理できます。この API を使用して、広告キャンペーンや、ターゲット設定、クリエイティブなど、その他の関連アセットを作成、更新、および監視できます。この API は、大量のキャンペーンを作成する開発者や、パートナーセンターを使用せずにキャンペーンを作成する必要がある開発者に特に便利です。この API は、Azure Active Directory (Azure AD) を使って、アプリまたはサービスからの呼び出しを認証します。

次の手順で、このプロセスについて詳しく説明しています。

すべての前提条件を完了したことを確認します。
Microsoft Store プロモーション API のメソッドを呼び出す前に、Azure AD アクセストークンを取得する必要があります。トークンを取得した後、Microsoft Store プロモーション API の呼び出しでこのトークンを使用できるのは、その有効期限が切れるまでの 60 分間です。トークンの有効期限が切れた後は、新しいトークンを生成できます。
Microsoft Store プロモーション API を呼び出します。

または、パートナーセンターを使用して広告キャンペーンの作成と管理を行うこともできます。Microsoft Store プロモーション API を使ってプログラムで作成した広告キャンペーンはすべて、パートナーセンターからもアクセスできます。パートナーセンターでの広告キャンペーンの管理の詳細については、アプリ向けの広告キャンペーンの作成に関するページを参照してください。

注意

パートナーセンターアカウントをお持ちの開発者の方はどなたでも、Microsoft Store プロモーション API を使用してアプリの広告キャンペーンを管理できます。メディアエージェンシーもこの API へのアクセスを要求して、広告主の代わりに広告キャンペーンを実行できます。お客様がメディアエージェンシーで、この API について詳しい情報を希望される場合、またはこの API へのアクセスを要求される場合は、storepromotionsapi@microsoft.com までリクエストをお送りください。

手順 1: Microsoft Store プロモーション API を使うための前提条件を満たす

Microsoft Store プロモーション API を呼び出すコードの作成を開始する前に、次の前提条件が満たされていることを確認します。

この API を使用して広告キャンペーンを正しく作成および開始するには、事前に、パートナーセンターの [広告キャンペーン] ページを使用して、有料の広告キャンペーンを 1 つ作成する必要があります。また、このページで支払い方法を少なくとも 1 つ追加する必要があります。これを行うと、この API を使用して、広告キャンペーンの請求可能な配信ラインを正しく作成することができます。この API を使用して作成した広告キャンペーンの配信ラインでは、パートナーセンターの [広告キャンペーン] ページで選択した既定の支払い方法に対して自動的に請求が行われます。
自分 (または自分の組織) に Azure AD ディレクトリがあり、自分がそのディレクトリに対するグローバル管理者のアクセス許可を持っている必要があります。 Microsoft 365 または Microsoft の他のビジネスサービスをすでに使用している場合、Azure AD ディレクトリをすでに所有しています。それ以外の場合は、追加料金なしにパートナーセンターで新しい Azure AD を作成できます。
Azure AD アプリケーションをパートナーセンターアカウントに関連付け、アプリケーションのテナント ID とクライアント ID を取得してキーを生成する必要があります。 Azure AD アプリケーションは、Microsoft Store プロモーション API の呼び出し元のアプリまたはサービスを表します。 API に渡す Azure AD アクセストークンを取得するには、テナント ID、クライアント ID、キーが必要です。

Note

この作業を行うのは一度だけです。テナント 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 分が経過する前に使用します。トークンの有効期限が切れた後は、トークンを更新してそれ以降の 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 メソッドも用意されています。

これらオブジェクトと関連するメソッドについての詳細は、以下の表を参照してください。

Object	説明
キャンペーン	このオブジェクトは広告キャンペーンを表し、広告キャンペーンのオブジェクトモデル階層の最上位に置かれます。このオブジェクトは、実行するキャンペーンの種類 (有料、自社、またはコミュニティ)、キャンペーン目標、広告キャンペーンの配信ライン、その他の詳細情報を示します。 1 つのキャンペーンに関連づけることができるのは、1 つのアプリのみです。このオブジェクトについて詳しくは、「広告キャンペーンの管理」をご覧ください。注広告キャンペーンの作成後は、Microsoft Store 分析 API の「広告キャンペーンのパフォーマンスデータの取得」の方法を使って、キャンペーンのパフォーマンスデータを取得できます。
配信ライン	キャンペーンごとに、インベントリの購入と広告の配信に使用する配信ラインが 1 つ以上あります。配信ラインごとに、ターゲットと入札額を設定できます。また、予算と使用したいクリエイティブへのリンクを設定することで、支払い額を決定できます。このオブジェクトについて詳しくは、「広告キャンペーンの配信ラインの管理」をご覧ください。
ターゲットプロファイル	配信ラインごとに、1 つのターゲットプロファイルを用意します。ターゲットプロファイルでは、対象にするユーザー、地域、およびインベントリの種類を指定します。ターゲットプロファイルは、テンプレートとして作成し、複数の配信ライン間で共有できます。このオブジェクトについて詳しくは、「広告キャンペーンのターゲットプロファイルの管理」をご覧ください。
クリエイティブ	配信ラインごとに、キャンペーンの一環でお客様に表示される広告を表すクリエイティブが 1 つ以上あります。クリエイティブは、常に同じアプリを表す場合は、同一の広告キャンペーンでなくても、1 つ以上の配信ラインに関連付けることができます。このオブジェクトについて詳しくは、「広告キャンペーンのクリエイティブの管理」をご覧ください。

次の図は、キャンペーン、配信ライン、ターゲットプロファイル、クリエイティブ間の関係を表しています。

広告キャンペーンの階層

コードの例

次のコード例は、Azure AD アクセストークンを取得し、C# コンソールアプリから Microsoft Store プロモーション API を呼び出す方法を示しています。このコード例を使う場合は、変数 tenantId、clientId、clientSecret、および appID を自分のシナリオに合った適切な値に割り当ててください。この例では、Microsoft Store プロモーション API から返される JSON データを逆シリアル化するときに、Newtonsoft の Json.NET パッケージが必要になります。

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

次の方法で共有

ストアサービスを使用した広告キャンペーンの実行

手順 1: Microsoft Store プロモーション API を使うための前提条件を満たす

手順 2:Azure AD アクセストークンを取得する

手順 3: Microsoft Store プロモーション API を呼び出す

コードの例

フィードバック

フィードバック

その他のリソース

次の方法で共有

ストア サービスを使用した広告キャンペーンの実行

手順 1: Microsoft Store プロモーション API を使うための前提条件を満たす

手順 2:Azure AD アクセス トークンを取得する

手順 3: Microsoft Store プロモーション API を呼び出す

コードの例

関連トピック

フィードバック

フィードバック

その他のリソース

ストアサービスを使用した広告キャンペーンの実行

手順 2:Azure AD アクセストークンを取得する