API Báo cáo Search Ads 360 mới hiện đã ra mắt. Tham gia nhóm Google searchads-api-announcements để luôn được cập nhật về những cải tiến và bản phát hành sắp tới.

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Cấu trúc truy vấn và mệnh đề

Một truy vấn bao gồm một số mệnh đề: SELECT, FROM, WHERE, ORDER BY, LIMIT và 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ự kết hợp thành một yêu cầu truy vấn duy nhất.

Nói một cách cơ bản, để tạo một truy vấn, bạn cần:

Chỉ định một tài nguyên để truy xuất dữ liệu.
Thêm các trường và chỉ số để xác định dữ liệu bạn muốn trả về.
Thêm phân đoạn để nhóm kết quả.
Thêm các tài nguyên được phân bổ để kết hợp ngầm dữ liệu tài nguyên có liên quan.
Lọc, sắp xếp thứ tự và giới hạn kết quả.

Mệnh đề `SELECT`

Mệnh đề SELECT:

Là một mệnh đề bắt buộc trong một truy vấn.
Chỉ định một tập hợp các trường cần tìm nạp trong yêu cầu.
Lấy một danh sách gồm nhiều trường tài nguyên, cột tuỳ chỉnh, biến Floodlight tuỳ chỉnh, trường phân đoạn và chỉ số được phân tách bằng dấu phẩy, đồng thời trả về các giá trị trong phản hồi.

Truy vấn ví dụ này cho biết cách chọn các thuộc tính của tài nguyên campaign:

SELECT
  campaign.id,
  campaign.name
FROM campaign

Nhiều loại trường

Bạn có thể yêu cầu nhiều loại trường trong cùng một yêu cầu.

Truy vấn mẫu bên dưới cho thấy một truy vấn duy nhất kết hợp:

Các trường tài nguyên: campaign.id, campaign.name, bidding_strategy.id và bidding_strategy.name.
Trường phân đoạn: segments.device và segments.date.
Các trường chỉ số: metrics.impressions và metrics.clicks.

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

Hãy xem phần Phân đoạn để tìm hiểu thêm về cách phân đoạn báo cáo tìm kiếm.

Trường tài nguyên chính

Thông thường, bạn sẽ thêm trường tài nguyên chính vào mệnh đề SELECT, nhưng đây là lựa chọn không bắt buộc (không bắt buộc).

Truy vấn ví dụ này sử dụng một trường tài nguyên chính (ad_group.status) để chỉ lọc kết quả.

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

Biến Floodlight tuỳ chỉnh

Bạn có thể thêm các biến Floodlight tuỳ chỉnh vào mệnh đề SELECT bằng cách sử dụng mã nhận dạng của các biến đó.

Trong ví dụ này, truy vấn bao gồm một biến tuỳ chỉnh có mã nhận dạng 123454321 cho tài nguyên chiến dịch.

SELECT
  conversion_custom_metrics.id[123454321]
FROM campaign

SELECT
  conversion_custom_dimensions.id[123454321]
FROM campaign

Cột tùy chỉnh

Bạn có thể thêm các cột tuỳ chỉnh vào mệnh đề SELECT bằng cách sử dụng mã nhận dạng của các cột đó.

Trong ví dụ này, truy vấn bao gồm một cột tuỳ chỉnh có mã nhận dạng 12345678 cho tài nguyên chiến dịch.

SELECT
  custom_columns.id[12345678]
FROM campaign

Xem cách lấy mã nhận dạng cột tuỳ chỉnh.

Trường chỉ số

Bạn có thể chọn các trường chỉ số cho một tài nguyên nhất định mà không cần thêm bất kỳ trường nào khác từ tài nguyên đó vào mệnh đề .SELECT

Truy vấn ví dụ này chọn chỉ số impressions và clicks cho tài nguyên campaign.

SELECT
  metrics.impressions,
  metrics.clicks
FROM campaign

Hãy xem metrics để biết danh sách các trường chỉ số mà bạn có thể sử dụng trong truy vấn.

Trường phân đoạn

Bạn có thể chọn các trường phân đoạn mà không cần chỉ định các trường tài nguyên hoặc chỉ số đi kèm trong mệnh đề SELECT.

