広告キャンペーンのパフォーマンス データの取得Get ad campaign performance data

日付範囲やその他のオプション フィルターを指定して、アプリケーションに関するプロモーション用広告キャンペーンのパフォーマンス データの集計サマリーを取得するには、Microsoft Store 分析 API の以下のメソッドを使います。Use this method in the Microsoft Store analytics API to get an aggregate summary of promotional ad campaign performance data for your applications during a given date range and other optional filters. このメソッドは、データを JSON 形式で返します。This method returns the data in JSON format.

このメソッドは、パートナーセンターの Ad キャンペーンレポート によって提供されるものと同じデータを返します。This method returns the same data that is provided by the Ad campaign report in Partner Center. 広告キャンペーンについて詳しくは、「アプリ向けの広告キャンペーンの作成」をご覧ください。For more information about ad campaigns, see Create an ad campaign for your app.

広告キャンペーンの詳細を作成、更新、取得するには、Microsoft Store プロモーション API広告キャンペーンの管理メソッドを使用します。To create, update, or retrieve details for ad campaigns, you can use the Manage ad campaigns methods in the Microsoft Store promotions API.

前提条件Prerequisites

このメソッドを使うには、最初に次の作業を行う必要があります。To use this method, you need to first do the following:

  • Microsoft Store 分析 API に関するすべての前提条件を満たします (前提条件がまだ満たされていない場合)。If you have not done so already, complete all the prerequisites for the Microsoft Store analytics API.
  • このメソッドの要求ヘッダーで使う Azure AD アクセス トークンを取得します。Obtain an Azure AD access token to use in the request header for this method. アクセス トークンを取得した後、アクセス トークンを使用できるのは、その有効期限が切れるまでの 60 分間です。After you obtain an access token, you have 60 minutes to use it before it expires. トークンの有効期限が切れたら新しいトークンを取得できます。After the token expires, you can obtain a new one.

RequestRequest

要求の構文Request syntax

認証方法Method 要求 URIRequest URI
GETGET https://manage.devcenter.microsoft.com/v1.0/my/analytics/promotion

要求ヘッダーRequest header

HeaderHeader TypeType 説明Description
承認Authorization stringstring 必須。Required. Bearer <トークン> という形式の Azure AD アクセス トークン。The Azure AD access token in the form Bearer <token>.

要求パラメーターRequest parameters

特定のアプリに関する広告キャンペーンのパフォーマンス データを取得するには、applicationId パラメーターを使用します。To retrieve ad campaign performance data for a specific app, use the applicationId parameter. 開発者アカウントに関連付けられているすべてのアプリに関する広告パフォーマンス データを取得するには、applicationId パラメーターは省略します。To retrieve ad performance data for all apps that are associated with your developer account, omit the applicationId parameter.

パラメーターParameter TypeType 説明Description 必須Required
applicationIdapplicationId stringstring 広告キャンペーンパフォーマンスデータを取得するアプリの ストア IDThe Store ID of the app for which you want to retrieve ad campaign performance data. いいえNo
startDatestartDate 日付date 広告キャンペーンのパフォーマンス データを取得する日付範囲の開始日です。YYYY/MM/DD の形式で指定します。The start date in the date range of ad campaign performance data to retrieve, in the format YYYY/MM/DD. 既定値は、現在の日付から 30 日を差し引いた日付になります。The default is the current date minus 30 days. いいえNo
endDateendDate 日付date 広告キャンペーンのパフォーマンス データを取得する日付範囲の終了日です。YYYY/MM/DD の形式で指定します。The end date in the date range of ad campaign performance data to retrieve, in the format YYYY/MM/DD. 既定値は、現在の日付から 1 日を差し引いた日付になります。The default is the current date minus one day. いいえNo
toptop intint 要求で返すデータの行数です。The number of rows of data to return in the request. 最大値および指定しない場合の既定値は 10000 です。The maximum value and the default value if not specified is 10000. クエリにこれを上回る行がある場合は、応答本文に次リンクが含まれ、そのリンクを使ってデータの次のページを要求できます。If there are more rows in the query, the response body includes a next link that you can use to request the next page of data. いいえNo
skipskip intint クエリでスキップする行数です。The number of rows to skip in the query. 大きなデータ セットを操作するには、このパラメーターを使用します。Use this parameter to page through large data sets. たとえば、top=10000 と skip=0 を指定すると、データの最初の 10,000 行が取得され、top=10000 と skip=10000 を指定すると、データの次の 10,000 行が取得されます。For example, top=10000 and skip=0 retrieves the first 10000 rows of data, top=10000 and skip=10000 retrieves the next 10000 rows of data, and so on. いいえNo
filterfilter stringstring 応答内の行をフィルター処理する 1 つまたは複数のステートメントです。One or more statements that filter the rows in the response. サポートされているフィルターは campaignId のみです。The only supported filter is campaignId. 各ステートメントでは eqne 演算子を使用できます。また、ステートメントを andor で結合することもできます。Each statement can use the eq or ne operators, and statements can be combined using and or or. filter パラメーターの例: filter=campaignId eq '100023'Here is an example filter parameter: filter=campaignId eq '100023'. いいえNo
aggregationLevelaggregationLevel stringstring 集計データを取得する時間範囲を指定します。Specifies the time range for which to retrieve aggregate data. 次のいずれかの文字列を指定できます。dayweek、または monthCan be one of the following strings: day, week, or month. 指定しない場合、既定値は day です。If unspecified, the default is day. いいえNo
orderbyorderby stringstring

広告キャンペーンのパフォーマンス データに関する結果データ値の順序を指定するステートメントです。A statement that orders the result data values for the ad campaign performance data. 構文は orderby=field [order],field [order],... です。field パラメーターは次のいずれかの文字列になります。The syntax is orderby=field [order],field [order],.... The field parameter can be one of the following strings:

  • datedate
  • campaignIdcampaignId

