我們在 2022 年 3 月推出了 Bid Manager API 第 2 版。由於這個新版本推出,我們預計在 1.1 版即將終止服務。建議您盡快從 1.1 版遷移至 v2。
遷移應用程式
從 v1.1 遷移至 v2 時,您必須更新端點網址才能呼叫 v2,並更新應用程式以因應破壞性變更。
將 API 呼叫從 v1.1 更新為 v2
如要使用 v2 而非 v1.1,您需要將要求更新為使用新的 v2 端點。
辨別對等方法
如要將 API 呼叫從 v1.1 更新為 v2,您必須先找出 v2 中對等的 v1.1 方法。
下列所有服務和方法的名稱在 v1.1 和 v2 之間稍有變更:
- v1.1 中的服務
Queries
和Reports
在第 2 版中稱為queries
和queries.reports
。 - 第 2 版中的方法已變更如下:
更新至新端點
找出對等的方法後,請務必更新要求。舉例來說,如要透過 v1.1 呼叫 queries.getquery
方法,請使用下列網址:
https://www.googleapis.com/doubleclickbidmanager/v1.1/query/queryId
如要呼叫 v2 中的對等方法 (稱為 queries.get
),請將網址更新為以下內容:
GET https://doubleclickbidmanager.googleapis.com/v2/queries/queryId
如果您是透過用戶端程式庫向 API 發出要求,請使用最新版用戶端程式庫並更新設定以使用 v2。
進行必要變更
第 2 版將推出多項破壞性變更。請詳閱下列操作說明,並根據您目前的 Bid Manager API 使用情況進行必要變更。
更新向 queries
服務發出的呼叫
- 一般巢狀物件所代表的
Query
資源中的下列欄位已變更為使用下列物件類型: - 在一般清單物件代表的
Query
資源中,下列欄位已變更為下列新物件類型的清單: - 下列
Query
資源中的欄位原本是以字串表示,v2 中的列舉類型會以列舉類型表示,並包含下列變更:metadata.dataRange
的 v2 對等項目現在使用Range
列舉。為了轉換成此列舉,系統已移除PREVIOUS_HALF_MONTH
值,並將TYPE_NOT_SUPPORTED
值變更為RANGE_UNSPECIFIED
。metadata.format
現在使用Format
列舉。為了轉換成此列舉,我們已移除EXCEL_CSV
值並新增FORMAT_UNSPECIFIED
值。params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter.match
和params.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter.match
現在使用Match
列舉。params.options.pathQueryOptions.pathFilters[].pathMatchPosition
現在使用PathMatchPosition
列舉。為了轉換成此列舉,我們已新增PATH_MATCH_POSITION_UNSPECIFIED
值。schedule.frequency
現在使用Frequency
列舉。為了轉換為此列舉,我們已新增FREQUENCY_UNSPECIFIED
值。params.type
現在使用ReportType
列舉。為了轉換至此列舉,我們已進行下列變更:- 下列值已淘汰:
TYPE_ACTIVE_GRP
TYPE_AUDIENCE_PERFORMANCE
TYPE_CLIENT_SAFE
TYPE_COMSCORE_VCE
TYPE_CROSS_FEE
TYPE_CROSS_PARTNER
TYPE_CROSS_PARTNER_THIRD_PARTY_DATA_PROVIDER
TYPE_ESTIMATED_CONVERSION
TYPE_FEE
TYPE_KEYWORD
TYPE_LINEAR_TV_SEARCH_LIFT
TYPE_NIELSEN_AUDIENCE_PROFILE
TYPE_NIELSEN_DAILY_REACH_BUILD
TYPE_NIELSEN_ONLINE_GLOBAL_MARKET
TYPE_PAGE_CATEGORY
TYPE_PETRA_NIELSEN_DAILY_REACH_BUILD
TYPE_PETRA_NIELSEN_ONLINE_GLOBAL_MARKET
TYPE_PIXEL_LOAD
TYPE_THIRD_PARTY_DATA_PROVIDER
TYPE_TRUEVIEW_IAR
TYPE_VERIFICATION
TYPE_YOUTUBE_VERTICAL
- 其餘值都已更新,以更準確地反映 UI 中的相等值:
v1.1 值 對等 ReportType
值TYPE_NOT_SUPPORTED
REPORT_TYPE_UNSPECIFIED
TYPE_GENERAL
STANDARD
TYPE_INVENTORY_AVAILABILITY
INVENTORY_AVAILABILITY
TYPE_AUDIENCE_COMPOSITION
AUDIENCE_COMPOSITION
TYPE_ORDER_ID
FLOODLIGHT
TYPE_TRUEVIEW
YOUTUBE
TYPE_NIELSEN_SITE
GRP
TYPE_PETRA_NIELSEN_AUDIENCE_PROFILE
YOUTUBE_PROGRAMMATIC_GUARANTEED
TYPE_REACH_AND_FREQUENCY
REACH
TYPE_REACH_AUDIENCE
UNIQUE_REACH_AUDIENCE
TYPE_PATH
FULL_PATH
TYPE_PATH_ATTRIBUTION
PATH_ATTRIBUTION
- 欄位
metadata.dataRange
、reportDataStartTimeMs
和reportDataEndTimeMs
已替換為range
、customStartDate
和customEndDate
欄位。新的日期欄位使用Date
物件,而非從 Unix Epoch 紀元時間起算的毫秒數。這些替換欄位已移至指派給QueryMetadata
物件中dataRange
欄位的DataRange
物件。 QuerySchedule
物件中的schedule.startTimeMs
和schedule.endTimeMs
欄位已替換為startDate
和endDate
欄位。新的日期欄位使用Date
物件,而非從 Unix Epoch 紀元時間起算的毫秒數。- 移除了
metadata.running
、metadata.reportCount
、metadata.googleCloudStoragePathForLatestReport
、metadata.googleDrivePathForLatestReport
和metadata.latestReportRunTimeMs
欄位。查詢最近產生的報表相關資訊應改用queries.reports.list
方法,並搭配「key.reportId desc」的orderBy
查詢參數,確保要求會先列出最新的報表。 - 移除了
kind
、timezoneCode
、metadata.locale
、params.includeInviteData
和schedule.nextRunMinuteOfDay
欄位。 - 建立後,
queries.create
將不會再自動執行查詢,並已移除asynchronous
查詢參數。在queries.create
後呼叫queries.run
,即可產生新查詢的報表。 queries.run
方法已更新,如下:asynchronous
查詢參數已替換為synchronous
查詢參數。新的查詢參數會採用反向邏輯,如未指定,則會視為「false」。因此,queries.run
預設在 v2 中會以非同步方式產生報表,而不是同步產生,在 v1.1 中則是預設產生。- 要求主體已更新,移除
timezoneCode
欄位,並將dataRange
、reportDataStartTimeMs
、reportDataEndTimeMs
欄位替換為指派給dataRange
欄位的DataRange
物件。 - 這個方法會傳回產生的
Report
物件,而非空白回應主體。
- 已移除
queries.list
回應主體中的kind
欄位。
更新向 reports
服務發出的呼叫
- 在一般巢狀物件所代表的
Report
資源中,下列欄位已變更為使用下列物件類型: - 在一般清單物件代表的
Report
資源中,下列欄位已變更為下列新物件類型的清單: Report
資源中的以下欄位最初由字串表示,因此 v2 中的對應欄位會以新的列舉類型表示,並納入可接受的值變更:metadata.status.format
現在使用Format
列舉。為了轉換至此列舉,我們已移除EXCEL_CSV
值並新增FORMAT_UNSPECIFIED
。metadata.status.state
現在使用State
列舉。為了轉換至此列舉,已新增QUEUED
和STATE_UNSPECIFIED
值。params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter.match
和params.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter.match
現在使用Match
列舉。params.options.pathQueryOptions.pathFilters[].pathMatchPosition
現在使用PathMatchPosition
列舉。為了轉換成此列舉,我們已新增PATH_MATCH_POSITION_UNSPECIFIED
值。params.type
現在使用ReportType
列舉。為了轉換至此列舉,我們已進行許多變更,並詳見上一節中關於更新查詢服務呼叫的章節。
ReportMetadata
物件中的metadata.reportDataStartTimeMs
和metadata.reportDataEndTimeMs
欄位已替換為reportDataStartDate
和reportDataEndDate
。新欄位會使用Date
物件,而非 Unix Epoch 紀元時間 (以毫秒為單位)。ReportStatus
物件中的finishTime
欄位已取代metadata.status.finishTimeMs
。這個新的時間欄位是以 RFC3339 世界標準時間「Zulu」格式表示日期時間,而不是以 Unix Epoch 紀元時間表示的時間戳記 (以毫秒為單位)。metadata.status.failure
和params.includeInviteData
欄位已移除。- 已移除
reports.list
回應主體中的kind
欄位。
更新錯誤處理邏輯
API 中的所有錯誤訊息都已在 v2 中更新。這些新的錯誤訊息更加具體,在某些情況下,會向 API 要求中導致錯誤傳回的值提供資訊。如果現有的錯誤處理邏輯需依賴特定錯誤訊息文字,請先進行一般錯誤處理,然後再遷移至 v2。