Cấu trúc truy vấn

Bạn có thể gửi truy vấn cho các trường tài nguyên, phân khúc và chỉ số đến phương thức GoogleAdsService Search hoặc SearchStream. Để tạo một truy vấn trong Ngôn ngữ truy vấn Google Ads, hãy tạo truy vấn đó bằng cách sử dụng ngữ pháp của ngôn ngữ này. Để xem thông tin tổng quan chung về Ngôn ngữ truy vấn Google Ads, hãy xem bài viết Tổng quan về Ngôn ngữ truy vấn Google Ads. Một truy vấn được tạo thành từ 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. Khi kết hợp thành một truy vấn duy nhất, bạn có thể gửi yêu cầu đến Google Ads API.

Mệnh đề

Các phần sau đây mô tả mục đích và cú pháp của từng mệnh đề trong Ngôn ngữ truy vấn Google Ads.

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 một danh sách các trường tài nguyên, trường phân khúc 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 một truy vấn.

Truy vấn mẫu sau đây cho thấy 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 các loại trường khác nhau 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 chính
    • campaign.id
    • campaign.name
  • Trường tài nguyên được phân bổ
    • bidding_strategy.id
    • bidding_strategy.name
  • Trường phân khúc
    • segments.device
    • segments.date
  • Chỉ số
    • metrics.impressions
    • metrics.clicks
  • Truy vấn các trường không thể chọn. Các trường này có thuộc tính siêu dữ liệu selectable được đánh dấu là false.
  • Chọn các thuộc tính của trường lặp lại. Các trường này có thuộc tính siêu dữ liệu is_repeated được đánh dấu là true.
  • Chọn các trường không có sẵn cho tài nguyên nhất định trong mệnh đề FROM. Bạn không thể chọn cùng nhau các thuộc tính của một số tài nguyên và chỉ có một tập hợp con của tất cả các chỉ số và phân khúc có sẵn cho tài nguyên trong mệnh đề FROM.
  • Chọn các phân khúc hoặc chỉ số không tương thích với nhau. Để biết thêm thông tin, hãy xem Phân khúc.

Bạn có thể tìm thấy thông tin liên quan đến các điều kiện nêu trên trong tài liệu tham khảo của chúng tôi hoặc từ GoogleAdsFieldService.

FROM

Mệnh đề FROM chỉ định tài nguyên chính cần trả về. Tài nguyên trong mệnh đề FROM xác định những trường có thể được sử dụng trong tất cả các mệnh đề khác cho 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 một truy vấn đến phương thức GoogleAdsService Search hoặc SearchStream. Tuy nhiên, bạn FROM không nên chỉ định mệnh đề khi sử dụng GoogleAdsFieldService.

Mặc dù chỉ có thể có một tài nguyên trong mệnh đề FROM cho một truy vấn nhất định, nhưng các trường từ tài nguyên được phân bổ cũng có thể có sẵn. 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, vì vậy, bạn chỉ cần thêm các thuộc tính của chúng vào mệnh đề SELECT để trả về các giá trị của chúng. Không phải tất cả tài nguyên đều 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ừ các 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 đượ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 tương tự cũng đúng đối với các tài nguyên được phân bổ khi bạn chọn ít nhất một trường. Ví dụ: campaign.resource_name được đưa vào phản hồi cho truy vấn sau:

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

WHERE

Mệnh đề WHERE chỉ định các điều kiện cần áp dụng khi lọc dữ liệu cho yêu cầu. Khi sử dụng mệnh đề WHERE, hãy chỉ định một hoặc nhiều điều kiện được phân tách bằng AND. Các điều kiện thường tuân theo mẫu field_name Operator value (hoặc sử dụng BETWEEN value AND value, IS NULL hoặc IS NOT NULL). Mệnh đề WHERE là không bắt buộc trong một truy vấn.

Ví dụ sau đây 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 yêu cầu số lượt nhấp cho tất cả các chiến dịch có 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 khúc trong mệnh đề WHERE cũng phải nằm trong mệnh đề SELECT, ngoại trừ các phân khúc ngày sau đây, được gọi là phân khúc ngày cơ bản:

  • segments.date
  • segments.week
  • segments.month
  • segments.quarter
  • segments.year

