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.

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 Search Ads 360 Reporting API.

Dịch vụ tìm kiếm

Search Ads 360 Reporting API 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 truyền trong một chuỗi truy vấn được viết bằng Ngôn ngữ truy vấn Search Ads 360. Bạn có thể xác định các truy vấn để:

Truy xuất các thuộc tính cụ thể của đối tượng.
Truy xuất các chỉ số hiệu suất cho đối tượng dựa trên một phạm vi ngày.
Sắp xếp các đối tượng dựa trên thuộc tính của chú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ề một SearchAds360Row chứa đối tượng chiến dịch có các trường id và name được đặt, đồng thời một đối tượng metrics có trường clicks được đặt.

Phương thức tìm kiếm

SearchStream

Gửi một yêu cầu duy nhất và bắt đầu một kết nối liên tục với Search Ads 360 Reporting API bất kể kích thước 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ộ đệm dữ liệu.
Mã của bạn có thể bắt đầu đọc dữ liệu được lưu vào bộ đệm mà không cần phải đợi toàn bộ luồng hoàn tất.

Search

Gửi nhiều yêu cầu phân trang để tải toàn bộ báo cáo xuống.

SearchStream thường mang lại hiệu suất cao hơn vì phương thức này loại bỏ thời gian mạng trao đổi cần thiết để yêu cầu từng trang riêng lẻ. Bạn nên sử dụng SearchStream cho tất cả cá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 đối với các báo cáo nhỏ hơn (dưới 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: một truy vấn hoặc báo cáo duy nhất được tính là một thao tác bất kể kết quả được phân trang hay phát trực tuyến.

Truy vấn 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

Để đưa ra yêu cầu, bạn cần truyền một customer_id và một chuỗi query đến giao diện SearchAds360Service.SearchStream hoặc SearchAds360Service.Search.

Yêu cầu bao gồm một HTTP POST đến máy chủ Search Ads 360 Reporting API 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

Sau đây là ví dụ hoàn chỉnh 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ý phản hồ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 được 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 chỉ điền vào mỗi đối tượng SearchAds360Row các trường campaign.id, campaign.name và campaign.status. Các thuộc tính khác, chẳng hạn 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 Tham khảo bao gồm tất cả thông tin bạn cần để sử dụng chính xác 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 phân đoạn và chỉ số 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 hoàn toàn tương thích và bổ sung 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) và 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ó lựa 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 chúng 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à tài nguyên được phân bổ của tài nguyên ad_group. Điều này có nghĩa 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.

Phần 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 được 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ó trong cột Trường tài nguyên. Mỗi trường tài nguyên liên kết đến thông tin chi tiết hơn về trường đó, bao gồm cả nội dung mô tả, danh mục, loại dữ liệu, URL loại 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 tất cả các trường phân đoạn đều có thể chọn được với một tài nguyên nhất định.

Cột Phân đoạn liệt kê các trường segments 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, URL loại và chế độ cài đặt có thể lọc, có thể chọn, có thể sắp xếp 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 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 tất cả các trường chỉ số đều 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, URL loại và chế độ cài đặt có thể lọc, có thể chọn, có thể sắp xếp và lặp lại. Nếu đang sử dụng tài nguyên trong mệnh đề FROM, hãy sử dụng trình đơn thả xuống 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 tài nguyên phân đoạ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 campaign trường tài nguyên, chẳng hạn như campaign.name, khi sử dụng campaign_budget trong mệnh đề FROM của bạn, campaign.resource_name sẽ tự động được trả về và phân đoạn, vì campaign là 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 từng trường segments liệt kê tất cả các 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 a 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ẽ tạo ra một báo cáo có một hàng cho impressions của mỗi thiết bị cho tài nguyên được chỉ định trong FROM mệnh đề.

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 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 đoạn có sẵn mà bạn có thể sử dụng.

Nhiều phân đoạn

segments

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ể tài nguyên chính được chỉ định trong mệnh đề FROM và giá trị của từng trường segment đã chọn.

Ví dụ: truy vấn sau sẽ trả về một hàng cho mỗi 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ả được phân đoạn ngầm theo từng thực thể của tài nguyên chính, nhưng không theo giá trị của các trường riêng lẻ được chọn.

Truy vấn mẫu sau đây tạo ra 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

Ban đầu, mọi báo cáo đều đượ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 mẫu này tự động trả về ad_group.resource_name và ngầm sử dụng trường 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 tương tự 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 WHERE mệnh đề để chỉ định một 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 mẫu 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à một ngoại lệ đối với quy tắc chung là bạn không thể sử dụng trường phân đoạn trong mệnh đề WHERE, trừ phi bạn cũng đưa trường đó vào mệnh đề SELECT. Hãy xem phần Lọc bị cấm để biết thêm thông tin.

Quy tắc phân đoạn ngày chính:

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ể đưa trường đó 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. Xin lưu ý rằng segments.date không có 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 một 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 tiêu chuẩn 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 một 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 xác định trước

Bạn cũng có thể sử dụng các ngày và phạm vi ngày xác định trước sau đây:

Ngày 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 tính hôm nay).
`LAST_BUSINESS_WEEK`	Tuần làm việc 5 ngày trước đó (từ 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 tính hôm nay).
`LAST_30_DAYS`	30 ngày trước đó (không tính hôm nay).
`THIS_WEEK_SUN_TODAY`	Khoảng thời gian từ Chủ Nhật trước đó đến 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 trước đó.

Ví dụ:

WHERE segments.date DURING LAST_30_DAYS

Không có chỉ số

Khi thực thi một truy vấn, bạn có thể gặp phải 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ý các chỉ số bằng 0 trong truy vấn.

Các loại enum KHÔNG XÁC ĐỊNH

Nếu một tài nguyên được trả về với loại dữ liệu enum UNKNOWN, điều này có nghĩa là loại đó 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 một tài nguyên có loại UNKNOWN, nhưng bạn cần lưu ý những điều sau:

Một tài nguyên có loại UNKNOWN có thể được hỗ trợ sau này, nhưng có thể vẫn là UNKNOWN vô thời hạn.
Các đối tượng mới có loại UNKNOWN có thể xuất hiện bất cứ lúc nào. Các đối tượng này tương thích ngược vì giá trị enum đã có sẵn. Chúng tôi ra mắt các tài nguyên với thay đổi này khi chúng có sẵn để bạn có thể xem chính xác tài khoản của mình. Tài nguyên UNKNOWN có thể xuất hiện do 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.
Các tài nguyên UNKNOWN có thể có các chỉ số chi tiết được đính kèm mà bạn có thể truy vấn.
Các tài nguyên UNKNOWN thường hiển thị đầy đủ trong giao diện người dùng Search Ads 360.