Truy vấn mẫu này phân đoạn kết quả theo thiết bị.

SELECT segments.device
FROM campaign

Hãy xem segments để biết danh sách các trường phân đoạn mà bạn có thể sử dụng trong các truy vấn.

Các trường bị cấm

Bạn không thể sử dụng các trường sau trong mệnh đề SELECT:

Các trường không chọn được, tức là các trường có thuộc tính siêu dữ liệu Selectable được đánh dấu là false.
Các trường lặp lại, tức là các trường có thuộc tính siêu dữ liệu Repeated được đánh dấu là true.
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. Một số tài nguyên chỉ cung cấp một nhóm nhỏ trong số tất cả các chỉ số và phân đoạn.
Các phân đoạn hoặc chỉ số không tương thích. Hãy xem phần Phân đoạn để biết thêm thông tin.

Hãy xem Tài liệu tham khảo để biết thông tin chi tiết về nơi tìm thông tin này cho từng tài nguyên.

Mệnh đề FROM

Mệnh đề FROM:

Là một mệnh đề bắt buộc đối với các truy vấn đến SearchAds360Service (cả phương thức Search và SearchStream).
Không được thêm not cho các cụm từ tìm kiếm đến SearchAds360FieldService.
Chỉ định tài nguyên chính mà truy vấn trả về.
Chỉ có thể chỉ định một tài nguyên duy nhất.
Xác định các trường mà bạn có thể sử dụng trong tất cả các mệnh đề khác trong truy vấn.

Tài nguyên được phân bổ

Nếu có tài nguyên được phân bổ, thì các tài nguyên đó sẽ được kết hợp ngầm với tài nguyên mà bạn chỉ định trong mệnh đề FROM. Bạn chỉ cần thêm các thuộc tính của họ vào mệnh đề SELECT để trả về các giá trị của họ.

Truy vấn ví dụ này trả về cả mã nhóm quảng cáo và mã chiến dịch, vì campaign là một tài nguyên được phân bổ của tài nguyên ad_group.

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

`resource_name` trường

Trường resource_name của tài nguyên chính trong mệnh đề FROM luôn được trả về.

Trong truy vấn ví dụ này, ad_group.resource_name sẽ được đưa vào phản hồi ngay cả khi bạn không chọn rõ ràng trong truy vấn:

SELECT ad_group.id
FROM ad_group

Trường resource_name của tài nguyên được phân bổ sẽ được trả về khi bạn chọn ít nhất một trường.

Trong cụm từ tìm kiếm ví dụ này, campaign.resource_name sẽ được đưa vào câu trả lời vì campaign.id được chọn:

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

Mệnh đề WHERE

Mệnh đề WHERE:

Là một mệnh đề không bắt buộc trong một truy vấn.
Chỉ định các điều kiện để lọc và phân đoạn dữ liệu cho yêu cầu. Điều kiện tuân theo mẫu sau: FIELD_NAME OPERATOR VALUE (phân tách bằng dấu cách).
Có thể bao gồm nhiều điều kiện được phân tách bằng dấu phân cách AND.

Truy vấn mẫu này cho biết cách sử dụng mệnh đề WHERE để trả về các chỉ số impressions cho 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

Hãy xem phần Phân đoạn để tìm hiểu thêm về cách phân đoạn báo cáo tìm kiếm.

Hãy xem phần Phạm vi ngày để tìm hiểu thêm về cách chỉ định phạm vi ngày trong các truy vấn.

Lọc theo trường `resource_name`

Bạn có thể sử dụng trường resource_name để lọc hoặc sắp xếp dữ liệu.

Truy vấn ví dụ này sử dụng trường campaign.resource_name để lọc kết quả theo một chiến dịch nhất định:

SELECT
  campaign.id,
  campaign.name
FROM campaign
WHERE campaign.resource_name = 'customers/1234567/campaigns/987654'

Nhiều điều kiện

Bạn có thể kết hợp nhiều điều kiện để lọc dữ liệu.

Truy vấn ví dụ này yêu cầu số lượng chỉ số clicks cho tất cả các chiến dịch có chỉ số impressions 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

Hãy xem phần Phân đoạn để tìm hiểu thêm về cách phân đoạn báo cáo.

Có phân biệt chữ hoa chữ thường

