このガイドでは、RTB トラブルシューティングのリソースについて説明します。このリソースでは、認定バイヤーの UI にある RTB 解析ツールでも公開されているリアルタイム ビッダー キャンペーンの指標にプログラマティックにアクセスできます。これには、bidders.filterSets、bidders.accounts.filterSets、およびその下のすべてのリソースが階層的に含まれます。
RTB トラブルシューティング リソースの指標を使用すると、インプレッション獲得の機会を逃すインサイトを確認し、リアルタイム ビッダー キャンペーンの最適化に役立てることができます。
API の構造とスタイルの調整
RTB トラブルシューティング リソースでは、所有権とアクセス権を明示的に示し、API から返されるデータをより細かく制御し、Google API の設計方法に沿うようにいくつかの変更が加えられています。
ビッダーレベルとアカウント レベルのリソース
リソースは bidders と bidders.accounts の両方で構造化されます。これにより、API 呼び出しの対象がビッダー（親アカウント）と関連するすべての子アカウントか、個々の認定バイヤー アカウントかを指定できます。RTB トラブルシューティングのコンテキストでは、bidders.filterSets で構造化されたリソースは、指定されたビッダーと、関連するすべての子アカウントに関する集計指標を返します。一方、bidders.accounts.filterSets の下にあるものは、それがビッダー アカウントか子アカウントかにかかわらず、指定されたアカウントの指標のみを返します。
注: 別の購入者に入札を委任したアカウントは入札者アカウントではないため、ビッダーレベルのリソースにアクセスできません。また、入札者以外のアカウントは、アカウント レベルの impressionMetrics、filteredBidResponses、bidResponseErrors、bidResponsesWithoutBids リソースにアクセスできません。
一意の識別子としてのリソース名の導入
リソース名は、整数または文字列の ID ではなく、一意の識別子として使用されます。特定のリソースタイプの新しいインスタンスを作成するときは、リソースの URI パスの後に優先リソース ID を続けて指定し、相対的なリソース名を指定することが必要になりました。RTB トラブルシューティング リソースに関連する名前の例を次に示します。
| リソース | 名前の例 |
|---|---|
| bidders.filterSets | bidders/12345678/filterSets/fset_1 |
| bidders.accounts.filterSets | bidders/12345678/accounts/87654321/filterSets/fset_2 |
注: 名前の bidders に指定するリソース ID は、ビッダーの認定バイヤー アカウント ID である必要があります。accounts の場合、リソース ID はビッダーのアカウント ID、またはビッダーによって管理されている子アカウントのアカウント ID である必要があります。Google アカウントに関連付けられている認定バイヤー アカウントがわからない場合は、accounts.list メソッドで確認できます。
フィルタセット
フィルタセットは利用可能なフィルタリング オプションを表し、ビッダーまたはアカウント レベルで作成できます。リアルタイム ビッダー キャンペーンの指標を取得する RTB トラブルシューティング リソースのリスト結果をフィルタするために使用されます。
指標の取得時に適用されるフィルタは、指定したフィルタセット内の各フィルタの共通部分です。platforms などのリストフィルタは、リスト内の各アイテムの結合と解釈されます。
ビッダーとアカウント単位のフィルタセットは区別され、作成に使用したアカウントに関係なく、最初に作成されたレベルからのみアクセスできます。ビッダーと子アカウントは、アカウント レベルで作成されたフィルタセットを共有しますが、ビッダーだけがビッダーレベルでリソースにアクセスできます。次の表は、ビッダーと子アカウントが各レベルでリソースにアクセスする方法を示しています。
| bidders.filterSets | bidders.accounts.filterSets | |
|---|---|---|
| ビッダー アカウント | ビッダーレベルのフィルタセットのみに影響する API 呼び出し。 | アカウント レベルのフィルタセットのみに影響する API 呼び出し。 |
| お子様のアカウント | この API 呼び出しはエラー レスポンスを返します。 | アカウント レベルのフィルタセットのみに影響する API 呼び出し。 |
フィルタセットを作成
フィルタセットを作成する場合は、期間を relativeDateRange、absoluteDateRange、realtimeTimeRange のいずれかとして指定する必要があります。指標を取得する場合、デフォルトの動作では、期間全体のすべてのデータが提供されます。一定期間の時系列の内訳を取得する場合は、timeSeriesGranularity を指定して、HOURLY または DAILY の間隔を指定できます。
短期間のみフィルタを設定する必要がある場合は、isTransient クエリ パラメータを true に設定できます。これは、フィルタセットが一時的なもの、つまり無期限に保持されないことを示します。一時的なフィルタセットは、作成後 1 時間以上利用できますが、最終的には削除されます。デフォルトでは、フィルタセットは一時的なものではありません。
ビッダーレベルの例
新しいビッダーレベルのフィルタセットを作成するには、bidders.filterSets リソース URI に POST リクエストを送信します。形式は次のとおりです。
https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/filterSets
警告: ビッダーレベルのフィルタセットをクリエイティブ ID や取引 ID でフィルタすることはできません。ビッダーレベルのフィルタセットを作成するときにこれらのフィルタを指定すると、エラー レスポンスが返されます。
リクエスト以下は、一時的でないビッダーレベルのフィルタセットを作成する POST リクエストの例です。
POST https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/filterSets
Authorization: Bearer access token here
Content-Type: application/json
{
"name": "bidders/12345678/filterSets/bidder-fs",
"format": "DISPLAY",
"environment": "APP",
"platforms": ["TABLET", "MOBILE"],
"absoluteDateRange": {
"startDate": {
"month": 11,
"day": 26,
"year": 2017
},
"endDate": {
"month": 12,
"day": 3,
"year": 2017
}
},
"timeSeriesGranularity": "DAILY"
}
レスポンスリクエストが成功すると、サーバーは 200 OK ステータス コードを返します。レスポンスの本文には、作成されたフィルタセットのリソースが含まれます。これは、リクエストで送信されるフィルタセットと同じものです。
アカウント単位の例
新しいアカウント レベルのフィルタセットを作成するには、bidders.accounts.filterSets リソース URI に POST リクエストを送信します。形式は次のとおりです。
https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/accounts/{account resource ID}/filterSets
注: accounts で指定するリソース ID には、URI で指定されたビッダー アカウントにアクセス可能な任意の認定バイヤー アカウントのアカウント ID を指定できます。これには、ビッダー アカウント自体も含まれます。
以下は、一時的でないアカウント レベルのフィルタセットを新たに作成する POST リクエストの例です。
POST https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/accounts/87654321/filterSets
Authorization: Bearer access token here
Content-Type: application/json
{
"name": "bidders/12345678/accounts/87654321/filterSets/account-fs",
"format": "VIDEO",
"environment": "WEB",
"platforms": ["DESKTOP"],
"absoluteDateRange": {
"startDate": {
"month": 11,
"day": 26,
"year": 2017
},
"endDate": {
"month": 12,
"day": 3,
"year": 2017
}
},
"timeSeriesGranularity": "DAILY"
}
レスポンスリクエストが成功すると、サーバーは 200 OK ステータス コードを返します。レスポンスの本文には、作成されたフィルタセット リソースが含まれます。これは、リクエストで送信されるフィルタセットと同じものです。
フィルタセットを取得する
get メソッドは、作成されているレベルと同じレベルのフィルタセットのみを取得できます。たとえば、ビッダー アカウントでアカウント レベルで作成されたフィルタセットを取得するには、bidders.filterSets.get メソッドではなく bidders.accounts.filterSets.get を使用する必要があります。
入札者（ビッダー）レベル
ビッダーレベルのフィルタセットを取得するには、次の形式の HTTP GET リクエストを bidders.filterSets リソース URI に送信します。
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/filterSets/{filter set resource ID}
リクエスト次の例をご覧ください。
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/filterSets/bidder-fsレスポンス
リクエストが成功すると、サーバーは 200 OK HTTP ステータス コードと取得したフィルタセットを返します。
{
"name": "bidders/12345678/filterSets/bidder-fs",
"format": "DISPLAY",
"environment": "APP",
"platforms": ["TABLET", "MOBILE"],
"absoluteDateRange": {
"startDate": {
"month": 11,
"day": 26,
"year": 2017
},
"endDate": {
"month": 12,
"day": 3,
"year": 2017
}
},
"timeSeriesGranularity": "DAILY"
}
アカウント単位
アカウント単位のフィルタセットを取得するには、次の形式の HTTP GET リクエストを bidders.accounts.filterSets リソース URI に送信します。
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/accounts/{account resource ID}/filterSets/{filter set resource ID}
リクエスト次の例をご覧ください。
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/accounts/87654321/filterSets/account-fsレスポンス
リクエストが成功すると、サーバーは 200 OK HTTP ステータス コードと取得したフィルタセットを返します。
{
"name": "bidders/12345678/accounts/87654321/filterSets/account-fs",
"format": "VIDEO",
"environment": "WEB",
"platforms": ["DESKTOP"],
"absoluteDateRange": {
"startDate": {
"month": 11,
"day": 26,
"year": 2017
},
"endDate": {
"month": 12,
"day": 3,
"year": 2017
}
},
"timeSeriesGranularity": "DAILY"
}
フィルタセットを一覧表示する
list メソッドは、呼び出されているレベルからアクセスできるフィルタセットのみを返します。たとえば、ビッダー アカウントで bidders.filterSets.list を呼び出す場合、bidders.accounts.filterSets.create を通じて作成されたフィルタセットは表示されません。
入札者（ビッダー）レベル
特定のビッダーについて、すべてのビッダーレベルのフィルタセットを取得するには、次の形式の bidders.filtersets リソース URI に HTTP GET リクエストを送信します。
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/filterSets
リクエスト次の例では、アカウント ID が 12345678 のビッダーについて、ビッダー単位のフィルタセットをすべて一覧表示しています。
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/filterSetsレスポンス
{
"filterSets": [{
"filterSetId": "99994",
"name": "bidders/12345678/filterSets/test-b-1",
"relativeDateRange": {
"durationDays": 30
}
},
{
"realtimeTimeRange": {
"startTimeStamp": "2017-11-15T12:30:30.072831583Z"
},
"filterSetId": "99995",
"name": "bidders/12345678/filterSets/test-b-2",
"timeSeriesGranularity": "HOURLY"
},
{
"absoluteDateRange": {
"endDate": {
"day": 12,
"month": 3,
"year": 2017
},
"startDate": {
"day": 26,
"month": 11,
"year": 2017
}
},
"filterSetId": "99996",
"name": "bidders/12345678/filterSets/bidder-fs",
"timeSeriesGranularity": "DAILY",
"platforms": ["TABLET", "MOBILE"],
"environment": "APP",
"format": "DISPLAY"
}
]
}
アカウント単位
特定のアカウントのすべてのアカウント レベルのフィルタセットを取得するには、次の形式の bidders.accounts.filtersets リソース URI に HTTP GET リクエストを送信します。
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/accounts/{account resource ID}/filterSets
リクエスト次の例では、アカウント ID が 87654321 の子アカウントのアカウント単位のフィルタセットがすべて一覧表示されています。
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/accounts/87654321/filterSetsレスポンス
{
"filterSets": [{
"realtimeTimeRange": {
"startTimeStamp": "2017-11-19T04:24:43.252893487Z"
},
"filterSetId": "99997",
"name": "bidders/12345678/accounts/87654321/filterSets/test-a-1",
"timeSeriesGranularity": "DAILY"
},
{
"absoluteDateRange": {
"endDate": {
"day": 3,
"month": 12,
"year": 2017
},
"startDate": {
"day": 26,
"month": 11,
"year": 2017
}
},
"filterSetId": "99998",
"name": "bidders/12345678/accounts/87654321/filterSets/account-fs",
"timeSeriesGranularity": "DAILY",
"platforms": ["DESKTOP"],
"environment": "WEB",
"format": "VIDEO"
}
]
}
フィルタセットを削除する
delete メソッドを使用して、不要になった一時的でないフィルタセットを削除できます。呼び出し元のレベルからアクセスできるフィルタセットのみを削除できます。たとえば、ビッダー アカウントは、bidders.filterSets.delete で bidders.accounts.filterSets.create で作成されたフィルタセットを削除できません。
入札者（ビッダー）レベル
特定のアカウントに対して設定されたビッダーレベルのフィルタを削除するには、次の形式の bidders.filtersets リソース URI に HTTP DELETE リクエストを送信します。
DELETE https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/filterSets/{filter set resource ID}
リクエストビッダー単位のフィルタセットを削除する例を次に示します。
DELETE https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/filterSets/test-b-2レスポンス
成功した場合、リクエストの本文は空になります。指定したフィルタセットにアクセスできなくなります。
アカウント単位
特定のアカウントに対してアカウント レベルのフィルタセットを削除するには、次の形式の HTTP DELETE リクエストを bidders.accounts.filtersets リソース URI に送信します。
DELETE https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/accounts/{account resource ID}/filterSets/{filter set resource ID}
リクエストアカウント レベルのフィルタセットを削除する例を次に示します。
DELETE https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/accounts/87654321/filterSets/test-a-1レスポンス
成功した場合、リクエストの本文は空になります。指定したフィルタセットにアクセスできなくなります。
RTB トラブルシューティングの指標を取得する
指標の受信に使用されるすべての RTB トラブルシューティング リソースの動作は似ています。つまり、filterSetName パスパラメータで指定されたフィルタセットの指標を 1 つの方法で一覧表示できます。指定されたフィルタセットによって、指標をクエリする際に適用されるフィルタと設定が決まります。これらのリソースをビッダーレベルから呼び出すと、ビッダー アカウントと、関連付けられているすべての子アカウントから集計された指標が返されます。アカウント レベルで呼び出すと、個々のアカウントの指標のみが返されます。
入札単価の指標
bidMetrics リソースは、入札数で測定される指標を取得するために使用されます。たとえば、特定の期間における入札の総数や、オークションで除外されなかった入札数や、インプレッションを獲得した入札数などを確認できます。指標の収集に使用される他の RTB トラブルシューティング リソースと同様に、この関数には list メソッドのみがあります。
ビッダーレベルの入札指標のリスト
特定のフィルタセットに対してビッダーレベルの入札指標を一覧表示するには、次の形式の bidders.filtersets.bidMetrics リソース URI に HTTP GET リクエストを送信します。
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/filterSets/{filter set resource ID}/bidMetrics
リクエスト入札者レベルの入札指標のリストの例を次に示します。
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/filterSets/bidder-fs/bidMetricsレスポンス
リクエストが成功すると、サーバーは 200 OK ステータス コードと、指定されたディメンションと指標の指標の行を含む本文を返します。
{
"bidMetricsRows": [{
"bids": {
"value": "6160"
},
"bidsInAuction": {
"value": "5698"
},
"billedImpressions": {
"value": "1196"
},
"impressionsWon": {
"value": "2920"
},
"measurableImpressions": {
"value": "1160"
},
"rowDimensions": {
"timeInterval": {
"endTime": "2017-11-29T08:00:00Z",
"startTime": "2017-11-28T08:00:00Z"
}
},
"viewableImpressions": {
"value": "683"
}
},
{
"bids": {
"value": "104288"
},
"bidsInAuction": {
"value": "94016"
},
"billedImpressions": {
"value": "99"
},
"impressionsWon": {
"value": "125"
},
"measurableImpressions": {
"value": "94"
},
"rowDimensions": {
"timeInterval": {
"endTime": "2017-11-30T08:00:00Z",
"startTime": "2017-11-29T08:00:00Z"
}
},
"viewableImpressions": {
"value": "87"
}
},
{
"bids": {
"value": "3999"
},
"bidsInAuction": {
"value": "3631"
},
"billedImpressions": {
"value": "618"
},
"impressionsWon": {
"value": "1819"
},
"measurableImpressions": {
"value": "604"
},
"rowDimensions": {
"timeInterval": {
"endTime": "2017-12-01T08:00:00Z",
"startTime": "2017-11-30T08:00:00Z"
}
},
"viewableImpressions": {
"value": "369"
}
},
{
"bids": {
"value": "15"
},
"bidsInAuction": {
"value": "3"
},
"billedImpressions": {},
"impressionsWon": {
"value": "3"
},
"measurableImpressions": {},
"rowDimensions": {
"timeInterval": {
"endTime": "2017-12-02T08:00:00Z",
"startTime": "2017-12-01T08:00:00Z"
}
},
"viewableImpressions": {}
}
]
}
注: 特定の指標で 0 に設定されたフィールドは、レスポンスに表示されません。
上記の空の billedImpressions 指標と measurableImpressions 指標は、値と分散の両方が 0 に設定されていることを示します。
警告: レスポンス内のデータの内訳について、ゼロ以外の指標が 1 つ以上含まれていない場合、レスポンスに行は含まれません。たとえば、timeSeriesGranularity を指定すると、フィルタセットで指定された期間内ですべての指標がゼロである timeInterval の行は、レスポンスに含まれません。
アカウント単位の入札単価の指標をリストする
特定のフィルタセットに対するアカウント単位の入札指標を一覧表示するには、次の形式の HTTP GET リクエストを bidders.accounts.filtersets.bidMetrics リソース URI に送信します。
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/accounts/{account resource ID}/filterSets/{filter set resource ID}/bidMetrics
リクエストアカウント単位の入札関連の指標の例を次に示します。
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/accounts/87654321/filterSets/account-fs/bidMetricsレスポンス
リクエストが成功すると、サーバーは 200 OK ステータス コードと、指定されたディメンションと指標の指標の行を含む本文を返します。
{
"bidMetricsRows": [{
"bids": {
"value": "1748"
},
"bidsInAuction": {
"value": "1421"
},
"billedImpressions": {
"value": "301"
},
"impressionsWon": {
"value": "915"
},
"measurableImpressions": {
"value": "298"
},
"rowDimensions": {
"timeInterval": {
"endTime": "2017-12-01T08:00:00Z",
"startTime": "2017-11-30T08:00:00Z"
}
},
"viewableImpressions": {
"value": "172"
}
},
{
"bids": {
"value": "6"
},
"bidsInAuction": {
"value": "2"
},
"billedImpressions": {},
"impressionsWon": {
"value": "1"
},
"measurableImpressions": {},
"rowDimensions": {
"timeInterval": {
"endTime": "2017-12-02T08:00:00Z",
"startTime": "2017-12-01T08:00:00Z"
}
},
"viewableImpressions": {}
}
]
}
注: 特定の指標で 0 に設定されているフィールドは、レスポンスに表示されません。上記の空の billedImpressions 指標と measurableImpressions 指標は、値と分散の両方が 0 に設定されていることを示します。
警告: レスポンス内のデータの内訳について、ゼロ以外の指標が 1 つ以上含まれていない場合、レスポンスに行は含まれません。たとえば、timeSeriesGranularity を指定すると、フィルタセットで指定された期間内ですべての指標がゼロである timeInterval の行は、レスポンスに含まれません。