Bạn có thể gửi truy vấn cho các trường tài nguyên, phân đoạn và chỉ số đến phương thức GoogleAdsService
Tìm kiếm hoặc SearchStream. Để tạo một truy vấn bằng Ngôn ngữ truy vấn của Google Ads, bạn sẽ cần tạo truy vấn đó bằng cách sử dụng ngữ pháp ngôn ngữ. Truy vấn bao gồm một số mệnh đề:
SELECT
FROM
WHERE
ORDER BY
LIMIT
PARAMETERS
Các mệnh đề sử dụng tên trường, tên tài nguyên, toán tử, điều kiện và thứ tự để giúp bạn chọn đúng dữ liệu. Sau khi được kết hợp thành một truy vấn, bạn có thể tạo một yêu cầu bằng cách sử dụng API Google Ads.
Điều khoản
Video: Khả năng tương thích với trường GAQL
SELECT
Mệnh đề SELECT
chỉ định một tập hợp các trường cần tìm nạp trong yêu cầu.
SELECT
lấy danh sách các trường tài nguyên, trường phân đoạn và chỉ số được phân tách bằng dấu phẩy, trả về các giá trị trong phản hồi. Mệnh đề SELECT
là bắt buộc trong truy vấn.
Truy vấn mẫu bên dưới là ví dụ về cách chọn các thuộc tính cho một tài nguyên nhất định:
SELECT
campaign.id,
campaign.name
FROM campaign
Bạn có thể yêu cầu nhiều loại trường trong một yêu cầu, ví dụ:
SELECT
campaign.id,
campaign.name,
bidding_strategy.id,
bidding_strategy.name,
segments.device,
segments.date,
metrics.impressions,
metrics.clicks
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
Trường tài nguyên
campaign.id
campaign.name
Trường tài nguyên
bidding_strategy.id
bidding_strategy.name
Trường phân đoạn
segments.device
segments.date
Chỉ số
metrics.impressions
metrics.clicks
Một số trường có thể không được cho phép trong mệnh đề SELECT
do các hạn chế sau:
- Đang truy vấn các trường không thể chọn được. Thuộc tính siêu dữ liệu
Selectable
của các trường này sẽ được đánh dấu làfalse
. - Chọn thuộc tính của các trường lặp lại. Thuộc tính siêu dữ liệu
isRepeated
của các trường này sẽ được đánh dấu làtrue
. - Chọn các trường không có sẵn cho tài nguyên đã cho trong mệnh đề
FROM
. Bạn không thể chọn các thuộc tính của một số tài nguyên cùng nhau. Ngoài ra, chỉ một tập hợp con của tất cả các chỉ số và phân đoạn sẽ được cung cấp cho tài nguyên trong mệnh đềFROM
. - Chọn phân đoạn hoặc chỉ số không tương thích với nhau. Để biết thêm thông tin về vấn đề này, hãy xem phần phân đoạn.
Bạn có thể tìm thấy thông tin liên quan đến các điều kiện trên trong tài liệu tham khảo của chúng tôi hoặc trên GoogleAdsFieldService
.
FROM
Mệnh đề FROM
chỉ định tài nguyên chính sẽ được trả về. Tài nguyên trong mệnh đề FROM
xác định những trường có thể dùng mọi mệnh đề khác cho một truy vấn nhất định. Bạn chỉ có thể chỉ định một tài nguyên trong mệnh đề FROM
. Mệnh đề FROM
là bắt buộc trong truy vấn đối với phương thức GoogleAdsService
Search hoặc SearchStream. Tuy nhiên, bạn không nên chỉ định mệnh đề này khi sử dụng GoogleAdsFieldService
.
Mặc dù chỉ có 1 tài nguyên có thể tồn tại trong mệnh đề FROM
cho một truy vấn nhất định, nhưng bạn cũng có thể sử dụng các trường từ Tài nguyên được phân bổ. Các tài nguyên này được kết hợp ngầm với tài nguyên trong mệnh đề FROM
nên bạn chỉ cần thêm các thuộc tính của chúng vào mệnh đề SELECT
để trả về giá trị. Không phải tài nguyên nào cũng có Tài nguyên được phân bổ. Trong ví dụ sau, bạn có thể yêu cầu cả mã nhóm quảng cáo và mã chiến dịch từ nhóm quảng cáo:
SELECT
campaign.id,
ad_group.id
FROM ad_group
Trường resource_name
của tài nguyên chính luôn được trả về.
Trong ví dụ sau, ad_group.resource_name
sẽ được đưa vào phản hồi mặc dù không được chọn rõ ràng trong truy vấn:
SELECT ad_group.id
FROM ad_group
Điều này cũng đúng đối với các tài nguyên khác khi bạn chọn ít nhất một trường.
Ví dụ: campaign.resource_name
sẽ được đưa vào phản hồi cho truy vấn sau:
SELECT
campaign.id,
ad_group.id
FROM ad_group
Ở ĐÂU?
Mệnh đề WHERE
chỉ định các điều kiện áp dụng khi lọc dữ liệu cho yêu cầu. Khi sử dụng mệnh đề WHERE
, bạn có thể chỉ định một hoặc nhiều điều kiện bằng cách sử dụng AND
để phân tách các điều kiện đó. Mỗi điều kiện phải tuân theo mẫu field_name Operator value
. Mệnh đề WHERE
là không bắt buộc trong truy vấn.
Sau đây là ví dụ về cách sử dụng WHERE
để trả về các chỉ số trong một khoảng thời gian nhất định:
SELECT
campaign.id,
campaign.name,
metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
Bạn có thể kết hợp nhiều điều kiện để lọc dữ liệu. Ví dụ này sẽ yêu cầu số lượt nhấp cho tất cả chiến dịch có số lượt hiển thị trên thiết bị di động trong 30 ngày qua.
SELECT
campaign.id,
campaign.name,
segments.device,
metrics.clicks
FROM campaign
WHERE metrics.impressions > 0
AND segments.device = MOBILE
AND segments.date DURING LAST_30_DAYS
Các phân đoạn trong mệnh đề WHERE
phải nằm trong mệnh đề SELECT
, trong đó các phân đoạn ngày sau đây được gọi là phân đoạn ngày chính, là ngoại lệ:
segments.date
segments.week
segments.month
segments.quarter
segments.year
Trong truy vấn sau, lưu ý rằng segments.date
được chọn.
Do phân đoạn này là một phân đoạn ngày cốt lõi, nên phân đoạn này yêu cầu cung cấp một phạm vi ngày hữu hạn bao gồm các phân đoạn ngày chính trong mệnh đề WHERE
.
SELECT
campaign.id,
campaign.name,
segments.date,
metrics.clicks
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
Tất cả các phân đoạn đáp ứng điều kiện ở trên là: segments.date, segments.week,
segments.month, segments.quarter và segments.year. Nếu bạn chọn bất kỳ phân đoạn nào trong số này, thì ít nhất một trong các phân đoạn đó phải được sử dụng trong mệnh đề WHERE
.
Khi lọc, bạn cần lưu ý đến khả năng phân biệt chữ hoa chữ thường của toán tử. Hãy xem phần Phân biệt chữ hoa chữ thường để biết thêm thông tin chi tiết.
Để xem danh sách đầy đủ các toán tử, hãy tham khảo ngữ pháp ngôn ngữ.
ORDER BY
Mệnh đề ORDER BY
chỉ định thứ tự trả về kết quả. Điều này cho phép bạn sắp xếp dữ liệu theo thứ tự tăng dần hoặc giảm dần dựa trên tên trường. Mỗi thứ tự được chỉ định là một field_name
, theo sau là ASC
hoặc DESC
. Nếu bạn không chỉ định ASC
hoặc DESC
, thì thứ tự mặc định sẽ là ASC
. Mệnh đề ORDER BY
là không bắt buộc trong truy vấn.
Truy vấn sau đây sắp xếp các chiến dịch đã trả về theo số lượt nhấp từ cao nhất đến thấp nhất:
SELECT
campaign.name,
metrics.clicks
FROM campaign
ORDER BY metrics.clicks DESC
Bạn có thể chỉ định nhiều trường trong mệnh đề ORDER BY
bằng cách sử dụng danh sách được phân tách bằng dấu phẩy. Thứ tự sẽ diễn ra theo cùng trình tự như được chỉ định trong truy vấn.
Ví dụ: trong truy vấn chọn dữ liệu nhóm quảng cáo này, kết quả sẽ được sắp xếp theo thứ tự tăng dần theo tên chiến dịch, sau đó theo thứ tự giảm dần theo số lượt hiển thị, sau đó theo thứ tự giảm dần theo số lượt nhấp:
SELECT
campaign.name,
ad_group.name,
metrics.impressions,
metrics.clicks
FROM ad_group
ORDER BY
campaign.name,
metrics.impressions DESC,
metrics.clicks DESC
GIỚI HẠN
Mệnh đề LIMIT
cho phép bạn chỉ định số lượng kết quả sẽ được trả về.
Điều này rất hữu ích nếu bạn chỉ muốn nội dung tóm tắt.
Ví dụ: bạn có thể sử dụng LIMIT
để giới hạn tổng số kết quả cho truy vấn sau:
SELECT
campaign.name,
ad_group.name,
segments.device,
metrics.impressions
FROM ad_group
ORDER BY metrics.impressions DESC
LIMIT 50
THÔNG SỐ
Mệnh đề PARAMETERS
cho phép bạn chỉ định tham số meta cho yêu cầu.
Các thông số này có thể ảnh hưởng đến loại hàng được trả về.
Hiện tại, các tham số meta sau được hỗ trợ:
include_drafts
Đặt include_drafts
thành true
để cho phép trả về các thực thể nháp.
Mặc định là false
.
Ví dụ: truy vấn sau tìm nạp các chiến dịch dự thảo cùng với các chiến dịch thông thường:
SELECT campaign.name
FROM campaign
PARAMETERS include_drafts=true
omit_unselected_resource_names
Đặt omit_unselected_resource_names
thành true
để ngăn tên tài nguyên của từng loại tài nguyên trong phản hồi bị trả về, trừ phi được yêu cầu rõ ràng trong mệnh đề SELECT
. Giá trị mặc định là false
.
ví dụ về ignore_unselected_resource_names | |
---|---|
SELECT campaign.name, customer.id FROM campaign |
Returned resources:campaign.resource_name
omit_unselected_resource_names mặc định là false , do đó, mọi trường resource_name đều được trả về.
|
SELECT campaign.name, customer.id FROM campaign PARAMETERS omit_unselected_resource_names = true |
Returned resources: Không có. omit_unselected_resource_names được chỉ định là true , campaign.resource_name và customer.resource_name không nằm trong mệnh đề SELECT .
|
SELECT campaign.name, campaign.resource_name FROM campaign PARAMETERS omit_unselected_resource_names = true |
Returned resource:campaign.resource_name
omit_unselected_resource_names được chỉ định là true
và campaign.resource_name được yêu cầu trong mệnh đề
SELECT .
|
Quy tắc ngôn ngữ bổ sung
Ngoài các ví dụ cho mỗi mệnh đề, Ngôn ngữ truy vấn của Google Ads còn có các hành vi sau đây mà bạn có thể sử dụng:
Trường tài nguyên chính không bắt buộc phải nằm trong mệnh đề
SELECT
của một truy vấn. Ví dụ: bạn có thể chỉ muốn sử dụng một hoặc nhiều trường tài nguyên chính để lọc dữ liệu:SELECT campaign.id FROM ad_group WHERE ad_group.status = PAUSED
Bạn có thể chọn riêng chỉ số cho một tài nguyên nhất định; truy vấn không yêu cầu các trường khác của tài nguyên đó:
SELECT metrics.impressions, metrics.clicks, metrics.cost_micros FROM campaign
Bạn có thể chọn các trường phân đoạn mà không có bất kỳ trường tài nguyên hoặc chỉ số nào đi kèm:
SELECT segments.device FROM campaign
Bạn có thể dùng trường
resource_name
(ví dụ:campaign.resource_name
) để lọc hoặc sắp xếp dữ liệu:SELECT campaign.id, campaign.name FROM campaign WHERE campaign.resource_name = 'customers/1234567/campaigns/987654'