API Google Ads có một cơ chế hợp nhất để truy xuất thuộc tính và báo cáo chỉ số. Cơ chế này cho phép bạn tạo các truy vấn bằng cách sử dụng Ngôn ngữ truy vấn Google Ads. Điều này cho phép các truy vấn phức tạp có thể trả về số lượng lớn dữ liệu về từng tài khoản Google Ads.
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 trong các trang có kích thước cố định gồm 10.000 hàng, cho phép bạn lặp lại một tập kết quả bằng cách sử dụng tính năng phân trang. Điều này có thể mang lại lợi thế trong điều kiện mạng có băng thông thấp hoặc không đáng tin cậy, chẳng hạn như phân đoạn một tập hợp kết quả lớn thành các phản hồi nhỏ hơn có thể được 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 toàn bộ tập kết quả trở lại trong một phản hồi duy nhất, có thể hiệu quả hơn cho việc truy xuất dữ liệu hàng loạt.
Cả Search và SearchStream đều sử dụng cùng một URL cơ sở:
https://googleads.googleapis.com/v20/customers/CUSTOMER_ID/googleAds
POST /v20/customers/CUSTOMER_ID/googleAds:search 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'" }
Nếu có hơn 10.000 hàng trong kết quả,thì nextPageToken sẽ được trả về 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 với pageToken được thêm vào các giá trị từ yêu cầu trước sẽ tìm nạp trang kết quả tiếp theo:
POST /v20/customers/CUSTOMER_ID/googleAds:search 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'", "pageToken": "CPii5aS87vfFTBAKGJvk36qpLiIWUW5SZk8xa1JPaXJVdXdIR05JUUpxZyoCVjMwADjUBkD___________8B" }
Để sử dụng phương thức SearchStream (trả về tất cả kết quả trong một phản hồi được truyền trực tuyến duy nhất), hãy thay đổi phương thức dịch vụ trong URL thành searchStream (pageToken không bắt buộc đối với SearchStream):
POST /v20/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'" }