本指南涵蓋即時出價疑難排解資源,讓您透過程式輔助方式存取即時出價廣告活動指標。這些指標也會透過 Authorized Buyers UI 中的即時出價明細工具顯示。包括 bidders.filterSets
、bidders.accounts.filterSets
,以及其階層下的所有資源。
您可以使用即時出價疑難排解資源中的指標,深入瞭解錯失的曝光機會,進而最佳化您的即時出價廣告活動。
調整 API 結構和樣式
即時出價疑難排解資源加入幾項變更,明確指出擁有權和存取權、以更精細的方式控制 API 傳回的資料,以及更符合 Google API 設計做法。
出價方層級與帳戶層級資源
資源皆位於 bidders
和 bidders.accounts
底下。透過這些條件,您可以指定 API 呼叫要指定出價方 (也稱為上層帳戶)、所有相關聯的子帳戶,還是個別 Authorized Buyers 帳戶。在即時出價疑難排解中,位於 bidders.filterSets
底下的資源會傳回指定出價方和所有相關聯子帳戶的匯總指標。相對地,無論帳戶是出價工具還是子帳戶,bidders.accounts.filterSets
值下的資料都只會傳回指定帳戶的指標。
注意:將出價委派給其他買方的帳戶並非出價工具帳戶,因此無法存取出價工具層級資源。此外,非出價工具的帳戶無法存取帳戶層級 impressionMetrics
、filteredBidResponses
、bidResponseErrors
和 bidResponsesWithoutBids
資源。
將資源名稱當做專屬 ID 隆重登場
資源名稱是做為專屬 ID,而非整數或字串 ID。建立新的指定資源類型的執行個體時,您現在必須使用資源的 URI 路徑再加上偏好的資源 ID 指定相對資源名稱。以下是與即時出價疑難排解資源相關的名稱範例:
資源 | 名稱範例 |
---|---|
bidders.filterSets | bidders/12345678/filterSets/fset_1 |
bidders.accounts.filterSets | bidders/12345678/accounts/87654321/filterSets/fset_2 |
注意:bidders
在名稱中指定的資源 ID 必須是出價方的 Authorized Buyers 帳戶 ID。accounts
的資源 ID 必須是出價方或由其管理的子帳戶 ID。如果您不知道哪些 Authorized Buyers 帳戶與您的 Google 帳戶相關聯,可以使用 accounts.list 方法尋找。
篩選器集
篩選器集代表可用的篩選選項,可在出價方或帳戶層級建立。可用於篩選 RTB 疑難排解資源的清單結果,這些資源會擷取即時出價廣告活動的指標。
擷取指標時套用的篩選器是指定篩選器組合中每個篩選器的交集。系統會將清單篩選器 (例如 platforms
) 解讀為清單中每個項目的聯集。
出價方和帳戶層級的篩選器組合互不相同,而且只能在建立時從建立時存取 (無論用來建立出價方的帳戶為何)。出價方和子帳戶共用篩選器組合是在帳戶層級建立,而只有出價工具可以存取出價工具層級的資源。下表摘要說明出價方和子帳戶在任一層級存取資源的方式:
bidders.filterSets | bidders.accounts.filterSets | |
---|---|---|
出價方帳戶 | API 呼叫只會影響出價方層級篩選器集。 | API 呼叫只會影響帳戶層級篩選器組合。 |
子帳戶 | 這個 API 呼叫會傳回錯誤回應。 | API 呼叫只會影響帳戶層級篩選器組合。 |
建立篩選器組合
建立篩選器組合時,您必須將時間範圍指定為 relativeDateRange
、absoluteDateRange
或 realtimeTimeRange
。擷取指標時,預設行為是針對整個時間範圍內提供所有資料。如果您想接收時間範圍內的時間序列細目,您可以指定 timeSeriesGranularity
來表示 HOURLY
或 DAILY
間隔。
如果短時間內只需要設定篩選器,可將 isTransient
查詢參數設為 true
。這表示該篩選器組合是暫時性的,也就是不會無限期保留。暫時性篩選器集在建立後的至少一小時內可供使用,不過系統最終會刪除這些篩選器集。根據預設,篩選器集不是暫時性的。
出價方層級範例
如要建立新的出價方層級篩選器組合,請將 POST
要求傳送至 bidders.filterSets
資源 URI,其格式如下:
https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/filterSets
警告:出價方層級的篩選器組合無法依廣告素材或交易 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 狀態碼回應,回應主體會包含建立的篩選器集資源,該資源與要求中提交的篩選器集相同。
帳戶層級範例
如要建立新的帳戶層級篩選器組合,請將 POST
要求傳送至 bidders.accounts.filterSets
資源 URI,其格式如下:
https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/accounts/{account resource ID}/filterSets
注意:針對 accounts
指定的資源 ID,可以是 URI 中指定的出價方帳戶可存取的任何 Authorized Buyers 帳戶 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.accounts.filterSets.get
擷取在帳戶層級建立的篩選器組合,而非 bidders.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
為自己建立的篩選器組合。
出價方層級
您可以擷取特定出價方的所有出價方層級篩選器組合,方法是將 HTTP GET
要求傳送至 bidders.filtersets
資源 URI,格式如下:
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" } ] }
帳戶層級
您可以擷取特定帳戶的所有帳戶層級篩選器組合,方法是將 HTTP GET
要求傳送至 bidders.accounts.filtersets
資源 URI,格式如下:
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.accounts.filterSets.create
建立的篩選器組合 (使用 bidders.filterSets.delete
)。
出價方層級
您可以刪除特定帳戶的出價方層級篩選器組合,方法是傳送 HTTP DELETE
要求至 bidders.filtersets
資源 URI,其格式如下:
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回應
如果成功,要求主體會留空。你將無法再存取指定的篩選器組合。
擷取即時出價疑難排解指標
用於接收指標的所有即時出價疑難排解資源,都是以類似方式運作的單一方法,可以列出透過 filterSetName
路徑參數指定的篩選器集指標。指定的篩選器集會決定您在查詢指標時要套用哪些篩選器與設定。從出價方層級呼叫這些資源時,系統會傳回出價方帳戶和所有相關聯子帳戶的匯總指標,而來自帳戶層級的呼叫只會傳回個人帳戶的指標。
出價指標
bidMetrics
資源可用於擷取以出價次數計算的指標。舉例來說,您可以使用這個指標來判斷特定時間範圍內的出價總數,以及未從競價中篩除或贏得曝光的出價總數。就像用於收集指標的其他所有 RTB 疑難排解資源一樣,只有 list
方法。
列出出價方層級出價指標
您可以傳送 HTTP GET
要求至 bidders.filtersets.bidMetrics
資源 URI,並按照下列格式列出特定篩選器組合的出價工具層級出價指標:
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。
警告:對於回應中的任何資料細目,如果回應中未包含至少一項非零指標,回應就不會包含資料列。例如,如果指定 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。
警告:對於回應中的任何資料細目,如果回應中未包含至少一項非零指標,回應就不會包含資料列。例如,如果指定 timeSeriesGranularity
,則回應不會包含篩選器組合指定時間範圍內任何 timeInterval
的資料列,而所有指標均為零。