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 API Trình quản lý giá thầu. Do phát hành phiên bản mới này, chúng tôi dự định sẽ sớm thông báo ngày ngừng cung cấp phiên bản 1.1. T4 bạn nên bắt đầu quá trình 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

Việc di chuyển từ phiên bản 1.1 sang phiên bản 2 yêu cầu bạn phải cập nhật URL điểm cuối để gọi phiên bản 2, và cập nhật ứng dụng của bạn cho phù hợp với 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.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 của mình để sử dụng phiên bản mới 2 điểm cuối.

Xác định các phương thức tương đương

Để cập nhật các lệnh gọi API của bạn 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 v1.1 trong v2.

Tên sau đây của tất cả dịch vụ và phương thức có thay đổi đôi chút giữa v1.1 và v2:

• Các dịch vụ Queries và Reports trong phiên bản 1.1 đã biết dưới dạng 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 v2 tương đương
  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 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 gọi là queries.get), hãy cập nhật phương thức URL đến:

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

Nếu bạn đang sử dụng thư viện ứng dụng để gửi yêu cầu tới API, hãy sử dụng phiên bản gần đây của thư viện ứng dụng và cập nhật cấu hình của bạn để 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ẽ giới thiệu một số thay đổi có thể gây lỗi trong phiên bản 2. Xem lại những nội dung sau và thực hiện những thay đổi cần thiết phù hợp với cách bạn đang sử dụng API Trình quản lý giá thầu.

Cập nhật cuộc gọi thành dịch vụ queries

• Các trường sau trong tài nguyên Query ban đầu được biểu thị bằng giá trị chung các đối tượng lồng nhau đã 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	PathQueryOptions
  params.options.pathQueryOptions.channelGrouping	ChannelGrouping
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter	PathQueryOptionsFilter
  params.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter	PathQueryOptionsFilter
  schedule	QuerySchedule

• Các trường sau trong tài nguyên Query ban đầu được biểu thị bằng giá trị chung đối tượng danh sách đã thay đổi thành danh sách gồm 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[]	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

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

    Các giá trị phiên bản 1.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

• 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 Date thay vì mili giây kể từ Unix Epoch. Các trường thay thế này đã được di chuyển vào đối tượng DataRange được gán cho 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 inch đối tượng QuerySchedule. Các trường ngày mới sử dụng Date thay vì mili giây kể từ Unix Epoch.
• Trường metadata.running, metadata.reportCount, metadata.googleCloudStoragePathForLatestReport, metadata.googleDrivePathForLatestReport và metadata.latestReportRunTimeMs đã bị xoá. Thông tin liên quan đến những báo cáo được tạo gần đây nhất của một truy vấn phải thay vào đó, hãy truy xuất phương thức queries.reports.list với phương thức Tham số truy vấn orderBy của “key.reportId Description” thành đả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 tiên.
• 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 truy vấn sau khi tạo và tham số truy vấn asynchronous đã bị xoá. Gọi điện queries.run sau queries.create để tạo báo cáo cho 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 Tham số truy vấn synchronous. Tham số truy vấn mới hoạt động với logic nghịch đảo và được coi là sai nếu không được chỉ định. Đã cho điều này, queries.run sẽ tạo các báo cáo không đồng bộ theo mặc định trong v2 trái ngược với đồng bộ, đó là mặc định trong v1.1.
  • Nội dung yêu cầu đã được cập nhật để xoá Trường timezoneCode và thay thế dataRange, reportDataStartTimeMs, reportDataEndTimeMs trường có DataRange được chỉ định cho dataRange.
  • Phương thức này trả về đối tượng Report thu được thay vì một đối tượng nội dung phản hồi trống.
• Trường kind trong nội dung phản hồi queries.list đã bị xóa.

Cập nhật cuộc gọi thành dịch vụ reports

• Các trường sau đây trong tài nguyên Report 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
  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

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

  trường danh sách v1.1	loại đối tượng 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

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

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

Thông báo lỗi trên API đã được cập nhật trong phiên bản 2. Đây là các thông báo lỗi mới 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 gây ra lỗi được trả về. Nếu lỗi hiện tại của bạn logic xử lý dựa trên văn bản thông báo lỗi cụ thể, khái quát hoá lỗi của bạn trước khi chuyển sang phiên bản 2.