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. 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 phần 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 OAuth 2.0 dưới dạng Authorization: Bearer YOUR_ACCESS_TOKEN. Mã thông báo này xác định một tài khoản người quản lý đang thay mặt cho một khách hàng hoặc một 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; khi mã này hết hạn, hãy làm mới mã truy cập để truy xuất mộ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 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. Tham khảo bài viết Các cấp truy cập trong Google Ads để biết thông tin chi tiết về cách quản lý quyền.

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 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 về mô hình truy cập OAuth.

https://googleads.googleapis.com/v25/customers/CUSTOMER_ID/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 tài khoản Đối tác sẽ thực hiện các lệnh gọi API để thực hiện hành động trên các thực thể trong tài khoản 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 tài khoản Nhà quảng cáo hoặc tài khoản người quản lý của tài khoản Nhà quảng cáo.

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

  • Authorization: Mã truy cập OAuth 2.0 cho người dùng có quyền truy cập vào Đố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 tài khoản Nhà quảng cáo có một đường liên kết trực tiếp đến sản phẩm với tài khoản Đố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 tài khoản Nhà quảng cáo.
  • Nếu tài khoản Nhà quảng cáo do một tài khoản người quản lý có mối liên kết sản phẩm với tài khoản Đối tác quản lý, 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 tài khoản Nhà quảng cáo 1111111111 có mối liên kết trực tiếp với tài khoản Đối tác 2222222222 và lệnh gọi API đang nhắm đến customers/1111111111/...:

Authorization: Bearer YOUR_ACCESS_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 tài khoản Nhà quảng cáo 1111111111 do tài khoản người quản lý 3333333333 quản lý, thì tài khoản người quản lý 3333333333 có mối liên kết với tài khoản Đối tác 2222222222 và lệnh gọi API đang nhắm đến customers/1111111111/...:

Authorization: Bearer YOUR_ACCESS_TOKEN
login-customer-id: 2222222222
linked-customer-id: 3333333333

Tiêu đề phản hồi

Các tiêu đề sau (hoặc dữ liệu meta theo sau grpc) đượ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 tài nguyên