広告のパフォーマンス データの取得
日付範囲やその他のオプション フィルターを指定して、アプリケーションの広告のパフォーマンスに関する集計データを取得するには、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 パラメーターは省略します。
| パラメーター | Type | 内容 | 必須 |
|---|---|---|---|
| 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 パラメーターは次のいずれかの文字列になります。
order パラメーターは省略可能であり、asc または desc を指定して、各フィールドを昇順または降順にすることができます。 既定値は asc です。 orderby 文字列の例: orderby=date,market |
No |
| groupby | string | 指定したフィールドのみにデータ集計を適用するステートメントです。 次のフィールドを指定できます。
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
}
関連トピック
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示