Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

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 máy khách để 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ó 2 cách để thực hiện lệnh gọi đến API.

Ư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 máy chủ bằng HTTP/2.
Giải tuần tự hoá phản hồi thành vùng đệm giao thức.
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:

Tạo nội dung của yêu cầu dưới dạng đối tượng JSON.
Gửi đến máy chủ bằng HTTP 1.1.
Giải tuần tự hoá phản hồi dưới dạng đối tượng JSON.
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 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, 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í 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 thêm mã nhận dạng đối tượng mẹ (nhóm quảng cáo) vào mã nhận dạng đó để tạo 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 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 phải đưa mã truy cập OAuth2 vào 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ề OAuth2 để biết hướng dẫn về cách truy xuất mã truy cập. Mã truy cập có giá trị trong một giờ sau khi bạn lấy được mã đó. 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.

Nếu bạn 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 về Cấp quyền 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ự 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. Bạn nên đưa mã của nhà phát triển vào dưới 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ý. Nếu bạn không đưa login-customer-id vào khi xác thực thông qua tài khoản người quản lý, thì hệ thống sẽ trả về lỗi AuthorizationError.USER_PERMISSION_DENIED. Hãy xem bài viết Các lỗi thường gặp để biết thêm thông tin về loại lỗi này.

Thuật ngữ chính: **Khách hàng đang hoạt động** là mã khách hàng trong tải trọng yêu cầu. Ví dụ: khách hàng đang hoạt động trong yêu cầu CampaignBudgetService sau đây là 1234567890:

https://googleads.googleapis.com/v24/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 đưa tiêu đề này vào, 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 thay mặt cho 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 sản phẩm.

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

Nhà quảng cáo: Tài khoản Google Ads đang được quản lý hoặc cập nhật bằng lệnh gọi API. Mã 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 đường 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 sẽ thực hiện lệnh gọi API để thay mặt cho 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 đề của 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 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 được 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 cho biết rằng việc uỷ quyền cho yêu cầu này dựa vào đường 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ó 2 trường hợp liên kết:

Nếu Nhà quảng cáo có đường liên kết sản phẩm trực tiếp 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 tài khoản người quản lý có đường 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: Liên kết trực tiếp

Nếu Nhà quảng cáo 1111111111 có đường 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: Liên kết người quản lý

Nếu Nhà quảng cáo 1111111111 được quản lý bởi Người quản lý 3333333333, Người quản lý 3333333333 có đường 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 siêu dữ liệu theo sau) đượ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.

Siêu dữ liệu về tài nguyên