Khi lọc theo giá trị chuỗi, chế độ phân biệt chữ hoa chữ thường mặc định của mỗi toán tử đóng vai trò quan trọng trong việc lọc kết quả một cách chính xác.

Bảng sau đây cho biết độ phân biệt chữ hoa chữ thường mặc định của từng toán tử.

Độ nhạy mặc định
`=/!=`	`Case sensitive`
`IN/NOT IN`	`Case sensitive`
`LIKE/NOT LIKE`	`Case insensitive`
`CONTAINS (...)`	`Case sensitive`
`REGEXP_MATCH/NOT REGEXP_MATCH`	`Case sensitive`

Bạn có thể dùng đối tượng sửa đổi (?i) để thay đổi độ nhạy mặc định cho REGEXP_MATCH và NOT REGEXP_MATCH thành không phân biệt chữ hoa chữ thường, ví dụ:

SELECT campaign.id
FROM campaign
WHERE campaign.name REGEXP_MATCH "(?i).*test.*"

Hãy xem Tài liệu tham khảo về cú pháp truy vấn để biết danh sách đầy đủ các toán tử mà bạn có thể dùng để lọc dữ liệu.

Phân khúc ngày cốt lõi

Các trường phân đoạn sau đây được gọi là phân đoạn ngày cốt lõi: segments.date, segments.week, segments.month, segments.quarter và segments.year.

Bạn có thể sử dụng các phân đoạn ngày chính trong mệnh đề WHERE để chỉ định một ngày hoặc khoảng thời gian.

Truy vấn mẫu này chỉ định DURING LAST_30_DAYS cho trường segments.date trong mệnh đề WHERE:

SELECT
  campaign.id,
  campaign.name,
  segments.date,
  metrics.clicks
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

Hãy xem phần Phân đoạn > Phân đoạn ngày cốt lõi để biết thông tin chi tiết về cách sử dụng phân đoạn ngày cốt lõi.

Lọc bị cấm

Không được phép lọc:

Trên các trường phân đoạn không được chọn, ngoại trừ phân đoạn ngày chính.
Trên các trường thuộc mọi loại thông báo, ngoại trừ các kiểu dữ liệu nguyên thuỷ (ví dụ: Int64Value, StringValue, v.v.).
Trên các thuộc tính của các trường lặp lại thuộc mọi loại thông báo, ngoại trừ các kiểu dữ liệu nguyên thuỷ (ví dụ: Int64Value, StringValue, v.v.).

Mệnh đề ORDER BY

Mệnh đề ORDER BY:

Là một mệnh đề không bắt buộc trong một truy vấn.
Chỉ định thứ tự trả về kết quả. Thứ tự tuân theo mẫu sau: FIELD_NAME ORDERING_OPTION (phân tách bằng dấu cách).
Cho phép 2 lựa chọn: ASC (tăng dần) hoặc DESC (giảm dần). Mặc định là tăng dần.

Truy vấn ví dụ này sắp xếp các chiến dịch theo số lượt nhấp theo thứ tự giảm dần (từ cao nhất đến thấp nhất):

SELECT
  campaign.name,
  metrics.clicks
FROM campaign
ORDER BY metrics.clicks DESC

Nhiều cách sắp xếp

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. Kết quả sẽ được sắp xếp theo thứ tự giống như bạn chỉ định trong truy vấn.

Truy vấn ví dụ này chọn dữ liệu nhóm quảng cáo và sắp xếp kết quả 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ị, rồi 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

Kết hợp sắp xếp theo thứ tự và giới hạn

Bạn có thể sử dụng mệnh đề ORDER BY kết hợp với mệnh đề LIMIT để tinh chỉnh kết quả.

Truy vấn mẫu này trả về 5 chiến dịch có số lượt hiển thị cao nhất trong 30 ngày qua:

SELECT
  campaign.id,
  campaign.name,
  metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
ORDER BY metrics.impressions DESC
LIMIT 5

Đơn đặt hàng bị cấm

Không được phép đặt hàng:

Theo thuộc tính của tài nguyên không được chọn.
Theo các chỉ số không được chọn.
Theo các phân khúc chưa chọn.
Đối với các loại trường sau:
- MESSAGE
- Các trường lặp lại
- Thuộc tính của các trường lặp lại.

