Chuyển từ phiên bản 1 sang phiên bản 2

Lần cập nhật gần đây nhất: 6/12/2022

Di chuyển ứng dụng

Để di chuyển từ phiên bản 1 sang phiên bản 2, bạn cần cập nhật URL điểm cuối để gọi phiên bản 2 và cập nhật ứng dụng để tính đến các thay đổi có thể gây lỗi.

Cập nhật lệnh gọi API từ phiên bản 1 lên phiên bản 2

Để sử dụng phiên bản 2 thay vì phiên bản 1, bạn cần cập nhật các yêu cầu để sử dụng các điểm cuối phiên bản 2 mới.

Ví dụ: để gọi phương thức advertisers.get bằng v1, bạn sẽ sử dụng URL sau:

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

Đối với phiên bản 2, hãy cập nhật URL thành như sau:

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

Nếu bạn đang sử dụng thư viện ứng dụng để gửi yêu cầu đến API, hãy sử dụng phiên bản mới nhất của thư viện ứng dụng và cập nhật cấu hình để sử dụng phiên bản 2.

Thực hiện các thay đổi bắt buộc

Chúng tôi sẽ ra mắt một số thay đổi có thể gây lỗi trong phiên bản 2. Xem lại các hướng dẫn sau và thực hiện các thay đổi bắt buộc liên quan đến cách bạn hiện đang sử dụng API Display & Video 360.

Cập nhật lệnh gọi đến các phương thức nhắm mục tiêu

• Một số loại tiêu chí nhắm mục tiêu hiện được chỉ định bằng cách sử dụng giá trị enum thay vì mã tuỳ chọn nhắm mục tiêu. Ví dụ: các thiết bị máy tính bảng hiện được nhắm mục tiêu trực tiếp bằng enum DEVICE_TYPE_TABLET DeviceType, thay vì mã tuỳ chọn nhắm mục tiêu từ dịch vụ targetingTypes.targetingOptions. Các phiên bản chuỗi của các enum này được biểu thị trong trường assignedTargetingOptionIdAlias mới trong các tài nguyên AssignedTargetingOption này và có thể được sử dụng khi truy xuất hoặc xoá tiêu chí nhắm mục tiêu hiện có. Giá trị assignedTargetingOptionId của các tài nguyên AssignedTargetingOption này không thay đổi.

  Cập nhật các lệnh gọi quản lý các loại tiêu chí nhắm mục tiêu sau để sử dụng các giá trị enum:

  • TARGETING_TYPE_AGE_RANGE
  • TARGETING_TYPE_CONTENT_INSTREAM_POSITION
  • TARGETING_TYPE_CONTENT_OUTSTREAM_POSITION
  • TARGETING_TYPE_DEVICE_TYPE
  • TARGETING_TYPE_DIGITAL_CONTENT_LABEL_EXCLUSION
  • TARGETING_TYPE_ENVIRONMENT
  • TARGETING_TYPE_EXCHANGE
  • TARGETING_TYPE_GENDER
  • TARGETING_TYPE_HOUSEHOLD_INCOME
  • TARGETING_TYPE_NATIVE_CONTENT_POSITION
  • TARGETING_TYPE_OMID
  • TARGETING_TYPE_PARENTAL_STATUS
  • TARGETING_TYPE_SENSITIVE_CATEGORY_EXCLUSION
  • TARGETING_TYPE_VIDEO_PLAYER_SIZE
  • TARGETING_TYPE_VIEWABILITY

• Phương thức advertisers.lineItems.bulkEditLineItemAssignedTargetingOptions đã được thay thế bằng phương thức advertisers.lineItems.bulkEditAssignedTargetingOptions.

• Phương thức advertisers.lineItems.bulkListLineItemAssignedTargetingOptions đã được thay thế bằng phương thức advertisers.lineItems.bulkListAssignedTargetingOptions.

• Cập nhật các lệnh gọi quản lý TARGETING_TYPE_PROXIMITY_LOCATION_LIST để sử dụng kích thước bán kính và đơn vị khoảng cách đã đặt thay vì giá trị enum ProximityRadiusRange.

• Các phương pháp nhắm mục tiêu truy xuất hoặc chỉnh sửa các tuỳ chọn nhắm mục tiêu trên nhiều loại mục tiêu trong một tài nguyên mẹ đã được đổi tên.

  Cập nhật lệnh gọi đến các phương thức sau để sử dụng tên mới:

  • advertisers.bulkEditAdvertiserAssignedTargetingOptions thành advertisers.editAssignedTargetingOptions
  • advertisers.bulkListAdvertiserAssignedTargetingOptions thành advertisers.listAssignedTargetingOptions
  • advertisers.campaigns.bulkListCampaignAssignedTargetingOptions thành advertisers.campaigns.listAssignedTargetingOptions
  • advertisers.insertionOrders.bulkListInsertionOrderAssignedTargetingOptions thành advertisers.insertionOrders.listAssignedTargetingOptions
  • partners.bulkEditPartnerAssignedTargetingOptions thành partners.editAssignedTargetingOptions

Cập nhật lệnh gọi đến dịch vụ advertisers.lineItems

• Trường inventorySourceIds đã bị xoá. Quản lý việc chỉ định nguồn khoảng không quảng cáo bằng cách sử dụng tài nguyên AssignedTargetingOption của TARGETING_TYPE_INVENTORY_SOURCE.

• Các giá trị enum LineItemWarningMessage sau đây đã ngừng hoạt động trong phiên bản 2 và sẽ không còn xuất hiện trong LineItem.warningMessages:

  • NO_POSITIVE_AUDIENCE_LIST_TARGETED
  • APP_INSTALL_NO_CONVERSION_PIXEL
  • TARGETING_REVOKED_OR_CLOSED_USER_LIST
  • APP_INSTALL_NO_OPTIMAL_BIDDING_STRATEGY
  • CREATIVE_SIZE_NOT_IN_USE_FOR_TARGETED_DEALS
  • NO_CREATIVE_FOR_TARGETED_DEALS
  • TARGETING_DEPRECATED_GEO_TARGET

