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 sử dụng thư viện ứng dụng để tương tác với API, bạn không cần phải lo lắng về thông tin chi tiết của yêu cầu cơ bản này. Tuy nhiên, việc biết một chút về các mã 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 liên kết REST. Điều này có nghĩa là bạn có hai cách để gọi API.

  1. [Ư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, gửi đến máy chủ bằng cách sử dụng HTTP/2, huỷ tuần tự phản hồi cho vùng đệm giao thức và diễn giải kết quả. Hầu hết các 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ội dung đó đến máy chủ bằng HTTP 1.1, huỷ 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 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. Xem Tên tài nguyên của giao diện REST để biết cấu trúc của chúng.

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 cầu, 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ã 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 mã đối tượng gốc (nhóm quảng cáo) của mã đó vào mã này để tạo một mã tổng hợp duy nhất:

  • AdGroupId trong số 123 + ~ + AdGroupAdId của 45678 = ID quảng cáo tổng hợp của nhóm quảng cáo là 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 cần bao gồm mã 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ý đang 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ã thông báo truy cập trong hướng dẫn về OAuth2. Mã truy cập có hiệu lực trong 1 giờ sau khi bạn lấy. Mã này sẽ hết hạn khi bạn 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ã thông báo của nhà phát triển

Mã của người 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. Một chuỗi mã của nhà phát triển mẫu là ABcdeFGH93KL-NOPQ_STUv. Mã của nhà phát triển phải được đưa vào dạng developer-token : ABcdeFGH93KL-NOPQ_STUv.

ID khách hàng đăng nhập

Đây là mã khách hàng của khách hàng được ủy quyền để sử dụng trong yêu cầu, không có dấu gạch nối (-). Nếu quyền truy cập vào tài khoản khách hàng của bạn là 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ý.

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

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

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

Hãy cân nhắc 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ể trong 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 đến tài khoản A, tùy thuộc vào 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 bằng mối liên kết bên thứ ba với tài khoản B, thay vì mối quan hệ giữa tài khoản người quản lý và tài khoản đượ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: Sự kết hợp của 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 siêu dữ liệu) được trả về cùng 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.

id yêu cầu

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