Trong truy vấn sau, segments.date được chọn. Vì phân khúc này là phân khúc ngày cơ bản, nên bạn phải cung cấp một phạm vi ngày hữu hạn trong mệnh đề WHERE bao gồm phân khúc ngày cơ bản:

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 khúc đáp ứng điều kiện nêu 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 khúc nào trong số này, thì bạn phải sử dụng ít nhất một trong số đó trong mệnh đề WHERE.

Để biết thêm thông tin chi tiết về tính năng lọc theo ngày, hãy xem bài viết Phạm vi ngày.

Khi lọc, hãy lưu ý đến tính phân biệt chữ hoa chữ thường của toán tử. Để biết thêm thông tin, hãy xem bài viết Tính phân biệt chữ hoa chữ thường.

Để xem danh sách đầy đủ các toán tử, hãy tham khảo ngữ pháp của ngôn ngữ này.

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à 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 một truy vấn.

Truy vấn sau đây sắp xếp các chiến dịch được 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. Việc sắp xếp diễn ra theo cùng một trình tự như được chỉ định trong truy vấn. Ví dụ: trong truy vấn này chọn dữ liệu nhóm quảng cáo, kết quả đượ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

LIMIT

Mệnh đề LIMIT cho phép bạn chỉ định số lượng kết quả cần trả về. Điều này rất hữu ích nếu bạn chỉ cần một tập hợp con kết quả.

Ví dụ: LIMIT có thể hạn chế 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

PARAMETERS

Mệnh đề PARAMETERS cho phép bạn chỉ định các tham số meta cho yêu cầu. Các tham số này có thể ảnh hưởng đến loại hàng được trả về.

Các tham số meta sau đây được hỗ trợ:

include_drafts

Đặt include_drafts thành true để trả về các thực thể nháp. Giá trị mặc định là false.

Ví dụ: truy vấn sau đây tìm nạp các chiến dịch nháp 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 để bỏ qua tên tài nguyên của từng loại tài nguyên trong phản hồi, trừ phi được yêu cầu rõ ràng trong mệnh đề SELECT. Giá trị mặc định là false.

Truy vấn Tài nguyên được trả về 
SELECT
  campaign.name,
  customer.id
FROM campaign
  • campaign.resource_name
  • customer.resource_name

omit_unselected_resource_names mặc định là false, vì vậy, tất cả các trường resource_name đều được trả về.

 
SELECT
  campaign.name,
  customer.id
FROM campaign
PARAMETERS omit_unselected_resource_names = true

Không có

omit_unselected_resource_names được chỉ định là true, và cả campaign.resource_name lẫn customer.resource_name đều không thuộc mệnh đề SELECT.

 
SELECT
  campaign.name,
  campaign.resource_name
FROM campaign
PARAMETERS omit_unselected_resource_names = true
  • campaign.resource_name

omit_unselected_resource_names được chỉ định là true và campaign.resource_name được yêu cầu là một phần của mệnh đề SELECT.

Quy tắc ngôn ngữ bổ sung

Ngoài các ví dụ cho từng mệnh đề, Ngôn ngữ truy vấn Google Ads còn hỗ trợ các hành vi sau:

  • Bạn không bắt buộc phải có trường tài nguyên chính trong mệnh đề SELECT cho một truy vấn. Ví dụ: bạn có thể sử dụng một hoặc nhiều trường tài nguyên chính để lọc dữ liệu mà không cần chọn các trường đó:

    SELECT campaign.id
FROM ad_group
WHERE ad_group.status = 'PAUSED'

  • Bạn có thể chỉ chọn các chỉ số cho một tài nguyên nhất định; không cần có trường nào khác từ tài nguyên đó trong truy vấn:

    SELECT
  metrics.impressions,
  metrics.clicks,
  metrics.cost_micros
FROM campaign

  • Bạn có thể chọn các trường phân khúc mà không cần có trường tài nguyên hoặc chỉ số đi kèm:

    SELECT segments.device FROM campaign

  • Bạn có thể sử 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'
Trước
Ngữ pháp truy vấn
Tiếp
Phạm vi ngày