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 dưới đây để tìm hiểu cách tạo báo cáo về kết quả tìm kiếm trong quảng cáo Tìm kiếm API Báo cáo 360.

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. Nội dung tìm kiếm được chuyển vào 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 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 đố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 dò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 và một đối tượng metrics có nhóm 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 bằng 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ộ đệ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 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ì loại bỏ thời gian trọn vòng trên mạng để yêu cầu các trang riêng lẻ. Bạn nên dùng SearchStream cho tất cả các báo cáo có hơn 10.000 hàng. Không có thay đổi nào đáng kể sự khác biệt về hiệu suất giữa các phương pháp 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 thao tác 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

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

Yêu cầu bao gồm một HTTP POST đến API Báo cáo Search Ads 360 máy chủ của bạn 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ụ 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ý 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 mà truy vấn trả về. Từng đố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 SELECT mệnh đề không được điền sẵn trong các đối tượng trong phản hồi.

Ví dụ: truy vấn bên dưới điền mỗi đối tượng SearchAds360Row chỉ bằ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, đều 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 đúng 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. Các trang segments và metrics liệt kê tất cả các phân đoạn và trường 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 nên không sử dụng được với nhau, trong khi các ứng dụng khác hoàn toàn tương thích và bổ trợ cho nhau. Một trang tài nguyên bao gồm những thông tin sau (nếu có) và phù hợp) và hơn thế nữa:

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 liên kết 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. Điều này có nghĩa là bạn có thể bao gồm các trường như campaign.id và campaign.bidding_strategy_type trong 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ất cả tài nguyên đều 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 Resource trường (Trường tài nguyên). Mỗi trường tài nguyên đều liên kết đến các thông tin chi tiết khác về trường này, bao gồm mô tả, danh mục, loại dữ liệu, loại URL và 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 bằng một tài nguyên nhất định.

Cột Phân đoạn liệt kê những trường segments mà bạn có thể dùng trong cùng mệnh đề SELECT với các trường của tài nguyên. Mỗi trường đều liên kết đến toàn bộ thông tin chi tiết về trường, bao gồm 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, sắp xếp và lặp lại. Nếu bạn bằng cách sử dụng tài nguyên trong mệnh đề FROM, bạn có thể 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 tất cả các trường chỉ số đều có thể chọn bằng 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ể dùng trong cùng mệnh đề SELECT với các trường của tài nguyên. Mỗi trường đều liên kết đến toàn bộ thông tin chi tiết về trường, bao gồm 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, sắp xếp và lặp lại. Nếu bạn sử dụng tài nguyên trong mệnh đề FROM, hãy 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 trường tài nguyên campaign, như campaign.name, thời điểm 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ào ngày, bởi 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ất cả các tài nguyên đều 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ố.

Trang segments bao gồm một phần Có thể chọn có thể mở rộng cho mỗi 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à 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 của mình bằng cách thêm một 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, dẫn đến một báo cáo có một hàng cho impressions của mỗi truy vấn 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ả mà SearchAds360Service.SearchStream trả về có vẻ giống nhau 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 truy cập vào segments để biết danh sách trường phân đoạn 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. Chiến lược phát hành đĩa đơn phản hồi chứa một đối tượng SearchAds360Row cho mỗi kết hợp của thuộc tính 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 mỗi kết hợp 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 ngầm phân đoạn theo từng phiên bản của biến thể chứ không phải theo giá trị của từng trường đã chọn.

Truy vấn ví dụ sau dẫn đến một hàng cho mỗi chiến dị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 FROM mệnh đề. 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 ẩn sử dụng mẫu 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 cốt lõi

Bạn có thể sử dụng phân đoạn ngày chính trong mệnh đề WHERE để chỉ định ngày hoặc khoảng thời gian cụ thể.

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ố của chiến dịch clicks 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 trường hợp ngoại lệ đối với quy tắc chung mà 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 vào trong mệnh đề SELECT. Xem phần Lọc bị cấm để tìm hiểu thêm của bạn.

Quy tắc chính của 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 đề 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 ví dụ này trả về các chỉ số clicks theo tên chiến dịch trong ngày dải ô. 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ề clicks chỉ số 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'
```

Các 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 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 tính hôm nay.
`LAST_BUSINESS_WEEK`	5 ngày làm việc tuần 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, ngoại trừ hôm nay.
`LAST_30_DAYS`	30 ngày trước, ngoại trừ 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 tuần 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 tuần 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ố

Khi thực thi truy vấn, bạn có thể gặp các chỉ số có giá trị bằng 0 cho 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ủa bạn.

Loại enum KHÔNG XÁC ĐỊNH

Nếu một tài nguyên được trả về có kiểu 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. Những tài nguyên này có thể có đượ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 bạn đang truy vấn.

Bạn vẫn có thể chọn 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:

Tài nguyên thuộc loại UNKNOWN có thể được hỗ trợ sau này, nhưng vẫn có thể 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. Những đối tượng này khả năng tương thích ngược vì giá trị enum đã có sẵn. Chúng tôi giới thiệu các tài nguyên khác với thay đổi này ngay khi có sẵn để bạn có chế độ xem tài khoản của bạn. Tài nguyên UNKNOWN có thể xuất hiện do trong tài khoản của bạn thông qua các giao diện khác hoặc vì 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ó đính kèm các chỉ số chi tiết 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.