Cấu trúc lệnh gọi API

Hướng dẫn này mô tả cấu trúc chung của tất cả lệnh gọi API.

Nếu đang sử dụng thư viện ứng dụng để tương tác với API, thì bạn không cần lo lắng về thông tin chi tiết cơ bản của yêu cầu. Tuy nhiên, việc biết một chút về các thành phần này có thể giúp ích cho quá trình kiểm thử và gỡ lỗi.

API Google Ads là một API gRPC có các liên kết REST. Điều này có nghĩa là có 2 cách để thực hiện lệnh gọi đến API.

1. [Ưu tiên] 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ủ bằng HTTP/2, giải tuần tự phản hồi đến vùng đệm giao thức và diễn giải kết quả. Hầu hết tài liệu của chúng tôi đều mô tả cách sử dụng gRPC.

2. [Không bắt buộc] Tạo nội dung yêu cầu dưới dạng đối tượng JSON, gửi đế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 và diễn giải kết quả. Hãy tham khảo hướng dẫn về giao diện REST để biết thêm thông tin về cách sử dụng REST.

Lưu ý: Hướng dẫn này mô tả cấu trúc và tiêu đề truyền tải dùng chung 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 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. Hãy xem Tên tài nguyên của giao diện REST để biết cấu trúc của các giao diện đó.

Lưu ý quan trọng: Hãy xem tài liệu về tài nguyên để biết tất cả tài nguyên được hỗ trợ và cách thể hiện đường dẫn của chúng (resource_name). Định dạng tương tự được 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à duy nhất trên toàn hệ thống, 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í dụ: vì một 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 chúng tôi sẽ thêm mã đối tượng gốc (nhóm quảng cáo) của nhóm quảng cáo đó vào trước để tạo ra một mã nhận dạng tổng hợp duy nhất:

• AdGroupId/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 đề của yêu cầu

Dưới đây là các tiêu đề HTTP (hoặc siêu dữ liệu grpc) đi kèm với phần nội dung trong yêu cầu:

Ủy quyền

Bạn cần đưa mã truy cập OAuth2 vào dưới dạng Authorization: Bearer YOUR_ACCESS_TOKEN. Mã này giúp xác định tài khoản người quản lý thay mặt cho khách hàng hoặc nhà quảng cáo trực tiếp quản lý tài khoản của riêng họ. Bạn có thể xem hướng dẫn truy xuất mã truy cập trong hướng dẫn về OAuth2. Mã truy cập có hiệu lực trong một giờ sau khi bạn nhận được; khi mã hết hạn, hãy làm mới mã truy cập để truy xuất mã mới. Xin lưu ý rằng thư viện ứng dụng của chúng tôi tự động làm mới các mã thông báo đã hết hạn.

mã thông báo của nhà phát triển

Mã của nhà phát triển là một chuỗi gồm 22 ký tự nhận dạng riêng một nhà phát triển API Google Ads. Một ví dụ về chuỗi mã thông báo của nhà phát triển là ABcdeFGH93KL-NOPQ_STUv. Mã của nhà phát triển phải được đưa vào dưới dạng developer-token : ABcdeFGH93KL-NOPQ_STUv.

login-customer-id

Đây là mã khách hàng của khách hàng được uỷ quyền sử dụng trong yêu cầu, không có dấu gạch nối (-). Nếu bạn truy cập vào tài khoản khách hàng thông qua tài khoản người quản lý, thì tiêu đề này là bắt buộc và phải được đặt thành mã khách hàng của tài khoản người quản lý.

Từ khoá chính: Khách hàng hoạt động là mã khách hàng trong tải trọng yêu cầu. Ví dụ: khách hàng vận hành trong yêu cầu CampaignBudgetService sau đây là 1234567890:

https://googleads.googleapis.com/v16/customers/1234567890/campaignBudgets:mutate

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 Google Ads 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. Nếu bạn không bao gồm tiêu đề này, thì tiêu đề sẽ mặc định là khách hàng đang hoạt động.

Lưu ý: Bạn có thể truy xuất danh sách tài khoản có thể truy cập trực tiếp bằng thông tin xác thực OAuth bằng cách tạo yêu cầu CustomerService.ListAccessibleCustomers. Bạn không bắt buộc phải sử dụng login-customer-id cho loại yêu cầu này và không ảnh hưởng đến danh sách khách hàng được trả về.

mã khách hàng được liên kết

Tiêu đề này chỉ được nhà cung cấp phân tích ứng dụng bên thứ ba sử dụng khi tải lượt chuyển đổi lên tài khoản Google Ads được liên kết.

Hãy xem xét trường hợp người dùng trên tài khoản A cung cấp quyền đọc và chỉnh sửa đối với các thực thể của tài khoản B thông qua ThirdPartyAppAnalyticsLink. Sau khi liên kết, người dùng trên tài khoản B có thể thực hiện lệnh gọi API đối với tài khoản A, tuỳ theo các quyền do đường liên kết cung cấp. Trong trường hợp này, quyền gọi API cho tài khoản A được xác định bằng đường liên kết của bên thứ ba tới tài khoản B, thay vì mối quan hệ tài khoản người quản lý được dùng trong các lệnh gọi API khác.

Nhà cung cấp phân tích ứng dụng bên thứ ba thực hiện lệnh gọi API như sau:

• linked-customer-id: Tài khoản phân tích ứng dụng bên thứ ba tải dữ liệu lên (tài khoản B).
• customer-id: Tài khoản Google Ads mà bạn muốn tải dữ liệu lên (tài khoản A).
• Tiêu đề login-customer-id và Authorization: Tổ hợp các giá trị để xác định người dùng có quyền truy cập vào tài khoản B.

Tiêu đề phản hồi

Các tiêu đề sau đây (hoặc siêu dữ liệu đuôi grpc) đượ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.

request-id

request-id là một chuỗi xác định duy nhất yêu cầu này.