Truy xuất đối tượng

Mục tiêu: Tìm hiểu cách truy xuất đối tượng và số liệu thống kê về hiệu suất bằng cách sử dụng GoogleAdsService. Để biết các khái niệm về báo cáo, hãy xem hướng dẫn báo cáo.

GoogleAdsService là dịch vụ báo cáo và truy xuất đối tượng hợp nhất của Google Ads API. Dịch vụ này có các phương thức:

• Truy xuất các thuộc tính cụ thể của đối tượng.
• Truy xuất chỉ số hiệu suất cho các đối tượng dựa trên phạm vi ngày.
• Sắp xếp các đối tượng dựa trên thuộc tính của chúng.
• Sử dụng các điều kiện để cho biết đối tượng nào bạn muốn được trả về trong phản hồi.
• Giới hạn số lượng đối tượng được trả về.

GoogleAdsService có thể trả về kết quả theo hai cách:

• GoogleAdsService.SearchStream trả về tất cả các hàng trong một phản hồi truyền trực tuyến duy nhất, hiệu quả hơn cho các tập kết quả lớn (lớn hơn 10.000 hàng). Bạn nên làm việc này nếu ứng dụng của bạn tải toàn bộ tập kết quả xuống hoặc xử lý các hàng dưới dạng luồng.
• GoogleAdsService.Search chia nhỏ các phản hồi lớn thành các trang kết quả dễ quản lý. Điều này rất hữu ích nếu ứng dụng tương tác của bạn hiển thị một trang kết quả tại một thời điểm.

Tìm hiểu thêm về phân trang so với truyền trực tuyến.

Tạo yêu cầu

GoogleAdsService.SearchStream yêu cầu SearchGoogleAdsStreamRequest, còn GoogleAdsService.Search yêu cầu SearchGoogleAdsRequest. Cả hai loại yêu cầu đều bao gồm:

• customer_id
• Một query Ngôn ngữ truy vấn Google Ads cho biết tài nguyên cần truy vấn, các thuộc tính, phân đoạn và chỉ số cần truy xuất, cũng như các điều kiện cần sử dụng để hạn chế đối tượng được trả về

Tuỳ thuộc vào phương thức, yêu cầu cũng hỗ trợ các trường dành riêng cho phương thức:

• SearchGoogleAdsStreamRequest (chỉ SearchStream):
  • summary_row_setting không bắt buộc để yêu cầu một hàng tóm tắt chứa các chỉ số tổng hợp
• SearchGoogleAdsRequest (chỉ Search):
  • page_token không bắt buộc để truy xuất lô kết quả tiếp theo khi sử dụng tính năng phân trang (page_size được cố định ở mức 10.000 hàng; việc đặt page_size trong yêu cầu sẽ gửi lỗi RequestError.PAGE_SIZE_NOT_SUPPORTED)
  • Thông báo search_settings không bắt buộc để định cấu hình return_summary_row, return_total_results_count và omit_results
  • Một boolean validate_only không bắt buộc để xác thực truy vấn mà không cần thực thi truy vấn đó

Để biết thêm thông tin về Ngôn ngữ truy vấn Google Ads, hãy xem hướng dẫn về Ngôn ngữ truy vấn Google Ads.

Xử lý phản hồi

GoogleAdsService trả về danh sách các đối tượng GoogleAdsRow (bên trong các lô SearchGoogleAdsStreamResponse được truyền trực tuyến hoặc trong SearchGoogleAdsResponse được phân trang).

Mỗi GoogleAdsRow đại diện cho một đối tượng được trả về bằng một truy vấn và bao gồm một tập hợp các thuộc tính được điền sẵn dựa trên các trường được yêu cầu trong mệnh đề SELECT. Các thuộc tính không có trong mệnh đề SELECT sẽ không được điền sẵn trên các đối tượng GoogleAdsRow trong phản hồi.

