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, bạn không cần lo lắng về thông tin chi tiết của yêu cầu cơ bản. Tuy nhiên, việc biết một chút về các thành phần này có thể hữu ích khi kiểm thử và gỡ lỗi.

API Google Ads là một API gRPC, có các mối liên kết REST. Tức 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 đế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ả việc sử dụng gRPC.

2. [Không bắt buộc] Tạo phần nội dung của 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 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 bằng chuỗi tên tài nguyên của chú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 tài nguyê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 trình bày đường dẫn của những tài nguyên đó (resource_name). Các dịch vụ khác cũng sử dụng cùng một định dạng.

ID 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à một 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 đó để tạo một mã nhận dạng tổng hợp duy nhất:

• AdGroupId/123 + ~ + AdGroupAdId/45678 = mã quảng cáo trong nhóm quảng cáo tổng hợp của 123~45678.

Tiêu đề của yêu cầu

Đâ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 xác định một tài khoản người quản lý hoạt động 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 vòng một giờ sau khi bạn lấy được. Khi mã này 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 sẽ tự động làm mới các mã thông báo đã hết hạn.

mã 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ự xác định duy nhất một nhà phát triển API Google Ads. Ví dụ về chuỗi mã thông báo của nhà phát triển: ABcdeFGH93KL-NOPQ_STUv. Mã của nhà phát triển phải được bao gồm ở 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 một 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á quan trọng: 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/v17/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 đề mặc định là khách hàng đang hoạt động.

Lưu ý: Bạn có thể truy xuất danh sách các tài khoản có thể truy cập trực tiếp bằng thông tin đăng nhập OAuth của mình bằng cách đưa ra 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 cá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 một 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 cấp quyền đọc và chỉnh sửa các thực thể của tài khoản đó để 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 mà đườ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 theo đường liên kết của bên thứ ba đến tài khoản B, thay vì mối quan hệ giữa 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 sẽ 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 (hoặc siêu dữ liệu theo sau 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.

request-id

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