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

我們在 2022 年 3 月推出了 Bid Manager API 第 2 版。由於新版已發布，我們計畫在近期宣布 v1.1 版的淘汰日期。建議您盡快開始從 1.1 版遷移至第 2 版。

遷移應用程式

如要從 v1.1 遷移至 v2，您必須更新端點網址來呼叫 v2，並更新應用程式以因應重大變更。

將 API 呼叫從 v1.1 更新至 v2

如要使用第 2 版而非第 1.1 版，請更新要求，改用新的第 2 版端點。

找出等效方法

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

在 v1.1 和 v2 之間，所有服務和方法名稱都略有變更，如下所示：

• v1.1 中的服務 Queries 和 Reports 在 v2 中稱為 queries 和 queries.reports。
• 在第 2 版中，方法已重新命名如下：

  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	已移除
  params.options.pathQueryOptions.channelGrouping	已移除
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter	已移除
  params.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter	已移除
  schedule	QuerySchedule

• Query 資源中原本以一般清單物件表示的下列欄位，已變更為下列新物件類型的清單：

  v1.1 清單欄位	v2 物件類型
  params.filters[]	FilterPair
  params.options.pathQueryOptions.channelGrouping.rules[]	已移除
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[]	已移除
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[]	已移除
  params.options.pathQueryOptions.pathFilters[]	已移除
  params.options.pathQueryOptions.pathFilters[].eventFilters[]	已移除

• Query 資源中的下列欄位原本是以字串表示，在第 2 版中則是以列舉類型表示，包括下列變更：
  • 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 中的等值：

    1.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 紀元以來的毫秒數。這些替代欄位已移至 QueryMetadata 物件中，指派給 dataRange 欄位的 DataRange 物件。
• schedule.startTimeMs 和 schedule.endTimeMs 欄位已由 QuerySchedule 物件中的 startDate 和 endDate 欄位取代。新的日期欄位會使用 Date 物件，而非 Unix 紀元以來的毫秒數。
• 已移除 metadata.running、metadata.reportCount、metadata.googleCloudStoragePathForLatestReport、metadata.googleDrivePathForLatestReport 和 metadata.latestReportRunTimeMs 欄位。如要取得查詢的最新生成報表相關資訊，請改用 queries.reports.list 方法，並將 orderBy 查詢參數設為「key.reportId desc」，確保要求會先列出最新報表。
• 已移除 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 資源中原本以一般巢狀物件表示的下列欄位，現在已改用下列物件型別：

  v1.1 欄位	對應的 v2 物件類型
  key	ReportKey
  metadata	ReportMetadata
  metadata.status	ReportStatus
  params	Parameters
  params.options	Options
  params.options.pathQueryOptions	已移除
  params.options.pathQueryOptions.channelGrouping	已移除
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter	已移除
  params.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter	已移除

• Report 資源中原本以一般清單物件表示的下列欄位，已變更為下列新物件類型的清單：

  v1.1 清單欄位	v2 物件類型
  params.filters[]	FilterPair
  params.options.pathQueryOptions.channelGrouping.rules[]	已移除
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[]	已移除
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[]	已移除
  params.options.pathQueryOptions.pathFilters[]	已移除
  params.options.pathQueryOptions.pathFilters[].eventFilters[]	已移除

• 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 列舉。轉換為這個列舉時，我們進行了許多變更，詳情請參閱上一節有關更新查詢服務呼叫的內容。
• metadata.reportDataStartTimeMs 和 metadata.reportDataEndTimeMs 欄位已由 ReportMetadata 物件中的 reportDataStartDate 和 reportDataEndDate 欄位取代。新欄位會使用 Date 物件，而非 Unix 紀元以來的毫秒數。
• metadata.status.finishTimeMs 已由 ReportStatus 物件中的 finishTime 欄位取代。這個新時間欄位會以 RFC3339 世界標準時間「Zulu」格式的時間戳記表示日期時間，而非以自 Unix 紀元開始至今經過的毫秒數表示。
• 已移除 metadata.status.failure 和 params.includeInviteData 欄位。
• reports.list 回應主體中的 kind 欄位已移除。

更新錯誤處理邏輯

第 2 版的 API 錯誤訊息已更新。這些新錯誤訊息更具體，有時還會提供 API 要求中導致傳回錯誤的值相關資訊。如果現有的錯誤處理邏輯依賴特定錯誤訊息文字，請先將錯誤處理邏輯一般化，再遷移至 v2。