Đang truy xuất đối tượng

Mục tiêu: Hiểu cách truy xuất đối tượng và số liệu thống kê hiệu suất bằng GoogleAdsService.

GoogleAdsService là dịch vụ báo cáo và truy xuất đối tượng hợp nhất của API Google Ads. 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 của đối tượng dựa trên phạm vi ngày.
• Sắp xếp đối tượng dựa trên các thuộc tính của đối tượng.
• Dùng các điều kiện để cho biết đối tượng bạn muốn 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 2 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 và hiệu quả hơn đối với nhóm kết quả lớn (lớn hơn 10.000 hàng). Phương thức này có thể phù hợp hơn nếu ứng dụng của bạn muốn tải nhiều dữ liệu nhất có thể nhanh nhất có thể.
• GoogleAdsService.Search sẽ chia nhỏ các phản hồi lớn thành các trang kết quả có thể quản lý. Điều này có thể phù hợp hơn 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ề tùy chọn phân trang so với phát trực tuyến.

Lưu ý quan trọng: Nếu di chuyển từ API AdWords, bạn có thể coi GoogleAdsService là sự kết hợp giữa dịch vụ quản lý đối tượng và dịch vụ báo cáo.

Gửi yêu cầu

Phương thức tìm kiếm này yêu cầu phải có SearchGoogleAdsRequest bao gồm các thuộc tính sau:

• customer_id.
• Ngôn ngữ truy vấn Google Ads query cho biết tài nguyên cần truy vấn, các thuộc tính, phân khúc và chỉ số cần truy xuất cũng như các điều kiện sử dụng để hạn chế đối tượng được trả về.
• (Chỉ GoogleAdsService.Search) A page_size để cho biết có bao nhiêu đối tượng cần trả về trong một phản hồi khi sử dụng cách phân trang.
• (Chỉ dành cho GoogleAdsService.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 chuyển trang.

Để 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.

Đang xử lý phản hồi

GoogleAdsService trả về danh sách các đối tượng GoogleAdsRow.

Mỗi GoogleAdsRow đại diện cho một đối tượng được trả về bởi một truy vấn và bao gồm một nhóm thuộc tính được điền dựa trên các trường yêu cầu trong mệnh đề SELECT. Các thuộc tính không có trong mệnh đề SELECT không được điền vào 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 trong phản hồi cho 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 nếu mệnh đề SELECT không bao gồm bất kỳ trường nào từ tài nguyên campaign.

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

Loại enum không xác định

Các tài nguyên được trả về với một loại UNKNOWN không được hỗ trợ đầy đủ trong phiên bản API đó. Các tài nguyên này 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 một tài nguyên có loại UNKNOWN, nhưng bạn không thể thay đổi tài nguyên đó thông qua API. Ví dụ về việc này sẽ là một chiến dịch hoặc quảng cáo mới được giới thiệu 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 cần lưu ý:

• Tài nguyên có loại UNKNOWN có thể được hỗ trợ sau hoặc vẫn chắc chắn UNKNOWN.
• Các đối tượng mới thuộc loại UNKNOWN có thể xuất hiện bất cứ lúc nào. Các đối tượng này tương thích ngược vì giá trị enum đã có sẵn. Thay đổi này sẽ ra mắt các tài nguyên để bạn có thể xem chính xác tài khoản của mình. Tài nguyên UNKNOWN có thể xuất hiện do hoạt động mới trong tài khoản của bạn thông qua các giao diện khác hoặc vì một tài nguyên không còn được hỗ trợ chính thức.
• UNKNOWN tài nguyên có thể đính kèm các chỉ số chi tiết mà bạn có thể truy vấn.
• Thông thường, bạn sẽ thấy toàn bộ tài nguyên UNKNOWN trong giao diện người dùng Google Ads.
• Tài nguyên UNKNOWN thường không thể bị thay đổi.

Phân đoạn

Nội dung phản hồi sẽ chứa một GoogleAdsRow cho mỗi tổ hợp nội dung sau:

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

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

• campaign
• segments.ad_network_type
• segments.date

Lưu ý: Các kết quả được phân đoạn ngầm theo từng phiên bản của tài nguyên chính, chứ không phải theo giá trị của từng trường đã chọn. Ví dụ:

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

sẽ tạo ra 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.