API Google Ads có cơ chế báo cáo chỉ số và truy xuất thuộc tính hợp nhất cho phép bạn tạo truy vấn bằng Ngôn ngữ truy vấn Google Ads. Điều này tạo điều kiện cho các truy vấn phức tạp có thể trả về một lượng lớn dữ liệu về các tài khoản Google Ads riêng lẻ.
Bạn có thể tạo truy vấn bằng một trong hai phương thức Search hoặc SearchStream.
Cả hai phương thức đều hỗ trợ các truy vấn giống nhau và trả về kết quả tương đương. Phương thức Search trả về dữ liệu ở các kích thước trang có thể tuỳ chỉnh, cho phép bạn lặp lại một tập hợp kết quả bằng tính năng phân trang. Điều này có thể có lợi thế trong điều kiện băng thông thấp hoặc điều kiện mạng không đáng tin cậy, chẳng hạn như để phân đoạn một kết quả lớn được đặt thành các phản hồi nhỏ hơn để có thể tìm nạp lại nếu mất kết nối. Mặt khác, phương thức SearchStream truyền trực tuyến toàn bộ kết quả được đặt lại trong một phản hồi duy nhất, giúp truy xuất dữ liệu hàng loạt hiệu quả hơn.
Cả Search và SearchStream đều sử dụng cùng một URL cơ sở:
https://googleads.googleapis.com/v16/customers/CUSTOMER_ID/googleAds
Phương thức tìm kiếm dựa trên trang sẽ lấy một tham số pageSize (không bắt buộc) để giới hạn số lượng kết quả được trả về trong một phản hồi API.
POST /v16/customers/CUSTOMER_ID/googleAds:search HTTP/1.1
Host: googleads.googleapis.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN
{
"pageSize": 10000,
"query": "SELECT ad_group_criterion.keyword.text, ad_group_criterion.status FROM ad_group_criterion WHERE ad_group_criterion.type = 'KEYWORD' AND ad_group_criterion.status = 'ENABLED'"
}
Nếu có nhiều hàng trong kết quả hơn pageSize, thì hệ thống sẽ trả về nextPageToken trong phản hồi:
{
"results": [
// ...
// ...
// ...
],
"nextPageToken": "CPii5aS87vfFTBAKGJvk36qpLiIWUW5SZk8xa1JPaXJVdXdIR05JUUpxZyoCVjMwADjUBkD___________8B",
"fieldMask": "adGroupCriterion.keyword.text,adGroupCriterion.status"
}
Việc lặp lại cùng một truy vấn đã thêm pageToken cùng với giá trị ở trên sẽ tìm nạp trang kết quả tiếp theo:
POST /v16/customers/CUSTOMER_ID/googleAds:search HTTP/1.1
Host: googleads.googleapis.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN
{
"pageSize": 10000,
"query": "SELECT ad_group_criterion.keyword.text, ad_group_criterion.status FROM ad_group_criterion WHERE ad_group_criterion.type = 'KEYWORD' AND ad_group_criterion.status = 'ENABLED'",
"pageToken": "CPii5aS87vfFTBAKGJvk36qpLiIWUW5SZk8xa1JPaXJVdXdIR05JUUpxZyoCVjMwADjUBkD___________8B"
}
Để sử dụng phương thức SearchStream mà sẽ trả về tất cả kết quả trong một phản hồi được truyền trực tuyến, chỉ cần thay đổi phương thức dịch vụ trong URL thành searchStream
(pageSize và pageToken không bắt buộc theo SearchStream):
POST /v16/customers/CUSTOMER_ID/googleAds:searchStream HTTP/1.1
Host: googleads.googleapis.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN
{
"query": "SELECT ad_group_criterion.keyword.text, ad_group_criterion.status FROM ad_group_criterion WHERE ad_group_criterion.type = 'KEYWORD' AND ad_group_criterion.status = 'ENABLED'"
}