Hãy đọc các phần bên dưới để tìm hiểu cách tạo báo cáo tìm kiếm trong API Báo cáo Search Ads 360.
Tìm kiếm dịch vụ
API Báo cáo Search Ads 360 cung cấp một dịch vụ đặc biệt để tìm kiếm và báo cáo.
SearchAds360Service
là một dịch vụ báo cáo và truy xuất đối tượng hợp nhất cung cấp hai phương thức tìm kiếm: SearchStream
và Search
. Các lượt tìm kiếm được chuyển trong một chuỗi truy vấn viết bằng Ngôn ngữ truy vấn của Search Ads 360. Bạn có thể xác định truy vấn để:
- Truy xuất các thuộc tính cụ thể của đối tượng.
- Truy xuất chỉ số hiệu suất cho các đối tượng dựa trên phạm vi ngày.
- Sắp xếp các đối tượng dựa trên thuộc tính của đối tượng.
- Lọc kết quả bằng cách sử dụng các điều kiện chỉ định đối tượng cần trả về
- Giới hạn số lượng đối tượng được trả về.
Cả hai phương thức tìm kiếm đều trả về tất cả các hàng khớp với truy vấn của bạn. Ví dụ: khi bạn truy xuất campaign.id
, campaign.name
và metrics.clicks
, API sẽ trả về SearchAds360Row
chứa đối tượng chiến dịch có các trường id
và name
được đặt và đối tượng metrics
có đặt trường clicks
.
Phương pháp tìm kiếm
SearchStream
Gửi một yêu cầu duy nhất và bắt đầu kết nối liên tục với API Báo cáo Search Ads 360, bất kể quy mô báo cáo.
- Các gói dữ liệu bắt đầu tải xuống ngay lập tức với toàn bộ kết quả được lưu vào bộ nhớ đệm dữ liệu.
- Mã của bạn có thể bắt đầu đọc dữ liệu được lưu vào vùng đệm mà không cần phải đợi toàn bộ luồng kết thúc.
Search
Gửi nhiều yêu cầu được phân trang để tải toàn bộ báo cáo xuống.
SearchStream
thường mang lại hiệu suất tốt hơn vì nó giúp loại bỏ thời gian mạng trọn vòng cần thiết để yêu cầu các trang riêng lẻ. Bạn nên sử dụng SearchStream
cho tất cả báo cáo có hơn 10.000 hàng. Không có sự khác biệt đáng kể về hiệu suất giữa các phương thức cho các báo cáo nhỏ hơn (<10.000 hàng).
Phương thức bạn sử dụng không ảnh hưởng đến hạn mức và giới hạn API của bạn: một truy vấn hoặc báo cáo duy nhất được tính là một hoạt động bất kể kết quả được phân trang hay truyền trực tuyến.
Cụm từ tìm kiếm mẫu
Truy vấn mẫu này trả về dữ liệu hiệu suất cho một tài khoản trong 30 ngày qua theo chiến dịch, được phân đoạn theo thiết bị:
SELECT
campaign.name,
campaign.status,
segments.device,
metrics.impressions,
metrics.clicks,
metrics.ctr,
metrics.average_cpc,
metrics.cost_micros
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
Tạo yêu cầu
Để gửi yêu cầu, bạn cần truyền customer_id
và chuỗi query
đến giao diện SearchAds360Service.SearchStream
hoặc SearchAds360Service.Search
.
Yêu cầu bao gồm một HTTP POST
gửi tới máy chủ API Báo cáo Search Ads 360 tại một trong các URL sau:
https://searchads360.googleapis.com/VERSION_NUMBER/customers/CUSTOMER_ID/searchads360:searchStream
https://searchads360.googleapis.com/VERSION_NUMBER/customers/CUSTOMER_ID/searchads360:search
Dưới đây là một ví dụ đầy đủ về định nghĩa báo cáo cho searchStream
được đính kèm trong yêu cầu HTTP POST
:
POST /VERSION_NUMBER/customers/CUSTOMER_ID/searchads360:searchStream HTTP/1.1 Host: searchads360.googleapis.com User-Agent: curl Content-Type: application/json Accept: application/json Authorization: Bearer [OAUTH_2.0_ACCESS_TOKEN] Parameters: { "query" : "SELECT campaign.name, campaign.status, segments.device, metrics.impressions, metrics.clicks, metrics.ctr, metrics.average_cpc, metrics.cost_micros FROM campaign WHERE segments.date DURING LAST_30_DAYS" }
Xử lý câu trả lời
SearchAds360Service
trả về danh sách các đối tượng SearchAds360Row
.
Mỗi SearchAds360Row
đại diện cho một đối tượng do truy vấn trả về. Mỗi đối tượng bao gồm một tập hợp các thuộc tính được điền dựa trên các trường được yêu cầu trong mệnh đề SELECT
của truy vấn. Các thuộc tính không có trong mệnh đề SELECT
sẽ không được điền vào các đối tượng trong phản hồi.
Ví dụ: truy vấn bên dưới sẽ chỉ điền campaign.id
, campaign.name
và campaign.status
vào từng đối tượng SearchAds360Row
. Các thuộc tính khác như campaign.engine_id
hoặc campaign.bidding_strategy_type
sẽ bị bỏ qua.
SELECT
campaign.id,
campaign.name,
campaign.status
FROM campaign
Tài liệu tham khảo
Phần Tài liệu tham khảo bao gồm tất cả thông tin bạn cần để sử dụng đúng cách từng cấu phần phần mềm. Mỗi tài nguyên có một trang, ví dụ: ad_group
và campaign
.
Các trang segments
và metrics
liệt kê tất cả các trường chỉ số và phân đoạn có sẵn.
Một số tài nguyên, phân đoạn và chỉ số không tương thích và không thể sử dụng cùng nhau, trong khi những tài nguyên, phân đoạn và chỉ số khác thì hoàn toàn tương thích và bổ trợ cho nhau. Mỗi trang tài nguyên bao gồm các thông tin sau (nếu có và phù hợp) cùng nhiều thông tin khác:
- Tài nguyên được phân bổ
Đối với một số tài nguyên, bạn có thể có tuỳ chọn ngầm kết hợp các tài nguyên có liên quan bằng cách chọn các trường của tài nguyên đó cùng với các trường của tài nguyên trong mệnh đề
FROM
. Ví dụ: tài nguyêncampaign
là một tài nguyên được phân bổ của tài nguyênad_group
. Tức là bạn có thể đưa các trường nhưcampaign.id
vàcampaign.bidding_strategy_type
vào truy vấn khi sử dụngad_group
trong mệnh đềFROM
.Mục Tài nguyên được phân bổ liệt kê các tài nguyên được phân bổ có sẵn. Không phải tài nguyên nào cũng có tài nguyên phân bổ.
- Cột trường tài nguyên
Tất cả các trường của tài nguyên đều được đưa vào cột Tài nguyên trường. Mỗi trường tài nguyên đều liên kết đến thông tin chi tiết khác về trường đó, bao gồm cả nội dung mô tả, danh mục, loại dữ liệu, loại URL và chế độ cài đặt có thể lọc, có thể chọn, có thể sắp xếp và lặp lại.
- Cột Phân đoạn
Không phải trường phân đoạn nào cũng có thể chọn được với một tài nguyên nhất định.
Cột Segment (Phân đoạn) liệt kê các trường
segments
mà bạn có thể sử dụng trong cùng mệnh đềSELECT
với các trường của tài nguyên. Mỗi trường liên kết đến thông tin chi tiết đầy đủ về trường đó, bao gồm cả nội dung mô tả, danh mục, loại dữ liệu, loại URL và chế độ cài đặt có thể lọc, chọn, sắp xếp được và lặp lại. Nếu đang sử dụng tài nguyên trong mệnh đềFROM
, bạn có thể sử dụng trình đơn thả xuống Yes/No (Có/Không) để lọc ra các phân đoạn không có sẵn.- Cột chỉ số
Không phải trường chỉ số nào cũng có thể chọn được với một tài nguyên nhất định.
Cột Chỉ số liệt kê các trường
metrics
mà bạn có thể sử dụng trong cùng một mệnh đềSELECT
với các trường của tài nguyên. Mỗi trường liên kết đến thông tin chi tiết đầy đủ về trường đó, bao gồm cả nội dung mô tả, danh mục, loại dữ liệu, loại URL và chế độ cài đặt có thể lọc, chọn, sắp xếp được và lặp lại. Nếu bạn đang sử dụng tài nguyên trong mệnh đềFROM
, hãy sử dụng trình đơn thả xuống Yes/No (Có/Không) để lọc ra các chỉ số không có sẵn.
- Phân đoạn tài nguyên
Một số tài nguyên có các trường phân đoạn tài nguyên mà bạn có thể chọn khi tài nguyên nằm trong mệnh đề
FROM
. Ví dụ: nếu bạn chọn một trường tài nguyêncampaign
, nhưcampaign.name
, thì khi sử dụngcampaign_budget
trong mệnh đềFROM
,campaign.resource_name
sẽ tự động được trả về và phân đoạn vìcampaign
là một tài nguyên phân đoạn củacampaign_budget
.Phần Tài nguyên phân đoạn liệt kê các tài nguyên phân đoạn có sẵn. Không phải tài nguyên nào cũng có tài nguyên phân đoạn.
- Có thể chọn với
Một số trường
segments
không tương thích với các tài nguyên, phân đoạn và chỉ số khác.Trang
segments
bao gồm một phần Có thể chọn với có thể mở rộng cho mỗi trườngsegments
. Danh sách này liệt kê mọi trường tài nguyên tương thích, trườngmetrics
và các trườngsegments
khác mà bạn có thể đưa vào mệnh đềSELECT
.
Phân đoạn
Bạn có thể phân đoạn kết quả tìm kiếm bằng cách thêm trường segments.FIELD_NAME
vào mệnh đề SELECT
của truy vấn.
Ví dụ: segments.device
trong truy vấn bên dưới sẽ dẫn đến một báo cáo có một hàng cho impressions
của mỗi thiết bị đối với tài nguyên được chỉ định trong mệnh đề FROM
.
SELECT
campaign.name,
campaign.status,
segments.device,
metrics.impressions
FROM campaign
Kết quả do SearchAds360Service.SearchStream
trả về sẽ có dạng như chuỗi JSON như sau:
{
"results":[
{
"campaign":{
"resourceName":"customers/1234567890/campaigns/111111111",
"name":"Test campaign",
"status":"ENABLED"
},
"metrics":{
"impressions":"10922"
},
"segments":{
"device":"MOBILE"
}
},
{
"campaign":{
"resourceName":"customers/1234567890/campaigns/111111111",
"name":"Test campaign",
"status":"ENABLED"
},
"metrics":{
"impressions":"28297"
},
"segments":{
"device":"DESKTOP"
}
},
...
]
}
Hãy xem segments
để biết danh sách các trường phân khúc có sẵn mà bạn có thể sử dụng.
Nhiều phân đoạn
Bạn có thể chỉ định nhiều phân đoạn trong mệnh đề SELECT
của truy vấn. Phản hồi chứa một đối tượng SearchAds360Row
cho mỗi tổ hợp của thực thể của tài nguyên chính được chỉ định trong mệnh đề FROM
và value của từng trường segment
đã chọn.
Ví dụ: truy vấn sau đây sẽ trả về một hàng cho từng tổ hợp của
campaign
, segments.ad_network_type
và segments.date
.
SELECT
segments.ad_network_type
segments.date
FROM campaign
Xin lưu ý rằng kết quả sẽ được phân đoạn ngầm theo từng thực thể của tài nguyên chính, chứ không phải theo giá trị của từng trường đã chọn.
Truy vấn mẫu sau đây dẫn đến một hàng cho mỗi chiến dịch, chứ không phải một hàng cho mỗi giá trị riêng biệt của trường campaign.status
.
SELECT
campaign.status,
metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_14_DAYS
Phân đoạn ngầm ẩn
Ban đầu, mỗi báo cáo sẽ được phân đoạn theo tài nguyên được chỉ định trong mệnh đề FROM
. Các chỉ số được phân đoạn theo trường resource_name
của tài nguyên này
Truy vấn ví dụ này sẽ tự động trả về ad_group.resource_name
và ngầm sử dụng truy vấn này để phân đoạn các chỉ số ở cấp ad_group
.
SELECT metrics.impressions
FROM ad_group
Chuỗi JSON được trả về sẽ có dạng như sau:
{
"results":[
{
"adGroup":{
"resourceName":"customers/1234567890/adGroups/2222222222"
},
"metrics":{
"impressions":"237"
}
},
{
"adGroup":{
"resourceName":"customers/1234567890/adGroups/33333333333"
},
"metrics":{
"impressions":"15"
}
},
{
"adGroup":{
"resourceName":"customers/1234567890/adGroups/44444444444"
},
"metrics":{
"impressions":"0"
}
}
]
}
Phân đoạn ngày chính
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 khoảng thời gian.
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
.
Truy vấn ví dụ này trả về các chỉ số clicks
của chiến dịch trong 30 ngày qua.
SELECT
campaign.id,
campaign.name,
segments.date,
metrics.clicks
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
Các trường phân đoạn ngày chính là ngoại lệ với quy tắc chung rằng bạn không thể sử dụng một trường phân đoạn trong mệnh đề WHERE
, trừ phi bạn cũng đưa trường đó vào mệnh đề SELECT
. Vui lòng xem phần Bộ lọc bị cấm để biết thêm thông tin.
Quy tắc chính về phân đoạn ngày:
Bạn có thể sử dụng trường ngày chính trong mệnh đề
WHERE
mà không cần đưa trường đó vào mệnh đềSELECT
. Bạn cũng có thể thêm trường này vào cả hai mệnh đề nếu muốn.Truy vấn mẫu này trả về các chỉ số
clicks
theo tên chiến dịch trong phạm vi ngày. Lưu ýsegments.date
không nằm trong mệnh đềSELECT
.SELECT campaign.name, metrics.clicks FROM campaign WHERE segments.date > '2022-02-01' AND segments.date < '2022-03-01'
Nếu đưa trường ngày chính vào mệnh đề
SELECT
, bạn phải chỉ định ngày hoặc phạm vi ngày hữu hạn trong mệnh đềWHERE
. Các trường được chỉ định trong mệnh đềSELECT
vàWHERE
không cần phải khớp với nhau.Truy vấn mẫu này trả về các chỉ số
clicks
theo tên chiến dịch được phân đoạn theo tháng cho tất cả các ngày trong phạm vi ngày đó.SELECT campaign.name, metrics.clicks, segments.month FROM campaign WHERE segments.date > '2022-02-01' AND segments.date < '2022-03-01'
Ngày theo ISO 8601
Bạn có thể sử dụng định dạng YYYY-MM-DD
(ISO 8601) để chỉ định ngày và phạm vi ngày,
ví dụ:
WHERE segments.date BETWEEN '2022-06-01' AND '2022-06-30'
WHERE segments.date >= '2022-06-01' AND segments.date <= '2022-06-30'
Đối với các phân đoạn ngày chính yêu cầu khoảng thời gian (segments.week
, segments.month
, segments.quarter
), bạn có thể sử dụng toán tử =
với ngày đầu tiên của khoảng thời gian, ví dụ:
WHERE segments.month = '2022-06-01'
Ngày được xác định trước
Bạn cũng có thể sử dụng các ngày và phạm vi ngày được xác định trước sau đây:
Ngày được xác định trước | |
---|---|
TODAY |
Chỉ hôm nay. |
YESTERDAY |
Chỉ hôm qua. |
LAST_7_DAYS |
7 ngày trước, không bao gồm ngày hôm nay. |
LAST_BUSINESS_WEEK |
Tuần làm việc 5 ngày trước (thứ Hai đến thứ Sáu). |
THIS_MONTH |
Tất cả các ngày trong tháng hiện tại. |
LAST_MONTH |
Tất cả các ngày trong tháng trước. |
LAST_14_DAYS |
14 ngày trước, không bao gồm ngày hôm nay. |
LAST_30_DAYS |
30 ngày trước, trừ ngày hôm nay. |
THIS_WEEK_SUN_TODAY |
Khoảng thời gian giữa Chủ Nhật trước đó và ngày hiện tại. |
THIS_WEEK_MON_TODAY |
Khoảng thời gian từ thứ Hai trước đó đến ngày hiện tại. |
LAST_WEEK_SUN_SAT |
Khoảng thời gian 7 ngày bắt đầu từ Chủ Nhật trước đó. |
LAST_WEEK_MON_SUN |
Khoảng thời gian 7 ngày bắt đầu từ thứ Hai tuần trước. |
Ví dụ:
WHERE segments.date DURING LAST_30_DAYS
Không có chỉ số nào
Khi thực thi một truy vấn, bạn có thể gặp các chỉ số có giá trị bằng 0 đối với một số thực thể. Tìm hiểu cách xử lý chỉ số 0 trong truy vấn.
Loại enum KHÔNG XÁC ĐỊNH
Nếu một tài nguyên được trả về bằng kiểu dữ liệu enum UNKNOWN
, thì tức là kiểu đó không được hỗ trợ đầy đủ trong phiên bản API. Các tài nguyên này có thể được tạo thông qua các giao diện khác. Ví dụ: một chiến dịch hoặc quảng cáo mới được ra mắt trong giao diện người dùng Search Ads 360, nhưng chưa được hỗ trợ trong phiên bản API mà bạn đang truy vấn.
Bạn vẫn có thể chọn các chỉ số khi tài nguyên có loại UNKNOWN
, nhưng bạn cần lưu ý những điều sau:
- Tài nguyên có loại
UNKNOWN
có thể được hỗ trợ sau này, nhưng tài nguyên đó có thể vẫn làUNKNOWN
vô thời hạn. - Các đối tượng mới thuộc loại
UNKNOWN
có thể xuất hiện bất cứ lúc nào. Các đối tượng này có khả năng tương thích ngược vì đã có giá trị enum. Chúng tôi sẽ giới thiệu các tài nguyên có thay đổi này khi chúng có sẵn để bạn có cái nhìn chính xác về tài khoản của mình. Tài nguyênUNKNOWN
có thể xuất hiện do có hoạt động mới trong tài khoản của bạn thông qua các giao diện khác hoặc do một tài nguyên không còn được hỗ trợ chính thức nữa. - Các tài nguyên
UNKNOWN
có thể có các chỉ số chi tiết đi kèm mà bạn có thể truy vấn. - Tài nguyên
UNKNOWN
thường hiển thị đầy đủ trong giao diện người dùng Search Ads 360.