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

Truy vấn được tạo thành từ một số mệnh đề: SELECT, FROM, WHERE, ORDER BY, LIMIT thân mến! 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 duy nhất.

Về cơ bản, để tạo một truy vấn, bạn:

Chỉ định tài nguyên để truy xuất dữ liệu.
Thêm trường và chỉ số để xác định dữ liệu mà bạn muốn trả về.
Thêm phân đoạn để nhóm các kết quả của bạn.
Thêm tài nguyên được phân bổ để ngầm kết hợp dữ liệu tài nguyên 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 đề required trong truy vấn.
Chỉ định một nhóm 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, trường tuỳ chỉnh được phân tách bằng dấu phẩy Biến Floodlight, trường phân đoạn và chỉ số, đồng thời trả về các giá trị trong của bạn.

Truy vấn mẫu này cho bạn biết cách chọn các thuộc tính của campaign tài nguyên:

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 ví dụ bên dưới cho thấy một truy vấn duy nhất kết hợp với:

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

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 của bạn.

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 trong SELECT Mệnh đề, nhưng đây là mệnh đề 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ể đưa các biến Floodlight tuỳ chỉnh vào mệnh đề SELECT (CHỌN) bằng cách sử dụng mã nhận dạng.

Trong ví dụ này, truy vấn bao gồm một biến tuỳ chỉnh có mã là 123454321 cho thuộc tính nguồn lực 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ã 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 là 12345678 cho thuộc tính nguồn lực 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 thêm bất kỳ trường nào khác trường từ tài nguyên trong mệnh đề SELECT.

Truy vấn mẫu này chọn chỉ số impressions và clicks cho campaign nguồn.

SELECT
  metrics.impressions,
  metrics.clicks
FROM campaign

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

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 đi kèm hoặc chỉ số trong mệnh đề SELECT.

Truy vấn ví dụ này phân đoạn kết quả theo thiết bị.

SELECT segments.device
FROM campaign

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

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

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

Những trường không thể chọn, tức là những trường có 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ác thuộc tính của một số tài nguyên cùng nhau. Chỉ một số tài nguyên tạo sẵn một tập hợp con gồm tất cả các chỉ số và phân khúc.
Phân khúc hoặc chỉ số không tương thích. Xem phần Phân đoạn để tìm hiểu thêm của bạn.

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

Mệnh đề TỪ

Mệnh đề FROM:

Là mệnh đề bắt buộc cho các truy vấn tới SearchAds360Service (cả phương thức Search và SearchStream).
Không nên đưa vào cho 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 duy nhất.
Xác định các trường mà bạn có thể sử dụng trong tất cả mệnh đề khác trong truy vấn.

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

Nếu có sẵn tài nguyên được phân bổ, chúng sẽ được ngầm kết hợp 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 thành phần này vào mệnh đề SELECT để trả về giá trị của chúng.

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 là bị trả lại.

Trong truy vấn mẫu này, ad_group.resource_name sẽ được đưa vào phản hồi mặc dù nó 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ổ là sẽ trả về khi có ít nhất một trường được chọn.

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 biết cách sử dụng mệnh đề WHERE để trả về 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

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 của bạn.

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

Lọc theo trường `resource_name`

Bạn có thể 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 mẫu này yêu cầu số lượng chỉ số clicks cho tất cả chiến dịch bằng impressions chỉ số 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

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ủa bạn.

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

Khi lọc các giá trị chuỗi, 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 chính xác kết quả của bạn.

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

Phân biệt chữ hoa chữ thường 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.*"

Xem Tài liệu tham khảo ngữ pháp truy vấn để biết danh sách đầy đủ bạn có thể sử dụng để lọc dữ liệu của mình.

Phân đoạn 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 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 ngày hoặc giờ 6 tháng.

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

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

Bộ lọc bị cấm

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

Trên các trường phân đoạn chưa được chọn, ngoại trừ các 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ừ dữ liệu gốc (ví dụ: Int64Value, StringValue, v.v.).
Trên 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ừ dữ liệu gốc (ví dụ: Int64Value, StringValue, v.v.).

Mệnh đề ĐẶT HÀNG THEO

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ả. Việc sắp xếp thứ tự sẽ tuân theo mẫu: FIELD_NAME ORDERING_OPTION (phân tách bằng một 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 (cao nhất đến thấp nhất):

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

Nhiều đơn đặt hàng

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. Kết quả sẽ được sắp xếp theo cùng một trình tự như 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 thứ tự theo tên chiến dịch, sau đó theo thứ tự giảm dần theo số lượt hiển thị và thì theo thứ tự giảm dần theo số lần 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ả của bạn.

Truy vấn ví dụ này trả về 5 chiến dịch có số lần 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

Đặt hàng bị cấm

Không được phép sắp xếp thứ tự:

Theo thuộc tính của các tài nguyên chưa được chọn.
Theo các chỉ số chưa được chọn.
Theo các phân khúc chưa được 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 đề GIỚI HẠN

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

Mệnh đề này hữu ích, ví dụ: nếu bạn chỉ quan tâm đến một mẫu hoặc 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 đề THAM SỐ

Mệnh đề PARAMETERS cho phép bạn chỉ định 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ó đưa các thực thể nháp vào kết quả. Giá trị mặc định là false. Hãy đặt thuộc tính này thành true để bao gồm các thực thể nháp.

Truy vấn ví dụ 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ỏ 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, chúng tôi khuyên 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 của bạn.

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

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 sử dụng trong các chỉ số

Tham số metrics_currency cho phép bạn chỉ định đơn vị tiền tệ để sử dụng khi tính toán chỉ số có trong mệnh đề SELECT. Lựa chọn mặc định là sử dụng nội tệ cho tài khoản. Nếu bạn thiết lập 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ộ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 ví dụ này trả về chỉ số cost_micros bằ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"

Tìm hiểu thêm

Ngữ pháp của cụm từ tìm kiếm