從 Display & Video 360 API 第 4 版遷移至第 5 版

上次更新時間：2026 年 10 月 22 日

警告： 第 5 版為公開測試版。第 5 版在 Beta 版階段可能會有破壞性變更，這些變更會列在 Display & Video 360 API 版本資訊中。我們會視需要更新這份文件，反映 Beta 版的最新情況。

遷移應用程式

從第 4 版遷移至第 5 版時，您必須更新端點網址以呼叫第 5 版、更新應用程式以因應破壞性變更，並查看任何可能有助於整合的新功能。

將 API 呼叫從第 4 版更新至第 5 版

如要改用第 5 版，請更新要求，改用新的第 5 版端點。

舉例來說，如要使用 v4 呼叫 advertisers.get 方法，請使用下列網址：

GET https://displayvideo.googleapis.com/v4/advertisers/advertiserId

如果是第 5 版，請將網址更新為：

GET https://displayvideo.googleapis.com/v5/advertisers/advertiserId

如果您使用用戶端程式庫向 API 提出要求，請使用最新版本的用戶端程式庫，並更新設定以使用第 5 版。

進行必要變更

Display & Video 360 API 第 5 版導入多項破壞性變更。請詳閱下列操作說明，並根據您目前使用 Display & Video 360 API 的情況，進行必要變更。

如需 Display & Video 360 API 第 4 版和第 5 版之間的完整差異清單，請參閱版本資訊。

更新廣告空間來源擷取和指定目標，改用新的 ID 和類型

Display & Video 360 API v5 變更了廣告空間來源交易和競價套裝方案的擷取及指定方式。

在 v4 中，使用 inventorySources 服務擷取的 InventorySource 資源代表廣告空間來源交易和競價套裝方案。交易和競價套裝方案都是使用 TARGETING_TYPE_INVENTORY_SOURCE 指定。

在第 5 版中，廣告空間來源交易和競價套裝方案會分開處理：

• 廣告空間來源交易是使用 TARGETING_TYPE_INVENTORY_SOURCE_DEAL 指定，透過 advertisers.inventorySources 和 partners.inventorySources 服務擷取，並使用 AssignedTargetingOption 欄位 inventorySourceDetails 指定。
• 競價套裝方案會使用 TARGETING_TYPE_AUCTION_PACKAGE 指定目標、使用 targetingTypes.targetingOptions 服務擷取，並使用 auctionPackageDetails 的 AssignedTargetingOption 欄位指定目標。

這項更新會變更現有交易和競價套裝方案使用的 ID，因此遷移後，您無法使用任何先前快取的 InventorySource 資源 ID。

除了上述異動，第 5 版也移除了建立、更新及編輯廣告空間來源存取子的功能。

更新需求開發和 YouTube 資源的指定目標對象邏輯

Display & Video 360 API v5 更新了需求開發和 YouTube 資源的指定目標對象邏輯，為每個指定目標對象名單使用個別指派選項。

在 v4 中，所有指定目標對象都是使用 TARGETING_TYPE_AUDIENCE_GROUP 管理。

在第 5 版中，需求開發和 YouTube 廣告群組的指定目標對象，會根據目標對象類型，使用下列其中一種指定類型和 AssignedTargetingOption 資源欄位進行管理：

• TARGETING_TYPE_COMBINED_AUDIENCE使用 combinedAudienceDetails
• TARGETING_TYPE_CUSTOM_LIST使用 customListDetails
• TARGETING_TYPE_FIRST_PARTY_AND_PARTNER_AUDIENCE使用 firstPartyAndPartnerAudienceDetails
• TARGETING_TYPE_GOOGLE_AUDIENCE使用 googleAudienceDetails
• TARGETING_TYPE_LOOKALIKE_AUDIENCE使用 lookalikeAudienceDetails

委刊項會繼續使用單一 TARGETING_TYPE_AUDIENCE_GROUP AssignedTargetingOption，管理所有類型的指定目標對象。

升級至 Data Manager API，管理目標顧客比對目標對象

Display & Video 360 API v5 移除下列方法，因此無法再建立及管理目標顧客比對目標對象的成員：

• firstPartyAndPartnerAudiences.create
• firstPartyAndPartnerAudiences.editCustomerMatchMembers
• firstPartyAndPartnerAudiences.patch

如要繼續管理目標顧客比對目標對象，請升級工作流程，改用 Data Manager API。

新增擷取數位戶外廣告訂單的支援

Display & Video 360 API v5 新增擷取數位戶外廣告訂單的功能。

如果廣告主使用數位戶外廣告，請升級所有呼叫 advertisers.insertionOrders.list 的整合，以便納入 insertionOrderType 欄位值為 OUT_OF_HOME 的 InsertionOrder 資源。

在 v5 中，數位戶外廣告訂單下的委刊項仍可像在 v4 中一樣擷取。

將 Adloox 參照更新為 Peer39

在第 5 版中，參照 Display & Video 360 第三方品牌合適度與 Adloox (也稱為 Scope3) 整合的欄位和列舉值，已更新為 Peer39：

• ThirdPartyVerifierAssignedTargetingOptionDetails 欄位 adloox 已由 peer39 取代。
• PartnerCostType 列舉值 PARTNER_COST_TYPE_ADLOOX 和 PARTNER_COST_TYPE_ADLOOX_PREBID 已替換為 PARTNER_COST_TYPE_PEER39 和 PARTNER_COST_TYPE_PEER39_PREBID。

更新 YouTube 委刊項、廣告群組和廣告的欄位

在第 5 版中，LineItem、AdGroup 和 AdGroupAd 資源中的多個欄位已移除或更新。請更新資源擷取邏輯，以因應這些異動。

在 LineItem 資源中：

• YoutubeAndPartnersSettings 欄位relatedVideoIds已由 relatedVideos 取代。

在 LineItem 和 AdGroup 資源中：

• TargetingExpansionConfig 欄位 audienceExpansionSeedListExcluded 和 audienceExpansionLevel 已移除。

在 AdGroupAd 資源中：

• 已新增 containsSyntheticMedia 欄位。
• AudioAd、CommonInStreamAttribute 和 VideoPerformanceAd 物件中的 trackingUrl 欄位已拆分為 trackingUrl 和 userSpecifiedTrackingUrl 兩個欄位，用來區分追蹤網址和使用者指定的追蹤網址。

移除提及已淘汰列舉值的內容

在第 5 版中，先前淘汰的列舉值已完全移除。在 v4 中，如果在 API 要求中使用這些值，會導致錯誤，但這項變更會從 v5 用戶端程式庫中移除所有相關參照。如果程式碼參照這些已淘汰的值，升級至第 5 版時可能會發生錯誤。

受影響值的列舉類型包括 ContentRatingTier、GoogleAudienceType、SdfVersion 和 SensitiveCategory。如需所有已移除列舉值的完整清單，請參閱版本資訊。

查看新功能

除了破壞性變更外，第 5 版也推出下列新功能：

• 在廣告主層級，完整管理指定類型 TARGETING_TYPE_YOUTUBE_VIDEO 和 TARGETING_TYPE_YOUTUBE_CHANNEL 的 YouTube 影片和頻道排除指定目標。在第 4 版中，這項指定目標為唯讀。
• 可建立數位戶外廣告 InsertionOrder 資源。
• 新增 AdGroup 欄位 adSource 和 creativeAssignments，以及 AdGroupAd 欄位 parentCreativeId，支援使用指派廣告素材產生廣告的廣告群組。
• 可建立及擷取 LookalikeAudience 資源。
• AdGroupAd 資源中的新 containsSyntheticMedia 欄位。