• Trường triggerId đã bị xoá khỏi đối tượng LineItemFlight và giá trị LINE_ITEM_FLIGHT_DATE_TYPE_TRIGGER đã bị xoá khỏi loại enum LineItemFlightDateType. Phiên bản 2 không hỗ trợ việc đặt mục hàng để chi tiêu dựa trên việc kích hoạt trình kích hoạt thủ công.

Cập nhật lệnh gọi đến dịch vụ customBiddingAlgorithms

Các trường customBiddingAlgorithmState và modelReadiness đã được thay thế bằng trường modelDetails . Trường này cung cấp trạng thái sẵn sàng và tạm ngưng của mô hình thuật toán hiện có cho từng nhà quảng cáo có quyền truy cập thông qua danh sách đối tượng CustomBiddingModelDetails.

Các nội dung thay đổi khác

Ngoài các thay đổi có thể gây lỗi nêu trên, phiên bản 2 cũng ra mắt các tính năng mới.

Bạn có thể xem các tính năng được thêm vào phiên bản 2 sau lần phát hành đầu tiên trong ghi chú phát hành của chúng tôi.

Quyền chỉ đọc đối với các mục riêng trên YouTube

Trong phiên bản 2, bạn có thể truy xuất các mục hàng trên YouTube và chế độ cài đặt nhắm mục tiêu của các mục hàng đó tương ứng bằng các dịch vụ advertisers.lineItems và advertisers.lineItems.targetingTypes.assignedTargetingOptions. API này cung cấp quyền chỉ có thể đọc, nghĩa là mọi yêu cầu ghi được thực hiện đối với các mục hàng này sẽ trả về lỗi. Mục hàng trên YouTube sẽ có một trong các giá trị LineItemType sau:

• LINE_ITEM_TYPE_YOUTUBE_AND_PARTNERS_ACTION
• LINE_ITEM_TYPE_YOUTUBE_AND_PARTNERS_AUDIO
• LINE_ITEM_TYPE_YOUTUBE_AND_PARTNERS_NON_SKIPPABLE
• LINE_ITEM_TYPE_YOUTUBE_AND_PARTNERS_NON_SKIPPABLE_OVER_THE_TOP
• LINE_ITEM_TYPE_YOUTUBE_AND_PARTNERS_REACH
• LINE_ITEM_TYPE_YOUTUBE_AND_PARTNERS_REACH_OVER_THE_TOP
• LINE_ITEM_TYPE_YOUTUBE_AND_PARTNERS_SIMPLE
• LINE_ITEM_TYPE_YOUTUBE_AND_PARTNERS_SIMPLE_OVER_THE_TOP
• LINE_ITEM_TYPE_YOUTUBE_AND_PARTNERS_VIDEO_SEQUENCE

Các phương thức mới giúp nâng cao hiệu suất

Trong phiên bản 2, dịch vụ advertisers.lineItems cung cấp các phương thức mới để sử dụng thay vì yêu cầu theo lô nhằm cải thiện hiệu suất và giảm mức sử dụng hạn mức:

• Bạn có thể sử dụng advertisers.lineItems.bulkUpdate để đặt cùng một giá trị trường cho nhiều mục hàng. Hiện tại, chúng tôi chỉ hỗ trợ nội dung cập nhật cho trường entityStatus.
• Bạn có thể sử dụng advertisers.lineItems.bulkEditAssignedTargetingOptions để thêm hoặc xoá cùng một lựa chọn nhắm mục tiêu được chỉ định trên nhiều mục dòng.
• Bạn có thể sử dụng advertisers.lineItems.bulkListAssignedTargetingOptions để liệt kê các lựa chọn nhắm mục tiêu được chỉ định trên nhiều mục hàng.
• Bạn có thể sử dụng advertisers.lineItems.duplicate để tạo bản sao của một mục hàng hiện có trong cùng một đơn đặt hàng quảng cáo, sao chép tất cả cấu hình và chế độ cài đặt tiêu chí nhắm mục tiêu.

Quyền ghi một phần đối với tiêu chí nhắm mục tiêu theo đơn đặt hàng quảng cáo

Trong phiên bản 2, bạn có thể chỉnh sửa một nhóm nhỏ các chế độ cài đặt nhắm mục tiêu cho tài nguyên InsertionOrder bằng cách sử dụng các phương thức create và delete mới trong dịch vụ advertisers.insertionOrders.targetingTypes.assignedTargetingOptions. Bạn có thể quản lý đầy đủ các loại tiêu chí nhắm mục tiêu sau ở cấp đơn đặt hàng quảng cáo:

• TARGETING_TYPE_AGE_RANGE
• TARGETING_TYPE_BROWSER
• TARGETING_TYPE_CATEGORY
• TARGETING_TYPE_CHANNEL
• TARGETING_TYPE_DEVICE_MAKE_MODEL
• TARGETING_TYPE_DIGITAL_CONTENT_LABEL_EXCLUSION
• TARGETING_TYPE_ENVIRONMENT
• TARGETING_TYPE_GENDER
• TARGETING_TYPE_KEYWORD
• TARGETING_TYPE_LANGUAGE
• TARGETING_TYPE_NEGATIVE_KEYWORD_LIST
• TARGETING_TYPE_OPERATING_SYSTEM
• TARGETING_TYPE_PARENTAL_STATUS
• TARGETING_TYPE_SENSITIVE_CATEGORY_EXCLUSION
• TARGETING_TYPE_VIEWABILITY