Trang này được dịch bởi Cloud Translation API.

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 việc 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 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 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 để tính đến những 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 v2 thay vì v1.1, bạn cần cập nhật các yêu cầu để sử dụng các điểm cuối v2 mới.

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

Để 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, trước tiên, bạn phải xác định các phương thức tương đương với phiên bản 1.1 trong phiên bản 2.

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

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 phiên bản 1.1	Phương thức tương đương 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`

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 gọi là queries.get, hãy cập nhật URL thành như sau:

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 đến API, hãy sử dụng phiên bản thư viện ứng dụng mới nhất 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 xét các hướng dẫn sau đây và thực hiện các thay đổi cần thiết có liên quan đến hoạt động sử dụng API Trình quản lý giá thầu hiện tại của bạn.

Cập nhật cuộc gọi lê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 đã thay đổi để sử dụng các kiểu đối tượng sau:

Trường phiên bản 1.1	Loại đối tượng tương đương 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`

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

Trường danh sách phiên bản 1.1	loại đối tượng phiên bản 2
`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 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 v2 và có những thay đổi sau:

Phiên bản v2 tương đương với metadata.dataRange 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 đã được 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 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.
schedule.frequency hiện sử dụng enum Frequency. Để chuyển đổi sang enum này, giá trị FREQUENCY_UNSPECIFIED đã được thêm.
params.type hiện sử dụng enum ReportType. Để 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òn đượ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 tốt hơn các giá trị tương đương của chúng trong giao diện người dùng:

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`

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 đối tượng Date thay vì mili giây kể từ Unix. Các trường thay thế này đã được chuyển vào đối tượng DataRange được gán 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 đối tượng Date thay vì mili giây kể từ 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 liên quan đến 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 là “key.reportId description” nhằm đảm bảo rằng yêu cầu này sẽ 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 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 với logic nghịch đảo và được coi là sai nếu không được chỉ định. Do đó, theo mặc định, queries.run sẽ tạo báo cáo không đồng bộ trong phiên bản 2 thay vì tạo báo cáo đồng bộ (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 đối tượng DataRange được chỉ định cho trường dataRange.
- Phương thức này trả về đối tượng Report thay vì một nội dung phản hồi trống.
Trường kind trong nội dung phản hồi queries.list đã bị xoá.

Cập nhật cuộc gọi lên dịch vụ `reports`

Các trường sau 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 phiên bản 1.1	Loại đối tượng tương đương 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`

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

Trường danh sách phiên bản 1.1	loại đối tượng phiên bản 2
`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 chuỗi đã thay đổi. Do đó, các trường tương đương trong v2 đượ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 chấp nhận:
- metadata.status.format hiện sử dụng enum Format. Để 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. Để chuyển đổi sang enum này, các giá trị QUEUED và STATE_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.
- params.type hiện sử dụng enum ReportType. Để 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 về 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 các trường reportDataStartDate và reportDataEndDate trong đối tượng ReportMetadata. Các trường mới này sử dụng đối tượng Date thay vì mili giây kể từ thời điểm 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ừ Unix Epoch.
Các trường metadata.status.failure và params.includeInviteData đã bị xoá.
Trường kind trong 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 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 gây ra lỗi được trả về. Nếu logic xử lý lỗi hiện tại của bạn phụ thuộc vào văn bản thông báo lỗi cụ thể, hãy khái quát hoá việc xử lý lỗi trước khi chuyển sang phiên bản 2.