Các lệnh gọi đến API Báo cáo Search Ads 360 thường được thực hiện thông qua thư viện ứng dụng. Xem Giải thích về thư viện ứng dụng để biết thêm thông tin. Tuy nhiên, kiến thức về cấu trúc của thông tin cơ bản về yêu cầu có thể hữu ích khi kiểm thử và gỡ lỗi.
API Báo cáo Search Ads 360 là một API gRPC có các liên kết REST. Tức là bạn có thể thực hiện lệnh gọi đến API theo 2 cách:
- Phương thức ưu tiên
- Sử dụng thư viện ứng dụng:
- Tạo phần nội dung của yêu cầu dưới dạng vùng đệm giao thức.
- Gửi yêu cầu đến máy chủ qua HTTP/2.
- Giải tuần tự phản hồi tới vùng đệm giao thức.
- Diễn giải kết quả.
- Phương thức thay thế không bắt buộc
- Sử dụng REST:
- Tạo nội dung yêu cầu dưới dạng đối tượng JSON.
- Gửi yêu cầu đến máy chủ bằng HTTP 1.1.
- Giải tuần tự phản hồi dưới dạng đối tượng JSON.
- Diễn giải kết quả.
Xem bài viết về API Google Cloud để biết thêm thông tin.
Các phần sau đây áp dụng cho cả giao thức gRPC và REST.
Tên tài nguyên
Hầu hết các đối tượng trong API đều được xác định theo chuỗi tên tài nguyên của các đối tượng đó. Các chuỗi này cũng đóng vai trò là URL khi sử dụng giao diện REST.
Vui lòng xem mục Tham khảo > REST để biết thêm thông tin về các tài nguyên được hỗ trợ và cách biểu thị đường dẫn của các tài nguyên đó. Định dạng này cũng được sử dụng cho các dịch vụ khác.
Mã tổng hợp
Nếu mã nhận dạng của một đối tượng không phải là mã nhận dạng duy nhất trên toàn cầu, thì một mã nhận dạng tổng hợp cho đối tượng đó sẽ được tạo bằng cách thêm vào trước mã nhận dạng mẹ và một dấu ngã (~).
Ví dụ: vì mã quảng cáo của nhóm quảng cáo không phải là duy nhất trên toàn hệ thống, nên mã đối tượng (nhóm quảng cáo) gốc được thêm vào trước mã này, tạo thành một mã nhận dạng tổng hợp duy nhất.
Ví dụ: AdGroupId/123 + ~ + AdGroupAdId/45678
= mã quảng cáo tổng hợp của nhóm quảng cáo 123~45678.
Tiêu đề của yêu cầu
Bạn nên đưa tiêu đề HTTP (hoặc siêu dữ liệu gRPC) trong những phần sau vào phần nội dung của yêu cầu.
Ủy quyền
Bạn cần phải cung cấp mã truy cập OAuth2 vào biểu mẫu:
Authorization: Bearer [OAUTH_2.0_ACCESS_TOKEN]
Mã thông báo phải xác định tài khoản người quản lý đại diện cho khách hàng hoặc nhà quảng cáo trực tiếp quản lý tài khoản khách hàng hoặc tài khoản người quản lý phụ của riêng mình. Hãy xem bài viết Giới thiệu về tài khoản người quản lý Search Ads 360 và Xác thực để tìm hiểu thêm.
Tiêu đề mã khách hàng đăng nhập
Bạn phải có tiêu đề login-customer-id khi sử dụng tài khoản người quản lý để truy cập vào tài khoản khách hàng hoặc tài khoản người quản lý phụ. Bạn không bắt buộc phải thực hiện việc này khi truy cập trực tiếp vào tài khoản người quản lý phụ hoặc tài khoản khách hàng. Mặc dù không thực sự cần thiết, nhưng bạn nên luôn chỉ định login-customer-id cho những người dùng đã xác thực và có quyền truy cập vào nhiều tài khoản. Điều này giúp tránh tình trạng không rõ ràng và tránh việc vô tình đặt ngữ cảnh cho tài khoản không chính xác.
Yêu cầu phải bao gồm mã khách hàng của người dùng được uỷ quyền, không có dấu gạch ngang (-), ví dụ:
https://searchads360.googleapis.com/VERSION_NUMBER/customers/CUSTOMER_ID/campaignBudgets
Việc đặt login-customer-id tương đương với việc chọn một tài khoản trong
giao diện người dùng Search Ads 360 sau khi đăng nhập hoặc nhấp vào ảnh hồ sơ của bạn ở
trên cùng bên phải.
Tiêu đề phản hồi
Các tiêu đề sau (hoặc siêu dữ liệu theo dõi gRPC) sẽ được trả về cùng với nội dung phản hồi. Bạn nên ghi nhật ký các giá trị này cho mục đích gỡ lỗi.
Mã yêu cầu
Tiêu đề request-id là một chuỗi xác định yêu cầu duy nhất.