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 đ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.

Lưu ý quan trọng: GoogleAdsFieldService cung cấp một danh mục cho ứng dụng Ngôn ngữ truy vấn của Google Ads với siêu dữ liệu về tất cả các trường tài nguyên, trường phân đoạn và chỉ số, cũng như mối quan hệ của chúng với nhau và khả năng sử dụng trong mỗi mệnh đề như được định nghĩa bên dưới. Để biết thêm thông tin, hãy tham khảo tài liệu về GoogleAdsField.

Đ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

Lưu ý quan trọng: Nếu tài nguyên trong mệnh đề FROM liệt kê một tài nguyên khác dưới dạng segment, thì việc chọn bất kỳ thuộc tính nào của tài nguyên đó sẽ đóng vai trò là một phân đoạn.

Ở ĐÂ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.

Lưu ý quan trọng: Bạn chỉ có thể sử dụng dấu phân cách AND giữa các điều kiện toán tử (WHERE segments.device != "DESKTOP" AND segments.device != "MOBILE") và không thể dùng trong một điều kiện toán tử duy nhất (WHERE segments.device != "DESKTOP" AND "MOBILE"),

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

Lưu ý quan trọng: LIMIT cho phép bạn cắt bớt kết quả. Hãy sử dụng trường page_size của GoogleAdsService.Search để xử lý các danh sách kết quả dài.

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.

Lưu ý: Nếu định sử dụng bất kỳ đối tượng nào được trả về để cập nhật hoặc xoá thao tác, bạn nên đặt tuỳ chọn này thành false vì không thể sử dụng các tài nguyên không có tên tài nguyên trong thao tác biến đổi. Nếu bạn đặt tuỳ chọn này thành true, hãy đảm bảo rằng bạn yêu cầu rõ ràng tên tài nguyên của cả tài nguyên chính và mọi tài nguyên thuộc tính mà bạn tìm nạp bằng truy vấn.

ví dụ về ignore_unselected_resource_names
SELECT campaign.name, customer.id FROM campaign	Returned resources: campaign.resource_name customer.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.costMicros
  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'