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. Hãy xem phần 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 chi tiết về yêu cầu cơ bản có thể hữu ích khi kiểm thử và gỡ lỗi.
Search Ads 360 Reporting API là một API gRPC có các liên kết REST. Điều này có nghĩa là bạn có thể thực hiện lệnh gọi đến API theo hai cách khác nhau:
- Phương thức ưu tiên
- Sử dụng thư viện ứng dụng:
- Tạo 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ủ bằng HTTP/2.
- Giải mã phản hồi thành 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.
- Tạo lại phản hồi dưới dạng đối tượng JSON.
- Diễn giải kết quả.
Hãy xem 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 được xác định bằng chuỗi tên tài nguyên. Các chuỗi này cũng đóng vai trò là URL khi sử dụng giao diện REST.
Xem phần Tham chiếu > REST để biết thêm thông tin về các tài nguyên được hỗ trợ và cách trình bày đường dẫn của các tài nguyên đó. Định dạng tương tự được dùng cho các dịch vụ khác.
Mã nhận dạng tổng hợp
Nếu mã nhận dạng của một đối tượng không duy nhất trên toàn cầu, thì mã nhận dạng tổng hợp cho đối tượng đó sẽ được tạo bằng cách thêm mã nhận dạng mẹ và dấu ngã (~) vào đầu.
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 gốc (nhóm quảng cáo) được thêm vào trước mã đó dẫn đến một mã nhận dạng kết hợp duy nhất.
Ví dụ: AdGroupId của 123 + ~ + AdGroupAdId của 45678
= mã quảng cáo của nhóm quảng cáo tổng hợp là 123~45678.
Tiêu đề yêu cầu
Bạn phải đưa các tiêu đề HTTP (hoặc siêu dữ liệu gRPC) trong các phần sau vào phần nội dung của yêu cầu.
Ủy quyền
Bạn cần đưa 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 một tài khoản người quản lý thay mặt cho một khách hàng hoặc một nhà quảng cáo trực tiếp quản lý tài khoản người quản lý phụ hoặc tài khoản khách hàng của chính họ. 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 người quản lý phụ hoặc tài khoản khách hàng. Bạn không bắt buộc phải làm vậ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 bắt buộc, nhưng bạn nên luôn chỉ định login-customer-id cho những người dùng đã xác thực có quyền truy cập vào nhiều tài khoản. Điều này giúp tránh sự mơ hồ và ngăn việc vô tình đặt ngữ cảnh thành 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 nối (-), 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 sau gRPC) được trả về cùng với nội dung phản hồi. Bạn nên ghi lại 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 duy nhất yêu cầu.