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

我們在 2022 年 3 月推出了第 2 版的 Bid Manager API。由於 時，我們計劃宣布 1.1 版即將停用，三 建議您盡快從 1.1 版遷移至 v2。

遷移應用程式

如要從 v1.1 遷移至 v2，您必須更新端點網址，才能呼叫 v2。 更新應用程式，以利處理破壞性變更。

將 API 呼叫從 1.1 版更新至 v2

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

辨別對等的方法

為了將 API 呼叫從使用 1.1 版更新至 v2，您必須先指定 第 1.1 版中等效的 v1.1 方法

下列所有服務和方法的名稱都略有不同 1.1 版和 v2 版：

• 第 1.1 版中的服務 Queries 和 Reports 已已知 在第 2 版中，如同 queries 和 queries.reports。
• 方法在 v2 中已重新命名，如下所示：

  1.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

更新至新端點

找出對等的方法後，您必須更新要求。適用對象 舉例來說，如要透過 1.1 版呼叫 queries.getquery 方法，應使用 下列網址：

https://www.googleapis.com/doubleclickbidmanager/v1.1/query/queryId

如要呼叫第 2 版中的對等方法 (稱為 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 資源中的下列欄位原本代表一般 list 物件已變更為以下新物件類型的清單：

  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 中以列舉類型表示，並包含以下內容： 變更：
  • v2 的對應項目 (metadata.dataRange) 現在使用 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
  • 其餘的值均已更新，以更準確地反映 使用者介面中的對等值：

    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 而非毫秒時間這些替換欄位 已移至指派給DataRange 「dataRange」欄位 QueryMetadata 物件。
• 欄位 schedule.startTimeMs 和 「schedule.endTimeMs」已替換為欄位 startDate 和 endDate 英吋 QuerySchedule 物件。新日期欄位使用 Date 而非毫秒時間
• 欄位 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	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 資源中原本代表的欄位 字串經過變更，因此 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已由 欄位 reportDataStartDate 和 reportDataEndDate ReportMetadata 物件。新欄位會使用 Date 物件，而非毫秒 (自 Unix Epoch 以來的毫秒數)。
• metadata.status.finishTimeMs已由 顯示的 finishTime 欄位 ReportStatus 物件。這個新的時間欄位代表 日期時間是 RFC3339 UTC「Zulu」中的時間戳記而不是使用 幾毫秒。
• metadata.status.failure 和 已移除 params.includeInviteData 個欄位。
• reports.list 回應主體中的 kind 欄位 已移除

更新錯誤處理邏輯

API 中的錯誤訊息已在 v2 中更新。這些新的錯誤訊息 可提供更精確的資訊，並在某些情況下 導致系統傳回錯誤的 API 要求。如果現有的錯誤 處理邏輯需要特定的錯誤訊息文字，並將錯誤一般化 再遷移至 v2