Ví dụ: mặc dù ad_group_criterion có thuộc tính status, nhưng trường status của thuộc tính ad_group_criterion của hàng không được điền sẵn trong phản hồi cho một truy vấn mà mệnh đề SELECT không bao gồm ad_group_criterion.status. Tương tự, thuộc tính campaign của hàng sẽ không được điền sẵn nếu mệnh đề SELECT không bao gồm bất kỳ trường nào trong tài nguyên campaign.

Mỗi GoogleAdsRow có thể có các thuộc tính và chỉ số khác với một hàng khác trong cùng một tập kết quả; vì vậy, các hàng nên được xem là đối tượng thay vì các hàng cố định của bảng.

Loại enum UNKNOWN và UNSPECIFIED

Các tài nguyên được trả về bằng giá trị enum UNKNOWN không được hỗ trợ đầy đủ trong phiên bản API đó, trong khi UNSPECIFIED cho biết rằng trường enum chưa được đặt hoặc không được yêu cầu trong mệnh đề SELECT. Tài nguyên có giá trị enum UNKNOWN có thể đã được tạo thông qua các giao diện khác, chẳng hạn như giao diện người dùng Google Ads. Bạn có thể chọn các chỉ số khi tài nguyên có loại là UNKNOWN, nhưng bạn không thể thay đổi tài nguyên thông qua API. Ví dụ: một loại chiến dịch hoặc loại quảng cáo có trong giao diện người dùng nhưng không được hỗ trợ trong phiên bản API mà bạn đang truy vấn.

Dưới đây là một số điều bạn nên cân nhắc:

• Tài nguyên có loại UNKNOWN có thể được hỗ trợ trong phiên bản API mới hơn hoặc giữ nguyên trạng thái UNKNOWN vô thời hạn.
• Các đối tượng mới có loại UNKNOWN có thể xuất hiện bất cứ lúc nào. Các đối tượng này có khả năng tương thích ngược vì giá trị enum UNKNOWN có trong mọi enum trong API. Tài nguyên được trả về cùng với UNKNOWN để bạn có thể xem chính xác các chỉ số hiệu suất tổng thể của tài khoản.
• Tài nguyên UNKNOWN có thể có các chỉ số chi tiết đính kèm mà bạn có thể truy vấn.
• Tài nguyên UNKNOWN thường hiển thị đầy đủ trong giao diện người dùng Google Ads.
• Tài nguyên UNKNOWN thường không thể thay đổi thông qua API.

Phân đoạn

Câu trả lời chứa một GoogleAdsRow cho mỗi tổ hợp sau:

• Thực thể của tài nguyên chính được chỉ định trong mệnh đề FROM
• Giá trị của từng trường segments đã chọn

Ví dụ: phản hồi cho một truy vấn chọn FROM campaign và có segments.ad_network_type và segments.date trong mệnh đề SELECT chứa một hàng cho mỗi tổ hợp sau:

• campaign
• segments.ad_network_type
• segments.date

Kết quả được phân đoạn ngầm theo từng thực thể của tài nguyên chính, chứ không phải theo giá trị của từng trường được chọn. Ví dụ:

SELECT campaign.status, metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_14_DAYS

sẽ trả về một hàng cho mỗi chiến dịch, chứ không phải một hàng cho mỗi giá trị riêng biệt của trường campaign.status.

Lưu ý: Phạm vi cung cấp phân khúc có thể khác nhau tuỳ theo phiên bản API. Ví dụ: segments.click_type trên AdGroupAsset, CampaignAsset và CustomerAsset và segments.ad_sub_network_type trên campaign_budget chỉ có thể chọn trong phiên bản 23 trở xuống; segments.ad_network_type trên PerformanceMaxPlacementView có trong phiên bản 24 trở lên; segments.ad_sub_format_type và segments.loyalty_membership có trong phiên bản 25 trở lên; và segments.search_lift_keyword_bundle và segments.search_property có trong phiên bản 26 trở lên. Sử dụng GoogleAdsFieldService để xác minh khả năng tương thích của phân khúc cho phiên bản API mà bạn đang truy vấn.