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 các 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 bạn muốn trả về đối tượng nào 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,hiệu quả hơn cho các tập kết quả lớn (lớn hơn 10.000 hàng). Điều này có thể phù hợp hơn nếu ứng dụng của bạn muốn tải xuống nhiều dữ liệu nhất có thể trong thời gian nhanh nhất.GoogleAdsService.Search
chia các phản hồi lớn thành các trang kết quả dễ 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ề cách phân trang so với truyền trực tuyến.
Tạo yêu cầu
Phương thức tìm kiếm yêu cầu một SearchGoogleAdsRequest
, bao gồm các thuộc tính sau:
customer_id
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 khúc 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ề- (Chỉ
GoogleAdsService.Search
) Mộtpage_size
để cho biết số lượng đối tượng cần trả về trong một phản hồi khi sử dụng tính năng phân trang. - (Chỉ
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 phâ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.
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 do truy vấn trả về và bao gồm một nhóm thuộc tính được điề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 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 sẽ 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 với một hàng khác trong cùng một tập hợp kết quả; vì vậy, các hàng phải được xem là đối tượng thay vì các hàng cố định của bảng.
Các loại enum UNKNOWN
Các tài nguyên được trả về với 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 là UNKNOWN
, nhưng bạn không thể thay đổi tài nguyên đó thông qua API. Ví dụ về trường hợp này 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 là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 đã có sẵn. Tài nguyên được giới thiệu cùng với thay đổi này khi có sẵn để bạn có được thông tin chính xác về tài khoản của mình. Tài nguyênUNKNOWN
có thể xuất hiện do các 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 khi một tài nguyên không còn được hỗ trợ. - Tài nguyên
UNKNOWN
có thể có các chỉ số chi tiết được đính kèm và có thể truy vấn. - Tài nguyên
UNKNOWN
thường hiển thị đầy đủ trong giao diện người dùng của Google Ads. - Thường thì không thể thay đổi tài nguyên
UNKNOWN
.
Phân đoạn
Phản hồi sẽ chứa một GoogleAdsRow
cho mỗi tổ hợp sau:
- Phiên bản 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 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ẽ 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
.