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 sẽ 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ề chúng có thể giúp ích cho bạn khi kiểm thử và gỡ lỗi.

API Google Ads là một API gRPC, với các liên kết REST. Tức là có 2 cách thực hiện lệnh gọi đến API.

1. [Được ưu tiên] Tạo phần nội dung của yêu cầu dưới dạng bộ đệm giao thức, hãy gửi đến máy chủ bằng HTTP/2, giải tuần tự phản hồi cho một 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 nội dung yêu cầu dưới dạng đối tượng JSON, gửi nội dung đó đến máy chủ bằng HTTP 1.1, chuyển đổi tuần tự phản hồi dưới dạng đối tượng JSON và diễn giải kết quả. 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 Kiến trúc chuyển trạng thái đại diện (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 Các chuỗi cũng đóng vai trò là URL khi sử dụng giao diện REST. Xem Tên tài nguyên của giao diện REST để biết cấu trúc của các tên đó.

Lưu ý quan trọng: Hãy xem tài liệu tham khảo, cho tất cả các tài nguyên được hỗ trợ và cách biểu diễn đường dẫn của chúng (resource_name). Các dịch vụ khác 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 đó được tạo bằng cách đặt tiền tố ID 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 cầu, nên chúng tôi sẽ thêm ID đối tượng gốc (nhóm quảng cáo) vào đối tượng gốc để tạo một ID tổng hợp duy nhất:

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

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

Đây là các tiêu đề HTTP (hoặc thuộc tính siêu dữ liệu RPC) đi kèm với phần nội dung trong yêu cầu:

Ủy quyền

Bạn cần cung cấp mã truy cập OAuth2 ở dạng Authorization: Bearer YOUR_ACCESS_TOKEN xác định tài khoản người quản lý hành động trực tiếp thay mặt cho khách hàng hoặc nhà quảng cáo quản lý tài khoản của chính mình. Hướng dẫn truy xuất mã truy cập trong hướng dẫn về OAuth2. Một mã truy cập có hiệu lực trong vòng một giờ sau khi bạn nhận được; khi nào hết hạn, hãy làm mới mã truy cập để truy xuất mộ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 mã thông báo đã hết hạn.

developer-token

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 mã Nhà phát triển API Google Ads. Ví dụ về chuỗi mã thông báo dành cho nhà phát triển là ABcdeFGH93KL-NOPQ_STUv. Mã của nhà phát triển phải được đưa vào biểu mẫu 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 có thể 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 vận hành 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 tại sau Yêu cầu CampaignBudgetService là 1234567890:

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

Việc thiết lập 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, nó sẽ mặc định là hoạt động khách hà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 bằng cách cấp CustomerService.ListAccessibleCustomers yêu cầu. login-customer-id là không bắt buộc đối với 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ề.

linked-customer-id

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 tài khoản.

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 cho các thực thể để 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 quyền được cung cấp qua đường liên kết. Trong trường hợp này, lệnh gọi API quyền đối với tài khoản A được xác định theo mối liên kết của bên thứ ba với tài khoản B, thay vì là 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 lên dữ liệu (tài khoản B).
• customer-id: Tài khoản Google Ads mà dữ liệu được tải 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) được trả về cùng với nội dung phản hồi. Bạn nên ghi nhật ký 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.