Bạn muốn chia sẻ ý kiến phản hồi về API Google Ads? Đăng ký để được mời tham gia nghiên cứu người dùng!

Trang này được dịch bởi Cloud Translation API.

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 các phương thức Search hoặc SearchStream của GoogleAdsService. Để tạo một truy vấn bằng Ngôn ngữ truy vấn của Google Ads, bạn cần tạo truy vấn đó bằng ngữ pháp ngôn ngữ. Một truy vấn bao gồm một số mệnh đề:

SELECT
FROM
WHERE
ORDER BY
LIMIT
PARAMETERS

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 kết hợp thành một truy vấn duy nhất, bạn có thể gửi yêu cầu bằ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 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 cho thấy ví dụ về cách chọn 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 khúc
- 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 các hạn chế sau:

Truy vấn các trường không thể chọ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 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 mệnh đề FROM. Bạn không thể chọn cùng lúc các thuộc tính của một số tài nguyên, đồng thời 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 khúc 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ể xem 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 từ 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ể được sử dụng cho 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 duy nhất trong mệnh đề FROM. Mệnh đề FROM là bắt buộc trong truy vấn đến các phương thức GoogleAdsService Search hoặc SearchStream, tuy nhiên, bạn không được chỉ định mệnh đề này khi sử dụng GoogleAdsFieldService.

Mặc dù chỉ có thể có 1 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ể xuất hiện. Các tài nguyên này được kết hợp ngầm ẩn 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ề giá trị của các tài nguyên đó. 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ừ 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 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 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 cầ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ó 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, ngoại trừ các phân đoạn ngày sau đây (được gọi là phân đoạn ngày cốt lõi):

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

Trong truy vấn sau, hãy lưu ý rằng segments.date được chọn. Vì là phân khúc ngày chính, nên phân khúc này yêu cầu bạn phải cung cấp một phạm vi ngày có giới hạn bao gồm các phân khúc 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 khúc đá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, ít nhất một phân đoạn phải được sử dụng trong mệnh đề WHERE.

Khi lọc, bạn cần lưu ý đến việc phân biệt chữ hoa chữ thường của toán tử. Hãy xem phần Tính năng 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ả. Thao tác 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 đơn đặt hàng đượ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 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 phân tách bằng dấu phẩy. Việc sắp xếp sẽ diễn ra theo trình tự giống như đã chỉ định trong truy vấn. Ví dụ: trong truy vấn này, dữ liệu nhóm quảng cáo 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ỉ quan tâm đến bản tóm tắt.

Ví dụ: bạn có thể dùng LIMIT để 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

THÔNG SỐ

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

Hiện tại, các thông số siêu dữ liệu sau đây đượ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 đây sẽ 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 để ngăn việc trả về 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.

Ví dụ về omit_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ả các trường resource_name sẽ đượ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` và `campaign.resource_name` và `customer.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à `true` và `campaign.resource_name` được yêu cầu trong mệnh đề `SELECT`.

Các quy tắc ngôn ngữ khác

Ngoài các ví dụ cho từng mệnh đề, Ngôn ngữ truy vấn Google Ads còn có các hành vi sau đây mà bạn có thể sử dụng:

Bạn không bắt buộc phải đặt trường tài nguyên chính trong mệnh đề SELECT cho 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; không có trường nào khác từ tài nguyên đó là bắt buộc 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ần có trường tài nguyên hoặc chỉ số đ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'

Ngữ pháp truy vấn

Tiếp

Phạm vi ngày