Chuyển từ API Trình quản lý giá thầu phiên bản 1.1 sang phiên bản 2

Vào tháng 3 năm 2022, chúng tôi đã phát hành phiên bản 2 của Bid Manager API. Do phiên bản mới này đã được phát hành, nên chúng tôi dự định sẽ sớm thông báo ngày ngừng hỗ trợ cho phiên bản 1.1. Bạn nên bắt đầu di chuyển từ phiên bản 1.1 sang phiên bản 2 càng sớm càng tốt.

Di chuyển ứng dụng

Để di chuyển từ phiên bản 1.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 các lệnh gọi API từ phiên bản 1.1 lên phiên bản 2

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

Xác định các phương pháp tương đương

Để cập nhật các lệnh gọi API từ việc sử dụng phiên bản 1.1 sang phiên bản 2, trước tiên, bạn phải xác định các phương thức tương đương của phiên bản 1.1 trong phiên bản 2.

Tên của tất cả các dịch vụ và phương thức sau đây đã thay đổi một chút giữa phiên bản 1.1 và phiên bản 2:

• Các dịch vụ Queries và Reports trong phiên bản 1.1 được gọi là queries và queries.reports trong phiên bản 2.
• Các phương thức đã được đổi tên như sau trong phiên bản 2:

  Tên phương thức v1.1	Phương thức tương đương phiên bản 2
  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

Cập nhật lên điểm cuối mới

Sau khi xác định được các phương thức tương đương, bạn cần cập nhật các yêu cầu của mình. Ví dụ: để gọi phương thức queries.getquery bằng phiên bản 1.1, bạn sẽ sử dụng URL sau:

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

Để gọi phương thức tương đương trong phiên bản 2 (còn gọi là queries.get), hãy cập nhật URL thành phương thức sau:

GET https://doubleclickbidmanager.googleapis.com/v2/queries/queryId

Nếu bạn đang dùng một thư viện ứng dụng để gửi yêu cầu đến API, hãy 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 để dùng phiên bản 2.

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

Chúng tôi sẽ giới thiệu một số thay đổi có thể gây lỗi trong phiên bản 2. Xem kỹ hướng dẫn sau đây và thực hiện những thay đổi cần thiết liên quan đến việc sử dụng Bid Manager API hiện tại của bạn.

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

• Các trường sau đây trong tài nguyên Query ban đầu được biểu thị bằng các đối tượng lồng nhau chung đã thay đổi để sử dụng các loại đối tượng sau:

  Trường v1.1	Loại đối tượng v2 tương đương
  metadata	QueryMetadata
  params	Parameters
  params.options	Options
  params.options.pathQueryOptions	Đã xoá
  params.options.pathQueryOptions.channelGrouping	Đã xoá
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter	Đã xoá
  params.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter	Đã xoá
  schedule	QuerySchedule

• Các trường sau đây trong tài nguyên Query ban đầu được biểu thị bằng các đối tượng danh sách chung đã thay đổi thành danh sách các loại đối tượng mới sau đây:

  Trường danh sách v1.1	loại đối tượng v2
  params.filters[]	FilterPair
  params.options.pathQueryOptions.channelGrouping.rules[]	Đã xoá
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[]	Đã xoá
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[]	Đã xoá
  params.options.pathQueryOptions.pathFilters[]	Đã xoá
  params.options.pathQueryOptions.pathFilters[].eventFilters[]	Đã xoá

• Các trường sau đây trong tài nguyên Query (ban đầu được biểu thị bằng các chuỗi) được biểu thị bằng các loại enum trong phiên bản 2 và bao gồm những thay đổi sau:
  • metadata.dataRange tương đương với phiên bản 2 hiện sử dụng enum Range. Khi chuyển đổi sang enum này, giá trị PREVIOUS_HALF_MONTH đã bị xoá và giá trị TYPE_NOT_SUPPORTED đã thay đổi thành RANGE_UNSPECIFIED.
  • metadata.format hiện sử dụng enum Format. Khi chuyển đổi sang enum này, giá trị EXCEL_CSV đã bị xoá và giá trị FORMAT_UNSPECIFIED đã được thêm.
  • params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter.match và params.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter.match hiện sử dụng enum Match.
  • params.options.pathQueryOptions.pathFilters[].pathMatchPosition hiện sử dụng enum PathMatchPosition. Khi chuyển đổi sang enum này, giá trị PATH_MATCH_POSITION_UNSPECIFIED đã được thêm.
  • schedule.frequency hiện sử dụng enum Frequency. Khi chuyển đổi sang enum này, giá trị FREQUENCY_UNSPECIFIED đã được thêm vào.
  • params.type hiện sử dụng enum ReportType. Khi chuyển đổi sang enum này, chúng tôi đã thực hiện những thay đổi sau:
  • Các giá trị sau đây không được dùng nữa:
    • 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
  • Tất cả các giá trị còn lại đều đã được cập nhật để phản ánh chính xác hơn các giá trị tương đương của chúng trong giao diện người dùng:

    Giá trị v1.1	Giá trị ReportType tương đương
    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