order パラメーターは省略可能であり、asc または desc を指定して、各フィールドを昇順または降順にすることができます。The order parameter is optional, and can be asc or desc to specify ascending or descending order for each field. 既定値は ascです。The default is asc.

Orderby文字列の例を次に示します。 orderby = date, campaignIdHere is an example orderby string: orderby=date,campaignId

いいえNo
groupbygroupby stringstring

指定したフィールドのみにデータ集計を適用するステートメントです。A statement that applies data aggregation only to the specified fields. 次のフィールドを指定できます。You can specify the following fields:

  • campaignIdcampaignId
  • applicationIdapplicationId
  • datedate
  • currencyCodecurrencyCode

groupby パラメーターは、aggregationLevel パラメーターと同時に使用できます。The groupby parameter can be used with the aggregationLevel parameter. 例: & Groupby = applicationId & aggregationLevel = weekFor example: &groupby=applicationId&aggregationLevel=week

いいえNo

要求の例Request example

広告キャンペーンのパフォーマンス データを取得するための要求の例を、いくつか次に示します。The following example demonstrates several requests for getting ad campaign performance data.

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/promotion?aggregationLevel=week&groupby=applicationId,campaignId,date  HTTP/1.1
Authorization: Bearer <your access token>

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/promotion?applicationId=9NBLGGH0XK8Z&startDate=2015/1/20&endDate=2016/8/31&skip=0&filter=campaignId eq '31007388' HTTP/1.1
Authorization: Bearer <your access token>

[応答]Response

応答本文Response body

Value TypeType 説明Description
Value arrayarray 広告キャンペーンのパフォーマンスに関する集計データが含まれるオブジェクトの配列です。An array of objects that contain aggregate ad campaign performance data. 各オブジェクトのデータについて詳しくは、次の「キャンペーンのパフォーマンス オブジェクト」セクションをご覧ください。For more information about the data in each object, see the campaign performance object section below.
@nextLink stringstring データの追加ページがある場合、この文字列には、データの次のページを要求するために使用できる URI が含まれます。If there are additional pages of data, this string contains a URI that you can use to request the next page of data. たとえば、要求の top パラメーターが 5 に設定されたが、クエリに対するデータに 5 個を超える項目が含まれている場合に、この値が返されます。For example, this value is returned if the top parameter of the request is set to 5 but there are more than 5 items of data for the query.
TotalCountTotalCount INTint クエリの結果データ内の行の総数です。The total number of rows in the data result for the query.

キャンペーンのパフォーマンス オブジェクトCampaign performance object

Value 配列の要素には、次の値が含まれます。Elements in the Value array contain the following values.

Value TypeType 説明Description
datedate stringstring 広告キャンペーンのパフォーマンス データの対象となる日付範囲の最初の日付です。The first date in the date range for the ad campaign performance data. 要求に日付を指定した場合、この値はその日付になります。If the request specified a single day, this value is that date. 要求に週、月、またはその他の日付範囲を指定した場合、この値はその日付範囲の最初の日付になります。If the request specified a week, month, or other date range, this value is the first date in that date range.
applicationIdapplicationId stringstring 広告キャンペーンのパフォーマンス データを取得するアプリのストア ID です。The Store ID of the app for which you are retrieving ad campaign performance data.
campaignIdcampaignId stringstring 広告キャンペーンの ID です。The ID of the ad campaign.
lineIdlineId stringstring このパフォーマンス データを生成した広告キャンペーン配信ラインの ID です。The ID of the ad campaign delivery line that generated this performance data.
currencyCodecurrencyCode stringstring キャンペーン予算の通貨コードです。The currency code of the campaign budget.
spendspend stringstring 広告キャンペーンで消費した予算金額です。The budget amount that has been spent for the ad campaign.
impressionsimpressions longlong キャンペーンの広告インプレッションの数です。The number of ad impressions for the campaign.
installsinstalls longlong キャンペーンに関連するアプリのインストールの数です。The number of app installs related to the campaign.
clicksclicks longlong キャンペーンの広告クリックの数です。The number of ad clicks for the campaign.
iapInstallsiapInstalls longlong キャンペーンに関連するアドオン (アプリ内購入または IAP とも呼ばれます) のインストールの数。The number of add-on (also called in-app purchase or IAP) installs related to the campaign.
activeUsersactiveUsers longlong キャンペーンの一部である広告をクリックし、アプリに戻ったユーザーの数です。The number of users who have clicked an ad that is part of the campaign and returned to the app.

応答の例Response example

この要求の JSON 返信の本文の例を次に示します。The following example demonstrates an example JSON response body for this request.

{
  "Value": [
    {
      "date": "2015-04-12",
      "applicationId": "9WZDNCRFJ31Q",
      "campaignId": "4568",
      "lineId": "0001",
      "currencyCode": "USD",
      "spend": 700.6,
      "impressions": 200,
      "installs": 30,
      "clicks": 8,
      "iapInstalls": 0,
      "activeUsers": 0
    },
    {
      "date": "2015-05-12",
      "applicationId": "9WZDNCRFJ31Q",
      "campaignId": "1234",
      "lineId": "0002",
      "currencyCode": "USD",
      "spend": 325.3,
      "impressions": 20,
      "installs": 2,
      "clicks": 5,
      "iapInstalls": 0,
      "activeUsers": 0
    }
  ],
  "@nextLink": "promotion?applicationId=9NBLGGGZ5QDR&aggregationLevel=day&startDate=2015/1/20&endDate=2016/8/31&top=2&skip=2",
  "TotalCount": 1917
}