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ả các lệnh gọi API.

Nếu đang dùng một thư viện ứng dụng để tương tác với API, bạn sẽ không cần biết thông tin chi tiết về yêu cầu cơ bản. Tuy nhiên, một số kiến thức về cấu trúc lệnh gọi API có thể hữu ích khi 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ó hai cách để đưa ra lệnh gọi đến API.

Ưu tiên:

  1. Tạo nội dung yêu cầu dưới dạng vùng đệm giao thức.

  2. Gửi mã này đến máy chủ bằng HTTP/2.

  3. Giải tuần tự phản hồi thành vùng đệm giao thức.

  4. 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.

Không bắt buộc:

  1. Tạo nội dung yêu cầu dưới dạng đối tượng JSON.

  2. Gửi mã thông báo đó đến máy chủ bằng HTTP 1.1.

  3. Giải tuần tự hoá phản hồi dưới dạng một đối tượng JSON.

  4. 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.

Tên tài nguyên

Hầu hết các đối tượng trong API đều đượ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. Hãy xem Tên tài nguyên của giao diện REST để biết cấu trúc của chúng.

Mã nhận dạng kết 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 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 trước.

Ví dụ: vì mã quảng cáo của nhóm quảng cáo không phải là mã riêng biệt trên toàn cầu, nên chúng tôi sẽ thêm mã đối tượng mẹ (nhóm quảng cáo) vào mã đó để tạo mã kết hợp riêng biệt:

  • AdGroupId của 123 + ~ + AdGroupAdId của 45678 = mã 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 nội dung trong yêu cầu:

Ủy quyền

Bạn phải thêm mã thông báo truy cập OAuth2 dưới dạng Authorization: Bearer YOUR_ACCESS_TOKEN để 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 về cách 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 mã này; khi mã truy cập 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 máy khách của chúng tôi sẽ tự động làm mới các 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ự, dùng để 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 là ABcdeFGH93KL-NOPQ_STUv. Mã thông báo nhà phát triển phải có 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 ngang (-). 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ý.

https://googleads.googleapis.com/v20/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 thêm tiêu đề này, thì tiêu đề này sẽ mặc định là khách hàng đang hoạt động.

linked-customer-id

Tiêu đề này chỉ được [nhà cung cấp dịch vụ 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 cấp quyền đọc và chỉnh sửa cho 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 các lệnh gọi API đối với tài khoản A, tuỳ thuộc vào các quyền do mối liên kết cung cấp. Trong trường hợp này, quyền gọi API đối với tài khoản A được xác định bằng mối liên kết với bên thứ ba đối với tài khoản B, chứ không phải 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 dịch vụ 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à 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 grpc trailing-metadata) đượ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 để gỡ lỗi.

request-id

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

Trước
Siêu dữ liệu về tài nguyên