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 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 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 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 chúng.
Lọc kết quả bằ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 một đối tượng chiến dịch đã đặt trường id và name, cũng như một đối tượng metrics đã đặt trường clicks.

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

SearchStream

Gửi một yêu cầu và bắt đầu một kết nối liên tục với API Báo cáo Search Ads 360, 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ộ 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 chờ toàn bộ luồng kết thúc.

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 tốt hơn vì loại bỏ thời gian mạng hai chiều 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à hạn mức của API: một truy vấn hoặc báo cáo được tính là một thao tác bất kể kết quả được phân trang hay truyền trực tuyến.

Ví dụ về cụm từ tìm kiếm

Truy vấn mẫu này trả về dữ liệu hiệu suất của 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 customer_id và chuỗi query vào giao diện SearchAds360Service.SearchStream hoặc SearchAds360Service.Search.

Yêu cầu này bao gồm một POST HTTP đến 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à ví dụ đầy đủ về định nghĩa báo cáo cho searchStream được đưa vào yêu cầu POST HTTP:

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 đố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 chỉ điền sẵn campaign.id, campaign.name và campaign.status vào mỗi đối tượng SearchAds360Row. 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 Tài liệu 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. Có một trang cho mỗi tài nguyên, ví dụ: ad_group và campaign. Trang segments và metrics liệt kê tất cả các phân khúc và trường chỉ số hiện có.

Một số tài nguyên, phân khúc và chỉ số không tương thích và không thể sử dụng cùng nhau, trong khi một số khác lại tương thích hoàn toàn 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) 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ể chọn tham gia ngầm các tài nguyên 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à 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ổ hiện có. 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 nằm 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 khác về trường đó, bao gồm cả mô tả, danh mục, loại dữ liệu, URL loại và chế độ cài đặt có thể lọc, chọn, sắp xếp và lặp lại.

Cột Phân khúc

Không phải trường phân đoạn nào cũng có thể được chọn bằng một tài nguyên nhất định.

Cột Segments (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, loại URL và chế độ cài đặt có thể lọc, chọn, 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 khúc 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 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 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 trường tài nguyên campaign, chẳng hạn như campaign.name, 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à 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 bằng

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 Selectable with (Có thể chọn bằng) có thể mở rộng cho mỗi trường segments. Trang này liệt kê tất cả các trường tài nguyên, trường metrics và các trường segments khác tương thích 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ẽ 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 mệnh đề FROM.

SELECT
  campaign.name,
  campaign.status,
  segments.device,
  metrics.impressions
FROM campaign

Kết quả do SearchAds360Service.SearchStream trả về 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 khúc hiện có mà bạn có thể sử dụng.

Nhiều phân khúc

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

Ví dụ: truy vấn sau đây 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 phiên bản 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 sẽ trả về 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 đượ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 ad_group.resource_name để phân đoạn các chỉ số ở cấp ad_group.

SELECT metrics.impressions
FROM ad_group

Chuỗi JSON được trả về 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 khúc 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 một ngày hoặc khoảng thời gian.

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.

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

Các quy tắc chính về phân khúc ngày:

Bạn có thể sử dụng trường ngày tháng cốt lõi trong mệnh đề WHERE mà không cần đưa trường này vào mệnh đề SELECT. Bạn cũng có thể đưa 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 ý 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.

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 cốt lõi 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 đượ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 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ả 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 hôm nay.
`LAST_30_DAYS`	30 ngày trước, không bao gồm 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 tuần trước.

Ví dụ:

WHERE segments.date DURING LAST_30_DAYS

Không có chỉ số nào

Khi thực thi 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 UNKNOWN

Nếu một tài nguyên được trả về bằng loại dữ liệu enum UNKNOWN, thì điều này có nghĩa là loại dữ liệu này 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 giới thiệu 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 chỉ số khi 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 có khả năng tương thích ngược vì giá trị enum đã có sẵn. Chúng tôi sẽ giới thiệu các tài nguyên liên quan đến thay đổi này khi có để bạn có được thông tin 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 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 tài nguyên không còn được hỗ trợ chính thức.
Tài nguyên UNKNOWN có thể có các chỉ số chi tiết đí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.