• Các trường metadata.dataRange, reportDataStartTimeMs và reportDataEndTimeMs đã được thay thế bằng các trường range, customStartDate và customEndDate. Các trường ngày mới sử dụng các đối tượng Date thay vì mili giây kể từ thời điểm bắt đầu thời gian Unix. Các trường thay thế này đã được di chuyển vào đối tượng DataRange được chỉ định cho trường dataRange trong đối tượng QueryMetadata.
• Các trường schedule.startTimeMs và schedule.endTimeMs đã được thay thế bằng các trường startDate và endDate trong đối tượng QuerySchedule. Các trường ngày mới sử dụng các đối tượng Date thay vì mili giây kể từ thời điểm bắt đầu thời gian Unix.
• Các trường metadata.running, metadata.reportCount, metadata.googleCloudStoragePathForLatestReport, metadata.googleDrivePathForLatestReport và metadata.latestReportRunTimeMs đã bị xoá. Thay vào đó, bạn nên truy xuất thông tin về các báo cáo được tạo gần đây nhất của một truy vấn bằng phương thức queries.reports.list với tham số truy vấn orderBy "key.reportId desc" để đảm bảo rằng yêu cầu liệt kê các báo cáo gần đây nhất trước.
• Các trường kind, timezoneCode, metadata.locale, params.includeInviteData và schedule.nextRunMinuteOfDay đã bị xoá.
• queries.create không còn tự động chạy các truy vấn sau khi tạo và tham số truy vấn asynchronous đã bị xoá. Gọi queries.run sau queries.create để tạo báo cáo cho các truy vấn mới.
• Phương thức queries.run đã được cập nhật theo những cách sau:
  • Tham số truy vấn asynchronous đã được thay thế bằng tham số truy vấn synchronous. Tham số truy vấn mới hoạt động theo logic đảo ngược và được coi là sai nếu không được chỉ định. Do đó, queries.run tạo báo cáo không đồng bộ theo mặc định trong phiên bản 2, thay vì đồng bộ như mặc định trong phiên bản 1.1.
  • Nội dung yêu cầu đã được cập nhật để xoá trường timezoneCode và thay thế các trường dataRange, reportDataStartTimeMs, reportDataEndTimeMs bằng một đối tượng DataRange được chỉ định cho trường dataRange.
  • Phương thức này trả về đối tượng Report kết quả thay vì một nội dung phản hồi trống.
• Trường kind trong phần nội dung phản hồi queries.list đã bị xoá.

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

• Các trường sau đây trong tài nguyên Report ban đầu do các đối tượng lồng nhau chung đại diện đã thay đổi để sử dụng các loại đối tượng sau:

  Trường v1.1	Loại đối tượng v2 tương đương
  key	ReportKey
  metadata	ReportMetadata
  metadata.status	ReportStatus
  params	Parameters
  params.options	Options
  params.options.pathQueryOptions	Đã xoá
  params.options.pathQueryOptions.channelGrouping	Đã xoá
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter	Đã xoá
  params.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter	Đã xoá

• Các trường sau đây trong tài nguyên Report ban đầu do các đối tượng danh sách chung đại diện đã thay đổi thành danh sách các loại đối tượng mới sau đây:

  Trường danh sách v1.1	loại đối tượng v2
  params.filters[]	FilterPair
  params.options.pathQueryOptions.channelGrouping.rules[]	Đã xoá
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[]	Đã xoá
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[]	Đã xoá
  params.options.pathQueryOptions.pathFilters[]	Đã xoá
  params.options.pathQueryOptions.pathFilters[].eventFilters[]	Đã xoá

• Các trường sau đây trong tài nguyên Report ban đầu được biểu thị bằng các chuỗi đã thay đổi để các trường tương đương trong phiên bản 2 được biểu thị bằng các loại enum mới và bao gồm các thay đổi đối với các giá trị có thể chấp nhận:
  • metadata.status.format hiện sử dụng enum Format. Khi chuyển đổi sang enum này, giá trị EXCEL_CSV đã bị xoá và FORMAT_UNSPECIFIED đã được thêm vào.
  • metadata.status.state hiện sử dụng enum State. Khi chuyển đổi sang enum này, các giá trị QUEUED và STATE_UNSPECIFIED đã được thêm vào.
  • params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter.match và params.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter.match hiện sử dụng enum Match.
  • params.options.pathQueryOptions.pathFilters[].pathMatchPosition hiện sử dụng enum PathMatchPosition. Khi chuyển đổi sang enum này, giá trị PATH_MATCH_POSITION_UNSPECIFIED đã được thêm.
  • params.type hiện sử dụng enum ReportType. Khi chuyển đổi sang enum này, nhiều thay đổi đã được thực hiện và được liệt kê chi tiết trong phần trước liên quan đến việc cập nhật các lệnh gọi dịch vụ truy vấn.
• Các trường metadata.reportDataStartTimeMs và metadata.reportDataEndTimeMs đã được thay thế bằng các trường reportDataStartDate và reportDataEndDate trong đối tượng ReportMetadata. Các trường mới sử dụng các đối tượng Date thay vì mili giây kể từ Epoch của Unix.
• metadata.status.finishTimeMs đã được thay thế bằng trường finishTime trong đối tượng ReportStatus. Trường thời gian mới này biểu thị ngày giờ dưới dạng dấu thời gian ở định dạng "Zulu" RFC3339 UTC thay vì tính bằng mili giây kể từ thời gian bắt đầu của hệ thống Unix.
• Đã xoá các trường metadata.status.failure và params.includeInviteData.
• Trường kind trong phần nội dung phản hồi reports.list đã bị xoá.

Cập nhật logic xử lý lỗi

Thông báo lỗi trên toàn bộ API đã được cập nhật trong phiên bản 2. Những thông báo lỗi mới này cụ thể hơn và trong một số trường hợp, cung cấp thông tin về các giá trị trong yêu cầu API đang gây ra lỗi được trả về. Nếu logic xử lý lỗi hiện tại của bạn dựa trên văn bản thông báo lỗi cụ thể, hãy khái quát hoá quy trình xử lý lỗi trước khi di chuyển sang phiên bản 2.