Yêu cầu báo cáo
Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang
Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.
API Báo cáo Search Ads 360 mới hiện đã ra mắt. API mới mang đến
khả năng linh hoạt hơn nữa trong việc xây dựng các báo cáo tuỳ chỉnh và tích hợp dữ liệu vào các ứng dụng
và quy trình báo cáo. Hãy tìm hiểu thêm về việc di chuyển sang và sử dụng
API Báo cáo Search Ads 360
mới.
Sau khi thiết lập ứng dụng khách như mô tả trong phần Ứng dụng đầu tiên của tôi, bạn có thể sử dụng API Search Ads 360
để yêu cầu và tải báo cáo xuống. Bạn có thể đưa ra một trong các loại yêu cầu sau:
- Đồng bộ
Chỉ cần một yêu cầu duy nhất và trả về báo cáo ở định dạng JSON. Yêu cầu đồng bộ:
Nếu đang yêu cầu báo cáo tài khoản công cụ hoặc nhà quảng cáo lớn, bạn nên sử dụng phương pháp không đồng bộ.
- Không đồng bộ
Yêu cầu bạn gửi yêu cầu ban đầu chỉ định dữ liệu bạn muốn có trong báo cáo. Sau đó, bạn gửi thêm các yêu cầu để thăm dò ý kiến về Search Ads 360. Khi Search Ads 360 tạo xong báo cáo, bạn sẽ gửi yêu cầu tải báo cáo xuống dưới dạng một hoặc nhiều tệp. Yêu cầu không đồng bộ:
- Có thể trả về bất kỳ loại báo cáo nào
- Phân đoạn các báo cáo rất lớn thành nhiều tệp
- Định dạng báo cáo dưới dạng CSV hoặc TSV
Mô hình dữ liệu: hàng và cột
Search Ads 360 sắp xếp dữ liệu trong báo cáo thành các hàng và cột.
Loại báo cáo mà bạn yêu cầu xác định các hàng được trả về.
Ví dụ: nếu bạn yêu cầu báo cáo từ khoá, thì mỗi hàng sẽ chứa dữ liệu về một từ khoá. Hãy xem tài liệu tham khảo về Loại báo cáo để biết danh sách tất cả các loại báo cáo.
Bạn chỉ định cột mà bạn muốn đưa vào báo cáo bằng cách đặt tên cho từng cột
trong yêu cầu báo cáo. Hãy xem tài liệu tham khảo về Loại báo cáo để biết danh sách các cột có thể được trả về cho từng loại báo cáo.
Hoạt động của cột
Hành vi của một cột phụ thuộc vào loại dữ liệu mà cột đó chứa (tài liệu tham khảo Loại báo cáo cho biết hành vi của từng cột):
Cột thuộc tính. Cột thuộc tính chứa dữ liệu giúp định cấu hình
hoặc xác định một thực thể trong chiến dịch, chẳng hạn như tên chiến dịch hoặc giá thầu từ khoá. API Search Ads 360 luôn trả về giá trị hiện tại cho một cột thuộc tính, bất kể ngày hoặc phạm vi ngày bất kỳ được chỉ định trong yêu cầu. Ví dụ: nếu ngày hôm qua, bạn đã thay đổi giá thầu của từ khoá từ
2,00 thành 1,50, sau đó yêu cầu báo cáo dữ liệu của tháng trước, báo cáo
sẽ trả về giá trị là 1,5 cho giá thầu từ khoá.
Cột chỉ số. Cột chỉ số chứa dữ liệu về hiệu suất
của chiến dịch, chẳng hạn như số lượt nhấp vào quảng cáo, số lượt truy cập do thẻ Floodlight ghi lại
hoặc doanh thu. Trừ phi bạn chỉ định phạm vi thời gian là của một ngày, API sẽ trả về giá trị tổng hợp cho các cột chỉ số. Ví dụ: nếu bạn yêu cầu báo cáo cho dữ liệu của tháng trước, thì API sẽ trả về tổng số lượt nhấp của tháng trước.
Cột phân đoạn. Cột phân đoạn chia dữ liệu thành các hàng riêng biệt.
Ví dụ: date là cột phân đoạn mà bạn có thể chỉ định cho nhiều
loại báo cáo. Nếu bạn chỉ định cột date trong báo cáo từ khoá có phạm vi ngày từ 2013-01-01 đến 7-01-2013, thì API sẽ trả về 7 hàng cho mỗi từ khoá, mỗi hàng tương ứng với một ngày và hiển thị các chỉ số cho ngày đó. Hãy xem Báo cáo đã phân đoạn.
Đơn vị tiền tệ
Bạn phải chỉ định đơn vị tiền tệ của dữ liệu tiền tệ (cả các thuộc tính như dailyBudget và các chỉ số như
cost). Bạn có thể chỉ định một trong các yếu tố sau:
- Đơn vị tiền tệ của công ty quảng cáo, nếu báo cáo thuộc phạm vi
của một công ty quảng cáo, nhà quảng cáo hoặc tài khoản công cụ.
- Đơn vị tiền tệ của nhà quảng cáo, nếu báo cáo phạm vi một tài khoản nhà quảng cáo hoặc công cụ.
- Đơn vị tiền tệ của tài khoản công cụ, nếu báo cáo chỉ dành cho một tài khoản công cụ.
- USD
Sử dụng thuộc tính yêu cầu Reports.request.statisticsCurrency để chỉ định đơn vị tiền tệ.
Bản thân báo cáo sẽ cho biết đơn vị tiền tệ trong thuộc tính Reports.statisticsCurrencyCode.
Múi giờ
Các chỉ số của Search Ads 360 được lưu trữ ở dạng ngày không có múi giờ. Những ngày này tương ứng với múi giờ
của tài khoản công cụ đối với các chỉ số về công cụ (chẳng hạn như số lượt nhấp, số lượt hiển thị và số lượt truy cập) và
múi giờ của mạng Campaign Manager cho các chỉ số về lượt chuyển đổi (chẳng hạn như các hành động,
giao dịch và doanh thu). Khi mọi chỉ số trong một báo cáo đều đến từ cùng một múi giờ,
múi giờ đó sẽ được trả về trong yêu cầu. Nếu không, hệ thống sẽ không trả về múi giờ.
Các yêu cầu của bạn có thể đặt Reports.request.verifySingleTimeZone: true thành những báo cáo không thành công trình bày chỉ số từ nhiều múi giờ.
Nếu tất cả các chỉ số có trong báo cáo đều thuộc một múi giờ, thì múi giờ đó sẽ được trả về theo Reports.statisticsTimeZoneReports.
Trừ phi có lưu ý khác, nội dung của trang này được cấp phép theo Giấy phép ghi nhận tác giả 4.0 của Creative Commons và các mẫu mã lập trình được cấp phép theo Giấy phép Apache 2.0. Để biết thông tin chi tiết, vui lòng tham khảo Chính sách trang web của Google Developers. Java là nhãn hiệu đã đăng ký của Oracle và/hoặc các đơn vị liên kết với Oracle.
Cập nhật lần gần đây nhất: 2025-08-29 UTC.
[null,null,["Cập nhật lần gần đây nhất: 2025-08-29 UTC."],[[["\u003cp\u003eThe new Search Ads 360 Reporting API offers enhanced flexibility for building custom reports and integrating data into your workflows.\u003c/p\u003e\n"],["\u003cp\u003eYou can make synchronous requests for quick advertiser and engine account reports, or asynchronous requests for larger reports and various report types.\u003c/p\u003e\n"],["\u003cp\u003eReports are organized into rows based on the report type and columns that you specify in your request, with attribute, metric, and segment columns behaving differently.\u003c/p\u003e\n"],["\u003cp\u003eWhen requesting reports, you need to specify the currency for monetary data, and Search Ads 360 handles time zones based on engine and conversion metric sources.\u003c/p\u003e\n"]]],["The Search Ads 360 Reporting API allows custom report building and data integration. Reports can be requested synchronously (limited to advertiser/engine account reports, JSON format, blocking) or asynchronously (all report types, CSV/TSV format, multiple files). Data is organized in rows and columns; column behavior varies by type (attribute, metric, segment). Currency for monetary data must be specified and can be the agency's, advertiser's, or engine account's or USD. Time zones are relevant to metric dates.\n"],null,["# Request Reports\n\nThe new Search Ads 360 Reporting API is now available. The new API provides enhanced flexibility to build custom reports and integrate the data into your reporting applications and processes. Learn more about migrating to and using the [new Search Ads 360 Reporting\nAPI](https://developers.google.com/search-ads/reporting/overview).\n\n\nAfter you've set up your client app as described in [My First App](/search-ads/v2/first-app), you can use the Search Ads 360 API\nto request and download reports. You can make either of the following types of\nrequests:\n\n**[Synchronous](/search-ads/v2/how-tos/reporting/synchronous-requests)**\n\n: Requires just a single request and returns the report in a JSON-formatted response. Synchronous requests:\n\n - Can return only [advertiser](/search-ads/v2/report-types/advertiser) and [engine account](/search-ads/v2/report-types/account) reports\n - Block your client until Search Ads 360 generates the report\n\n\n If you're requesting large advertiser or engine-account reports, we recommend the\n asynchronous approach.\n\n**[Asynchronous](/search-ads/v2/how-tos/reporting/asynchronous-requests)**\n\n: Requires you to send an initial request that specifies the data you want in the\n report. Then you send additional requests to poll Search Ads 360. When Search Ads 360 finishes generating the report,\n you send requests to download the report as one or more files. Asynchronous requests:\n\n - Can return any [report type](/search-ads/v2/report-types)\n - Shards very large reports into multiple files\n - Formats reports as CSV or TSV\n\n### Data model: rows and columns\n\nSearch Ads 360 organizes data in a report into rows and columns.\nThe type of report you request determines the **rows** that are returned.\nFor example, if your request a keyword report, each row will contain data about a single\nkeyword. See the [Report Types](/search-ads/v2/report-types)\nreference for a list of all report types.\nYou specify which **columns** you want in the report by naming each column\nin your report request. See the [Report\nTypes](/search-ads/v2/report-types) reference for the list of columns that can be returned for each report type.\n\n### Column behaviors\n\n\nThe behavior of a column depends on the type of data that the column\ncontains (the [Report Types](/search-ads/v2/report-types) reference\ndisplays each column's behavior):\n\n-\n **Attribute columns**. An attribute column contains data that configures\n or identifies an entity in a campaign, such as the campaign name or a keyword bid. The Search Ads 360 API\n always returns the current value for an attribute column, regardless of any date or\n date range specified in a request. For example, if you changed a keyword's bid from\n 2.00 to 1.50 yesterday and then request a report for last month's data, the report\n will return a value of 1.50 for the keyword bid.\n\n-\n **Metric columns** . A metric column contains data about your campaign's\n performance, such as the number of clicks on an ad, the number of visits as recorded\n by a Floodlight tag, or revenue. Unless you [specify a\n time range](/search-ads/v2/reference/reports#request.timeRange) of a single day, the API returns an aggregate value for metric columns. For\n example, if you request a report for last month's data, the API will return the total\n number of clicks for last month.\n\n-\n **Segment columns** . A segment column splits data into separate rows.\n For example, `date` is a segment column that you can specify for many\n types of reports. If you specify the `date` column in a keyword report\n with a date range 2013-01-01 to 2013-01-07, the API would return seven rows for each\n keyword, each corresponding to one day and displaying metrics for that day. See [Segmented\n Reports](/search-ads/v2/how-tos/reporting/segmented-reports).\n\n### Currencies\n\n\nYour report request is required to specify the currency of monetary data (both attributes like `dailyBudget` and metrics like\n`cost`). You can specify one of the following:\n\n- The agency's currency, if the report is [scoped](/search-ads/v2/reference/reports#request.reportScope) to an agency, advertiser, or engine account.\n- The advertiser's currency, if the report is scoped to an advertiser or engine account.\n- The engine account's currency, if the report is scoped to an engine account.\n- USD\n\n\nUse the [Reports.request.statisticsCurrency](/search-ads/v2/reference/reports#request.statisticsCurrency)\nrequest property to specify a currency.\n\n\nThe report itself will indicate the currency in the ` `[Reports.statisticsCurrencyCode](/search-ads/v2/reference/reports#statisticsCurrencyCode) property.\n\n### Time zone\n\n\nSearch Ads 360 metrics are stored in dates without time zones. These dates correspond to the engine\naccount time zone for engine metrics (such as clicks, impressions, and visits), and\nCampaign Manager network time zone for conversion metrics (such as actions,\ntransactions and revenue). When every metric in a report comes from the same time zone,\nthat time zone will be returned in the request. Otherwise, no time zone will be returned.\nYour requests can set [Reports.request.verifySingleTimeZone](/search-ads/v2/reference/reports#request.verifySingleTimeZone)`: true`\nto fail reports that present metric from more than one time zone.\n\n\nIf all metrics present in a report are from one time zone, that time zone is\nreturned in [Reports.statisticsTimeZoneReports](/search-ads/v2/reference/reports#statisticsTimeZone)."]]
