Cấu trúc truy vấn

Hệ thống có thể gửi truy vấn về các trường tài nguyên, phân đoạn và chỉ số đến GoogleAdsService Tìm kiếm hoặc SearchStream . Để tạo truy vấn bằng Ngôn ngữ truy vấn 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ữ. Một truy vấn được tạo thành từ 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đơn đặt hàng để giúp bạn chọn đúng dữ liệu. Sau khi được kết hợp thành một , bạn có thể thực hiện yêu cầu bằng cách sử dụng API Google Ads.

Mệnh đề

Video: Khả năng tương thích của 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 được phân tách bằng dấu phẩy và chỉ số, trả về các giá trị trong phản hồi. Mệnh đề SELECTbắt buộc trong truy vấn.

Truy vấn mẫu dưới đây là ví dụ về cách chọn thuộc tính cho một thuộc tính nhất định tài nguyên:

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 phép trong mệnh đề SELECT, do: hạn chế:

  • Không thể chọn các trường truy vấn. Các trường này sẽ có Thuộc tính siêu dữ liệu Selectable được đánh dấu là false.
  • Chọn thuộc tính của các trường lặp lại. Các trường này sẽ có Thuộc tính siêu dữ liệu isRepeated được đánh dấu là true.
  • Chọn các trường không có sẵn cho tài nguyên đã cho trong FROM mệnh đề. Bạn không thể chọn cùng lúc thuộc tính của một số tài nguyên, ngoài ra chỉ có một tập hợp con của tất cả các chỉ số và phân đoạn sẽ có sẵn cho tài nguyên trong Mệnh đề FROM.
  • Chọn các phân đoạn hoặc chỉ số không tương thích với nhau. Cho để 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 tình trạng 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 sẽ được trả về. Chiến lược phát hành đĩa đơn tài nguyên trong mệnh đề FROM xác định trường nào có thể dùng được tất cả trong mệnh đề khác mệnh đề cho truy vấn cho trước. Chỉ có thể chỉ định một tài nguyên trong Mệnh đề FROM. Mệnh đề FROMbắt buộc trong truy vấn đến GoogleAdsService Tìm kiếm hoặc SearchStream phương thức khác, tuy nhiên, bạn không nên chỉ định khi sử dụng phương thức GoogleAdsFieldService

Mặc dù chỉ có thể tồn tại 1 tài nguyên trong mệnh đề FROM đối với một truy vấn nhất định, nhưng các trường trong Tài nguyên được phân bổ. Những tài nguyên này ngầm kết hợp với tài nguyên trong mệnh đề FROM, nên bạn chỉ cần thêm thuộc tính vào mệnh đề SELECT để trả về giá trị. Không phải tất cả 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 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 có ít nhất một trường được chọn. Ví dụ: campaign.resource_name sẽ được đưa vào phản hồi cho thuộc tính 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 sẽ áp dụng khi lọc dữ liệu cho của bạn. 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 chúng. Mỗi điều kiện phải tuân theo mẫu field_name Operator value. Mệnh đề WHEREkhô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ố của một thời điểm nhất định khoảng thời gian:

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ần nhấp chuột cho tất cả các chiến dịch có hiển thị trên thiết bị di động ở 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, với các phân đoạn ngày sau (đượ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. Bởi vì phân đoạn này là phân đoạn ngày cốt lõi, nên phân đoạn này yêu cầu ngày có thời hạn phạm vi bao gồm các phân đoạn ngày chính trong mệnh đề WHERE sẽ được cung cấp.

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 trên là: segments.date, segments.week, phân đoạn.month, phân đoạn.quý và phân đoạn.năm. Nếu bất kỳ phân khúc nào trong số này được chọn, ít nhất một trong số đó phải được dùng trong mệnh đề WHERE.

Khi lọc, điều quan trọng là phân biệt chữ hoa chữ thường của toán tử tâm trí. Hãy xem mục Phân biệt chữ hoa chữ thường để biết thêm thông tin chi tiết.

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

ORDER BY

Mệnh đề ORDER BY chỉ định thứ tự xuất hiện kết quả bị trả lại. Nhờ đó, bạn có thể 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 ASCDESC, thứ tự mặc định thành ASC. Mệnh đề ORDER BYkhông bắt buộc trong truy vấn.

Truy vấn sau đây sắp xếp các chiến dịch được trả về theo số lần nhấp từ cao nhất xuống 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 dấu phẩy danh sách. Thứ tự này sẽ diễn ra theo cùng một trình tự như đã 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

LIMIT

Mệnh đề LIMIT cho phép bạn chỉ định số lượng kết quả cần trả về. Cách này rất hữu ích nếu bạn chỉ quan tâm đến bản 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. Những tham 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

Thiết lập 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 đây tìm nạp các chiến dịch dự thảo cùng với chiến dịch:

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 mỗi loại tài nguyên trong phản hồi sẽ 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ề bỏ_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, vì vậy tất cả 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à truecampaign.resource_namecustomer.resource_name không thuộc 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à truecampaign.resource_name được yêu cầu trong quá trình 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 trong Google Ads còn có: các hành vi có thể sử dụng:

  • Trường tài nguyên chính không bắt buộc phải nằm trong SELECT mệnh đề cho 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 để lọc dữ liệu:

    SELECT campaign.id
    FROM ad_group
    WHERE ad_group.status = PAUSED
    
  • Bạn có thể chọn riêng các chỉ số cho một tài nguyên nhất định; không có trường nào khác từ tài nguyên được yêu cầu 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 đoạn mà không có bất kỳ trường tài nguyên đi kèm nào hoặc chỉ số:

    SELECT segments.device FROM campaign
    
  • Trường resource_name (ví dụ: campaign.resource_name) có thể là dùng để 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'