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.

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

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.

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.

Về 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 các phân khúc để nhóm kết quả.
Thêm tài nguyên được phân bổ để tham gia ngầm dữ liệu tài nguyên có liên quan.
Lọc, sắp xếp và giới hạn kết quả.

Mệnh đề `SELECT`

Mệnh đề SELECT:

Là mệnh đề bắt buộc trong truy vấn.
Chỉ định một tập hợp các trường để tìm nạp trong yêu cầu.
Lấy danh sách các 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 mẫu này cho bạn 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 đơn với tổ hợp:

Các trường tài nguyên: campaign.id, campaign.name, bidding_strategy.id và bidding_strategy.name.
Các 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ẽ đưa trường tài nguyên chính vào mệnh đề SELECT, nhưng điều này là không bắt buộc (không bắt buộc).

Truy vấn mẫu này sử dụng 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ể đưa 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ã 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ể đưa 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ã 12345678 cho tài nguyên chiến dịch.

SELECT
  custom_columns.id[12345678]
FROM campaign

Xem cách lấy mã 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 đưa bất kỳ trường nào khác từ tài nguyên đó vào mệnh đề SELECT.

Truy vấn mẫu này chọn các 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 khúc

Bạn có thể chọn các trường phân khúc 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 khúc mà bạn có thể sử dụng trong 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 thể chọn, tức là các trường có thuộc tính siêu dữ liệu Selectable được đánh dấu là false.
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. 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ỉ tạo một tập hợp con của tất cả các chỉ số và phân khú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ệ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 đưa vào các truy vấn đế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.
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ổ, các tài nguyên đó sẽ được kết hợp ngầm với tài nguyên bạn chỉ định trong mệnh đề FROM. 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.

Truy vấn mẫu này trả về cả mã nhóm quảng cáo và mã chiến dịch, vì campaign là 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

Trường `resource_name`

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 mẫu này, 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

Trường resource_name của một 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 truy vấn mẫu này, campaign.resource_name sẽ được đưa vào phản hồi vì campaign.id được chọn:

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

Mệnh đề WHERE

Mệnh đề WHERE:

Là mệnh đề không bắt buộc trong 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. Các điều kiện tuân theo mẫu sau: FIELD_NAME OPERATOR VALUE (được phân tách bằng khoảng trống).
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 thấy cách sử dụng mệnh đề WHERE để trả về các chỉ số impressions 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

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 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 mẫu 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 mẫu này yêu cầu số lượng chỉ số clicks cho tất 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, tính năng phân biệt chữ hoa chữ thường mặc định của từng toán tử đóng vai trò quan trọng trong việc lọc chính xác kết quả.

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

Phân biệt chữ hoa chữ thường theo 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ể sử 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 phần 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ử bạn có thể sử dụng để lọc dữ liệu.

Phân khúc ngày chính

Các trường phân khúc sau đây được gọi là phân khúc ngày chính: 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 chính để biết thông tin chi tiết về cách sử dụng phân đoạn ngày chính.

Bộ lọc bị cấm

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

Trên các trường phân khúc không được chọn, ngoại trừ các phân khúc ngày chính.
Trên các trường của bất kỳ loại thông báo nào, ngoại trừ các loại thông báo gốc (ví dụ: Int64Value, StringValue, v.v.).
Trên các thuộc tính của trường lặp lại thuộc bất kỳ loại thông báo nào, ngoại trừ các thuộc tính gốc (ví dụ: Int64Value, StringValue, v.v.).

Mệnh đề ORDER BY

Mệnh đề ORDER BY:

Là mệnh đề không bắt buộc trong truy vấn.
Chỉ định thứ tự trả về kết quả. Thứ tự tuân theo mẫu này: FIELD_NAME ORDERING_OPTION (được phân tách bằng một khoảng trống).
Cho phép hai tuỳ 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 mẫu 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 thứ tự

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

Truy vấn mẫu 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ị, 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

Kết hợp 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 các 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 không được chọn.
Đối với các loại trường sau:
- MESSAGE
- Trường lặp lại
- Thuộc tính của trường lặp lại.

Mệnh đề LIMIT

Mệnh đề LIMIT:

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

Ví dụ: mệnh đề này sẽ hữu ích nếu bạn chỉ quan tâm đến một mẫu hoặc bản tóm tắt kết quả.

Truy vấn mẫu này giới hạn tổng số kết quả ở mức 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ố siêu dữ liệu 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 giá trị này thành true để bao gồm các thực thể nháp.

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

SELECT campaign.name
FROM campaign
PARAMETERS include_drafts=true

Bỏ qua `resource_name` chưa được chọn

Thông số omit_unselected_resource_names cho phép bạn loại trừ trường resource_name của tất 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 đặt tham số này thành true, 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 mẫu này không trả về trường campaign.resource_name cũng như trường 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

Truy vấn 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 chỉ số

Tham số metrics_currency cho phép bạn chỉ định đơn vị tiền tệ sẽ 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ội tệ cho tài khoản. 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 mẫu này trả về chỉ số cost_micros theo đơn vị nội tệ của tài khoản.

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

Truy vấn mẫu này trả về chỉ số cost_micros tính theo 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"

Tìm hiểu thêm

Ngữ pháp truy vấn