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 để gọi 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 yêu cầu đó đế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 tên tài nguyên.

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 kết 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 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/123 + ~ + AdGroupAdId/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ã 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 thay mặt cho một 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ã 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 các mã thông báo đã hết hạn.

Nếu gặp lỗi uỷ quyền, hãy đảm bảo rằng bạn đang sử dụng thông tin đăng nhập chính xác và có đủ quyền. Lỗi USER_PERMISSION_DENIED cho biết rằng người dùng được xác thực có thể không có quyền truy cập vào tài khoản khách hàng được chỉ định trong yêu cầu. Hãy tham khảo bài viết Các cấp độ truy cập vào Google Ads để biết thông tin chi tiết về cách quản lý quyề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 Google Ads API. Ví dụ về chuỗi mã của nhà phát triển là ABcdeFGH93KL-NOPQ_STUv. Mã thông báo của 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ý. Nếu bạn không thêm login-customer-id khi xác thực thông qua tài khoản người quản lý, thì sẽ xảy ra lỗi AuthorizationError.USER_PERMISSION_DENIED. Hãy xem phần Các lỗi thường gặp để biết thêm thông tin về loại lỗi này. Để biết thông tin giải thích chi tiết về cách giải quyết quyền truy cập vào tài khoản, hãy tham khảo hướng dẫn Mô hình truy cập OAuth.

https://googleads.googleapis.com/v25/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 là bắt buộc và được các đối tác (chẳng hạn như nhà cung cấp dịch vụ phân tích ứng dụng bên thứ ba hoặc đối tác dữ liệu) sử dụng khi thực hiện hành động trên một tài khoản Google Ads được liên kết. Tiêu đề này phải chỉ định Mã khách hàng của tài khoản Google Ads có đường liên kết đến sản phẩm.

Hãy xem xét trường hợp mà một đối tác cần thực hiện các lệnh gọi API đến một tài khoản Google Ads dựa trên một mối liên kết sản phẩm.

  • Nhà quảng cáo: Tài khoản Google Ads đang được lệnh gọi API quản lý hoặc cập nhật. Mã nhận dạng của tài khoản nhà quảng cáo được chỉ định trong yêu cầu. Trong REST, đây là tham số đường dẫn customerId (ví dụ: customers/1111111111/...) và trong gRPC, đây là trường customer_id trong yêu cầu.
  • Đối tác: Tài khoản đối tác (ví dụ: nhà cung cấp dịch vụ phân tích ứng dụng bên thứ ba hoặc đối tác dữ liệu).
  • Tài khoản được liên kết: Tài khoản Google Ads đã thiết lập mối liên kết sản phẩm với Đối tác, cấp cho Đối tác quyền truy cập vào Nhà quảng cáo.

Người dùng có quyền truy cập vào Đối tác thực hiện các lệnh gọi API để hành động trên các thực thể trong Nhà quảng cáo (ví dụ: tải lượt chuyển đổi lên hoặc quản lý danh sách người dùng). Tài khoản được liên kết có thể là chính Nhà quảng cáo hoặc tài khoản người quản lý của Nhà quảng cáo.

Bạn phải đặt tiêu đề yêu cầu như sau:

  • Authorization: Mã thông báo OAuth2 cho người dùng có quyền truy cập vào Đối tác.
  • developer-token: Mã của nhà phát triển cho ứng dụng API, thường được liên kết với Đối tác.
  • login-customer-id: Mã khách hàng của đối tác. Người dùng đã xác thực phải có quyền truy cập vào tài khoản này.
  • linked-customer-id: Mã khách hàng của Tài khoản được liên kết. Tiêu đề này báo hiệu rằng việc uỷ quyền cho yêu cầu này dựa vào mối liên kết sản phẩm của Tài khoản được liên kết với Đối tác.

Có hai trường hợp liên kết:

  • Nếu Nhà quảng cáo có đường liên kết trực tiếp đến sản phẩm với Đối tác, thì Tài khoản được liên kết là Nhà quảng cáo và bạn phải đặt linked-customer-id thành mã khách hàng của Nhà quảng cáo.
  • Nếu Nhà quảng cáo được quản lý bởi một tài khoản người quản lý có mối liên kết sản phẩm với Đối tác, thì Tài khoản được liên kết là tài khoản người quản lý và bạn phải đặt linked-customer-id thành mã khách hàng của người quản lý.

Ví dụ 1: Đường liên kết trực tiếp

Nếu Nhà quảng cáo 1111111111 có mối liên kết trực tiếp với Đối tác 2222222222 và lệnh gọi API đang nhắm đến customers/1111111111/...:

Authorization: Bearer YOUR_ACCESS_TOKEN
developer-token: YOUR_DEVELOPER_TOKEN
login-customer-id: 2222222222
linked-customer-id: 1111111111

Ví dụ 2: Đường liên kết của người quản lý

Nếu Nhà quảng cáo 1111111111 do Người quản lý 3333333333 quản lý, Người quản lý 3333333333 có mối liên kết với Đối tác 2222222222 và lệnh gọi API đang nhắm đến customers/1111111111/...:

Authorization: Bearer YOUR_ACCESS_TOKEN
developer-token: YOUR_DEVELOPER_TOKEN
login-customer-id: 2222222222
linked-customer-id: 3333333333

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 tài nguyên