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.

Tạo báo cáo tìm kiếm trong API Báo cáo Search Ads 360

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ên campaign là một tài nguyên được phân bổ của tài nguyên ad_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ụng ad_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ên campaign, như campaign.name, thì khi sử dụng campaign_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ủa campaign_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ường segments. Danh sách này liệt kê mọi trường tài nguyên tương thích, trường metrics và các trường segments 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ên UNKNOWN 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.