從 Bid Manager API 第 1.1 版遷移至第 2 版

我們在 2022 年 3 月發布了 Bid Manager API 的第 2 版。隨著新版本推出，我們預計即將在 v1.1 中淘汰。建議您盡快開始從 1.1 版遷移至 2.0 版。

遷移應用程式

從 v1.1 遷移至 v2 時，您需要更新端點網址才能呼叫 v2，並更新應用程式以反映破壞性變更。

將 API 呼叫從 1.1 版更新為 2 版

如要使用 v2 而非 v1.1，您必須將要求更新為使用新的 v2 端點。

找出對等的方法

如要將 API 呼叫從 v1.1 更新至 v2，您必須先在 v2 中找出對等的 v1.1 方法。

下列所有服務和方法的名稱在 v1.1 和 v2 之間略有不同：

v1.1 中的服務 Queries 和 Reports 在 v2 中稱為 queries 和 queries.reports。

在 v2 中，方法已重新命名：

v1.1 方法名稱	對等 v2 方法
`Queries.createquery`	`queries.create`
`Queries.deletequery`	`queries.delete`
`Queries.getquery`	`queries.get`
`Queries.listqueries`	`queries.list`
`Queries.runquery`	`queries.run`
`Reports.listreports`	`queries.reports.list`

更新至新的端點

找到對應的方法後，您必須更新要求。舉例來說，如要透過 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 資源中，下列欄位已變更為使用下列物件類型：

v1.1 欄位	對等 v2 物件類型
`metadata`	`QueryMetadata`
`params`	`Parameters`
`params.options`	`Options`
`params.options.pathQueryOptions`	`PathQueryOptions`
`params.options.pathQueryOptions.channelGrouping`	`ChannelGrouping`
`params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter`	`PathQueryOptionsFilter`
`params.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter`	`PathQueryOptionsFilter`
`schedule`	`QuerySchedule`

在原本由一般清單物件呈現的 Query 資源中，下列欄位已變更為下列新物件類型清單：

v1.1 清單欄位	v2 物件類型
`params.filters[]`	`FilterPair`
`params.options.pathQueryOptions.channelGrouping.rules[]`	`Rule`
`params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[]`	`DisjunctiveMatchStatement`
`params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[]`	`EventFilter`
`params.options.pathQueryOptions.pathFilters[]`	`PathFilter`
`params.options.pathQueryOptions.pathFilters[].eventFilters[]`	`EventFilter`

Query 資源中的下列欄位 (原本以字串表示) 在 v2 中以列舉類型表示，並納入下列變更：

metadata.dataRange 的第 2 版對等項目現在使用 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 物件。
欄位 schedule.startTimeMs 和 schedule.endTimeMs 已替換為 QuerySchedule 物件中的 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 查詢參數取代。新的查詢參數則會使用反向邏輯運作，如未指定，則會視為否。因此，queries.run 預設在 v2 中非同步產生報告，而非同步 (在 v1.1 中為預設值)。
- 要求主體已更新，移除 timezoneCode 欄位，並將 dataRange、reportDataStartTimeMs、reportDataEndTimeMs 欄位替換為指派給 dataRange 欄位的 DataRange 物件。
- 這個方法會傳回產生的 Report 物件，而不是空白回應主體。
已移除 queries.list 回應主體中的 kind 欄位。

更新對 `reports` 服務的呼叫

在原本一般巢狀物件代表的 Report 資源中，下列欄位已變更為使用以下物件類型：

v1.1 欄位	對等 v2 物件類型
`key`	`ReportKey`
`metadata`	`ReportMetadata`
`metadata.status`	`ReportStatus`
`params`	`Parameters`
`params.options`	`Options`
`params.options.pathQueryOptions`	`PathQueryOptions`
`params.options.pathQueryOptions.channelGrouping`	`ChannelGrouping`
`params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter`	`PathQueryOptionsFilter`
`params.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter`	`PathQueryOptionsFilter`

在原本由一般清單物件呈現的 Report 資源中，下列欄位已變更為下列新物件類型清單：

v1.1 清單欄位	v2 物件類型
`params.filters[]`	`FilterPair`
`params.options.pathQueryOptions.channelGrouping.rules[]`	`Rule`
`params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[]`	`DisjunctiveMatchStatement`
`params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[]`	`EventFilter`
`params.options.pathQueryOptions.pathFilters[]`	`PathFilter`
`params.options.pathQueryOptions.pathFilters[].eventFilters[]`	`EventFilter`

Report 資源中原本由字串表示的欄位已變更，因此第 2 版中的對等欄位以新的列舉類型表示，且包含可接受的值變更：
- 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 列舉。為了轉換成這個列舉，我們已進行多項變更，並將在前一節關於更新查詢服務呼叫的詳細說明。
欄位 metadata.reportDataStartTimeMs 和 metadata.reportDataEndTimeMs 已由 ReportMetadata 物件中的 reportDataStartDate 和 reportDataEndDate 欄位取代。自 Unix Epoch 以來，新欄位使用的是 Date 物件，而非毫秒。
metadata.status.finishTimeMs 已由 ReportStatus 物件的 finishTime 欄位取代。這個新時間欄位以 RFC3339 UTC &Zulu" 格式表示時間戳記，而非自 Unix Epoch 起算的毫秒數。
已移除 metadata.status.failure 和 params.includeInviteData 欄位。
已移除 reports.list 回應主體中的 kind 欄位。

更新錯誤處理邏輯

第 2 版 API 的錯誤訊息已更新。這些新的錯誤訊息會更明確，在某些情況下可以提供 API 要求中導致錯誤傳回的值的資訊。如果現有的錯誤處理邏輯依賴特定的錯誤訊息文字，請先簡化錯誤處理程序，然後再遷移至 v2。