広告のパフォーマンスデータの取得

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

日付範囲やその他のオプションフィルターを指定して、アプリケーションの広告のパフォーマンスに関する集計データを取得するには、Microsoft Store 分析 API の以下のメソッドを使います。このメソッドは、データを JSON 形式で返します。

このメソッドは、パートナーセンターの広告パフォーマンスレポートで提供されるのと同じデータを返します。

前提条件

このメソッドを使うには、最初に次の作業を行う必要があります。

Microsoft Store 分析 API に関するすべての前提条件を満たします (前提条件がまだ満たされていない場合)。
このメソッドの要求ヘッダーで使う Azure AD アクセストークンを取得します。アクセストークンを取得した後、アクセストークンを使用できるのは、その有効期限が切れるまでの 60 分間です。トークンの有効期限が切れたら新しいトークンを取得できます。

詳しくは、「Microsoft Store サービスを使った分析データへのアクセス」をご覧ください。

要求

要求の構文

認証方法	要求 URI
GET	`https://manage.devcenter.microsoft.com/v1.0/my/analytics/adsperformance`

要求ヘッダー

Header	型	説明
承認	string	必須。 Bearer<トークン> という形式の Azure AD アクセストークン。

要求パラメーター

特定のアプリに関する広告のパフォーマンスデータを取得するには、applicationId パラメーターを使用します。開発者アカウントに関連付けられているすべてのアプリに関する広告パフォーマンスデータを取得するには、applicationId パラメーターは省略します。

パラメーター	型	内容	必須
applicationId	string	広告のパフォーマンスデータを取得するアプリの Store ID です。	No
startDate	日付	広告のパフォーマンスデータを取得する日付範囲の開始日です。YYYY/MM/DD の形式で指定します。既定値は、現在の日付から 30 日を差し引いた日付になります。	いいえ
endDate	日付	広告のパフォーマンスデータを取得する日付範囲の終了日です。YYYY/MM/DD の形式で指定します。既定値は、現在の日付から 1 日を差し引いた日付になります。	いいえ
top	int	要求で返すデータの行数です。最大値および指定しない場合の既定値は 10000 です。クエリにこれを上回る行がある場合は、応答本文に次リンクが含まれ、そのリンクを使ってデータの次のページを要求できます。	いいえ
skip	int	クエリでスキップする行数です。大きなデータセットを操作するには、このパラメーターを使用します。たとえば、top=10000 と skip=0 を指定すると、データの最初の 10,000 行が取得され、top=10000 と skip=10000 を指定すると、データの次の 10,000 行が取得されます。	No
filter	string	応答内の行をフィルター処理する 1 つまたは複数のステートメントです。詳しくは、次の「フィルターフィールド」セクションをご覧ください。	No
aggregationLevel	string	集計データを取得する時間範囲を指定します。次のいずれかの文字列を指定できます。day、week、または month。指定しない場合、既定値は day です。	No
orderby	string	結果データ値の順序を指定するステートメントです。構文は orderby=field [order],field [order],... です。field パラメーターは次のいずれかの文字列になります。 date market deviceType adUnitId order パラメーターは省略可能であり、asc または desc を指定して、各フィールドを昇順または降順にすることができます。既定値は asc です。 orderby 文字列の例: orderby=date,market	No
groupby	string	指定したフィールドのみにデータ集計を適用するステートメントです。次のフィールドを指定できます。 applicationId applicationName date accountCurrencyCode market deviceType adUnitName adUnitId pubCenterAppName adProvider groupby パラメーターは、aggregationLevel パラメーターと同時に使用できます。例: &groupby=applicationId&aggregationLevel=week	いいえ

フィルターフィールド

要求本文の filter パラメーターには、応答内の行をフィルター処理する 1 つまたは複数のステートメントが含まれます。各ステートメントには eq 演算子または ne 演算子と関連付けられるフィールドと値が含まれ、and または or を使ってステートメントを組み合わせることができます。 filter パラメーターの例を次に示します。

filter=market eq 'US' and deviceType eq 'phone'

サポートされているフィールドの一覧については、次の表をご覧ください。 filter パラメーターでは、文字列値を単一引用符で囲む必要があります。

フィールド	説明
market	広告が提供された市場の ISO 3166 国コードを含む文字列です。
deviceType	PC/Tablet または Phone のどちらかの文字列になります。
adUnitId	フィルターに適用する広告ユニット ID を指定する文字列です。
pubCenterAppName	フィルターに適用する、現在のアプリの pubCenter 名を指定する文字列です。
adProvider	フィルターに適用する広告プロバイダー名を指定する文字列です。
日付	フィルターに適用する YYYY/MM/DD 形式の日付を指定する文字列です。

