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 mối 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, hãy gửi đối tượng này đến máy chủ bằng cách sử dụng HTTP 1.1, giả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 Kiến trúc chuyển trạng thái đại diện (REST) Tên tài nguyên của giao diện cho cấu trúc.
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 grpc siêu dữ liệu) đi kèm 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. 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.
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 của nhà phát triển:
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 đặ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 của Google Ads sau khi đăng nhập hoặc nhấp vào ảnh hồ sơ của bạn ở trên cùng
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ì 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.
mã yêu cầu
request-id là một chuỗi xác định duy nhất yêu cầu này.