Mệnh đề LIMIT

Mệnh đề LIMIT:

Là một mệnh đề không bắt buộc trong một truy vấn.
Cho phép bạn giới hạn số lượng kết quả mà truy vấn trả về.

Mệnh đề này rất hữu ích, chẳng hạn như nếu bạn chỉ quan tâm đến mẫu hoặc bản tóm tắt kết quả.

Truy vấn ví dụ này giới hạn tổng số kết quả là 50:

SELECT
  campaign.name,
  ad_group.name,
  segments.device,
  metrics.impressions
FROM ad_group
ORDER BY metrics.impressions DESC
LIMIT 50

Mệnh đề PARAMETERS

Mệnh đề PARAMETERS cho phép bạn chỉ định các tham số meta cho yêu cầu.

Bao gồm bản nháp

Tham số include_drafts kiểm soát việc các thực thể nháp có được đưa vào kết quả hay không. Giá trị mặc định là false. Đặt thành true để thêm các thực thể nháp.

Truy vấn mẫu này trả về cả chiến dịch dự thảo và chiến dịch thông thường:

SELECT campaign.name
FROM campaign
PARAMETERS include_drafts=true

Bỏ qua các mục chưa chọn `resource_name`

Tham số omit_unselected_resource_names cho phép bạn loại trừ trường resource_name của tất cả các tài nguyên không được yêu cầu rõ ràng trong mệnh đề SELECT. Giá trị mặc định là false. Nếu bạn đặt tham số này thành true, thì bạn nên yêu cầu rõ ràng tên tài nguyên của tài nguyên chính và mọi tài nguyên được phân bổ trong mệnh đề SELECT.

Truy vấn ví dụ này không trả về trường campaign.resource_name cũng như customer.resource_name vì các trường này không có trong mệnh đề SELECT:

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

Cụm từ tìm kiếm mẫu này trả về trường campaign.resource_name vì trường này được yêu cầu rõ ràng trong mệnh đề SELECT:

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

Thay đổi đơn vị tiền tệ được dùng trong các chỉ số

Tham số metrics_currency cho phép bạn chỉ định đơn vị tiền tệ cần sử dụng khi tính toán một chỉ số có trong mệnh đề SELECT. Theo mặc định, hệ thống sẽ sử dụng đơn vị tiền tệ của tài khoản do customer_id chỉ định. Nếu đặt tham số này, bạn cần sử dụng mã đơn vị tiền tệ gồm 3 ký tự theo tiêu chuẩn ISO 4217. Ví dụ: USD, EUR.

Truy vấn ví dụ này trả về chỉ số cost_micros bằng đơn vị tiền tệ của tài khoản do customer_id chỉ định.

SELECT
  campaign.name,
  metrics.cost_micros
FROM campaign
WHERE segments.date >= "2018-08-15"
AND segments.date < "2018-08-16"

Truy vấn ví dụ này trả về chỉ số cost_micros bằng đồng peso Chile (CLP).

SELECT
  campaign.name,
  metrics.cost_micros
FROM campaign
WHERE segments.date >= "2018-08-15"
AND segments.date < "2018-08-16"
PARAMETERS metrics_currency = "CLP"

Bật tính năng mở rộng MCC

Khi được đặt thành true, tham số enable_mcc_expansion cho phép bạn thêm các chỉ số, trường và phân đoạn từ tất cả tài khoản bắt nguồn từ customer_id, cho tài nguyên trong mệnh đề FROM. Phản hồi sẽ sử dụng đơn vị tiền tệ của customer_id, trừ phi được chỉ định rõ ràng trong tham số metrics_currency.

Truy vấn ví dụ này trả về bidding_strategy.name, bidding_strategy.type và metrics.cost_micros từ tất cả tài khoản trong hệ thống phân cấp tài khoản bắt nguồn từ customer_id, vì tham số enable_mcc_expansion được đặt thành true.

SELECT
  bidding_strategy.name,
  bidding_strategy.type,
  metrics.cost_micros
FROM bidding_strategy
WHERE segments.date DURING LAST_14_DAYS
PARAMETERS enable_mcc_expansion = true

Tìm hiểu thêm

Ngữ pháp truy vấn