要求の例

広告のパフォーマンスデータを取得するための要求の例を、いくつか次に示します。 applicationId 値を、目的のアプリのストア ID に置き換えてください。

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/adsperformance?applicationId=9NBLGGH4R315&startDate=1/1/2015&endDate=2/1/2015&top=10&skip=0  HTTP/1.1
Authorization: Bearer <your access token>

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/adsperformance?applicationId=9NBLGGH4R315&startDate=8/1/2015&endDate=8/31/2015&skip=0&$filter=market eq 'US' and deviceType eq 'phone’ eq 'US'; and gender eq 'm'  HTTP/1.1
Authorization: Bearer <your access token>

[応答]

応答本文

値	種類	説明
値	array	広告のパフォーマンスに関する集計データが含まれるオブジェクトの配列です。各オブジェクトのデータについて詳しくは、次の「広告のパフォーマンスの値」セクションをご覧ください。
@nextLink	string	データの追加ページがある場合、この文字列には、データの次のページを要求するために使用できる URI が含まれます。たとえば、要求の top パラメーターが 5 に設定されたが、クエリに対するデータに 5 個を超える項目が含まれている場合に、この値が返されます。
TotalCount	int	クエリの結果データ内の行の総数です。

広告のパフォーマンスの値

Value 配列の要素には、次の値が含まれます。

値	種類	説明
date	string	広告のパフォーマンスデータの対象となる日付範囲の最初の日付です。要求に日付を指定した場合、この値はその日付になります。要求に週、月、またはその他の日付範囲を指定した場合、この値はその日付範囲の最初の日付になります。
applicationId	string	広告のパフォーマンスデータを取得するアプリのストア ID です。
applicationName	string	アプリの表示名です。
adUnitId	string	広告ユニットの ID です。
adUnitName	string	パートナーセンターで開発者によって指定されている広告ユニットの名前です。
adProvider	string	広告プロバイダーの名前です。
deviceType	string	広告が提供されたデバイスの種類です。サポートされる文字列の一覧については、前の「フィルターフィールド」セクションをご覧ください。
market	string	広告が提供された市場の ISO 3166 国コードです。
accountCurrencyCode	string	アカウントの通貨コードです。
pubCenterAppName	string	パートナーセンターでアプリに関連付けられている、pubCenter アプリの名前です。
adProviderRequests	int	指定した広告プロバイダーに対する広告要求の数です。
impressions	int	広告インプレッションの数です。
clicks	int	クリックの数です。
revenueInAccountCurrency	number	アカウントの国/地域の通貨に基づく収益です。
requests	int	広告要求の数です。

応答の例

この要求の JSON 返信の本文の例を次に示します。

{
  "Value": [
    {
      "date": "2015-03-09",
      "applicationId": "9NBLGGH4R315",
      "applicationName": "Contoso Demo",
      "market": "US",
      "deviceType": "phone",
      "adUnitId":"10765920",
      "adUnitName":"TestAdUnit",
      "revenueInAccountCurrency": 10.0,
      "impressions": 1000,
      "requests": 10000,
      "clicks": 1,
      "accountCurrencyCode":"USD"
    },
    {
      "date": "2015-03-09",
      "applicationId": "9NBLGGH4R315",
      "applicationName": "Contoso Demo",
      "market": "US",
      "deviceType": "phone",
      "adUnitId":"10795110",
      "adUnitName":"TestAdUnit2",
      "revenueInAccountCurrency": 20.0,
      "impressions": 2000,
      "requests": 20000,
      "clicks": 3,
      "accountCurrencyCode":"USD"
    },
  ],
  "@nextLink": "adsperformance?applicationId=9NBLGGH4R315&aggregationLevel=week&startDate=2015/03/01&endDate=2016/02/01&top=2&skip=2",
  "TotalCount": 191753
}

次の方法で共有

広告のパフォーマンスデータの取得

前提条件

要求

要求の構文

要求ヘッダー

要求パラメーター

フィルターフィールド

要求の例

[応答]

応答本文

広告のパフォーマンスの値

応答の例

フィードバック

その他のリソース

次の方法で共有

広告のパフォーマンス データの取得

前提条件

要求

要求の構文

要求ヘッダー

要求パラメーター

フィルター フィールド

要求の例

[応答]

応答本文

広告のパフォーマンスの値

応答の例

関連トピック

フィードバック

その他のリソース

広告のパフォーマンスデータの取得

フィルターフィールド