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 phải lo lắng về thông tin chi tiết về yêu cầu cơ bản. Tuy nhiên, việc biết một chút về các loại lỗi này có thể hữu ích 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. Điều này có nghĩa là có hai cách để thực hiện lệnh gọi đến API.

  1. [Ưu tiên] Tạo nội dung của yêu cầu dưới dạng vùng đệm giao thức, gửi nội dung đó đến máy chủ bằng HTTP/2, chuyển đổi tuần tự phản hồi thành 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ộ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ả. 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 giao diện 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 Tên tài nguyên của giao diện REST để biết cấu trúc của các tên đó.

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 phải là mã nhận dạ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à mã duy nhất trên toàn cầu, nên chúng tôi sẽ thêm mã nhận dạng đối tượng mẹ (nhóm quảng cáo) vào trước để tạo một mã nhận dạng tổng hợp duy nhất:

  • 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 123~45678.

Tiêu đề 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 thêm mã thông báo truy cập OAuth2 ở 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 chính 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 lấy mã đó; khi mã truy cập hết hạn, hãy làm mới mã truy cập để truy xuất mã truy cập 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ự giúp 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 dành cho 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 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ý.

https://googleads.googleapis.com/v19/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 thêm tiêu đề này, tiêu đề mặc định sẽ là khách hàng vận hành.

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 đã 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 đó cho 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ỳ 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 đến tài khoản A được xác định bằng đường liên kết của bên thứ ba đến tài khoản B, thay vì mối quan hệ tài khoản người quản lý được sử 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à dữ liệu được tải lên (tài khoản A).
  • Tiêu đề login-customer-id và Authorization: Một 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 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.

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