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 lo lắng về thông tin chi tiết của yêu cầu cơ bản. Tuy nhiên, Việc biết một chút về chúng có thể giúp ích cho bạn 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. Tức là có 2 cách thực hiện lệnh gọi đến API.
[Được ư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, hãy gửi đến máy chủ bằng HTTP/2, giải tuần tự phản hồi cho một 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ả việc sử dụng gRPC.
[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ả. 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 Kiến trúc chuyển trạng thái đại 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ủa chúng. Các Các chuỗi 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 đó.
ID 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 hệ thống thì mã nhận dạng tổng hợp cho đối tượng đó được tạo bằng cách đặt tiền tố ID mẹ và dấu ngã (~).
Ví dụ: vì một 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 ID đối tượng gốc (nhóm quảng cáo) vào đối tượng gốc để tạo một ID tổng hợp duy nhất:
AdGroupIdtrong số123+~+AdGroupAdIdcủa45678= quảng cáo tổng hợp mã quảng cáo cho nhóm là123~45678.
Tiêu đề của 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 cung cấp mã truy cập OAuth2 ở dạng
Authorization: Bearer YOUR_ACCESS_TOKEN xác định
tài khoản người quản lý hành động trực tiếp thay mặt cho khách hàng hoặc nhà quảng cáo
quản lý tài khoản của chính mình. Hướng dẫn truy xuất mã truy cập
trong hướng dẫn về OAuth2. Một
mã truy cập có hiệu lực trong vòng một giờ sau khi bạn nhận được; khi nào
hết hạn, hãy làm mới mã truy cập để truy xuất mộ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 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ự xác định duy nhất một mã
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ã của nhà phát triển phải được đưa vào
biểu mẫu 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 có thể 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/v17/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 bao gồm tiêu đề này, nó sẽ mặc định là hoạt động
khách hàng.
linked-customer-id
Tiêu đề này chỉ được nhà cung cấp 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 được liên kết tài khoản.
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ể để 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ỳ theo quyền được cung cấp qua đường liên kết. Trong trường hợp này, lệnh gọi API
quyền đối với tài khoản A được xác định theo mối liên kết của bên thứ ba với tài khoản B,
thay vì là mối quan hệ tài khoản người quản lý được 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 lên dữ liệu (tài khoảnB).customer-id: Tài khoản Google Ads mà dữ liệu được tải lên (tài khoảnA).- Tiêu đề
login-customer-idvàAuthorization: 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ảnB.
Tiêu đề phản hồi
Các tiêu đề sau (hoặc siêu dữ liệu theo sau grpc) được trả về cùng với nội dung phản hồi. Bạn nên ghi nhật ký 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.