API Báo cáo Search Ads 360 mới hiện đã ra mắt. API mới cung cấp
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 báo cáo
và quy trình. Tìm hiểu thêm về cách di chuyển sang và sử dụng Báo cáo Search Ads 360 mới
.
Nếu yêu cầu báo cáo tài khoản công cụ hoặc báo cáo nhà quảng cáo ở quy mô từ nhỏ đến trung bình, bạn có thể chỉ gửi một yêu cầu báo cáo đồng bộ, duy nhất. Để đáp ứng yêu cầu này, API Search Ads 360 sẽ trả về toàn bộ báo cáo trong một đối tượng JSON. Yêu cầu đồng bộ:
- Chỉ có thể trả về nhà quảng cáo và báo cáo tài khoản công cụ
- Chặn khách hàng cho đến khi Search Ads 360 tạo báo cáo
Nếu đang yêu cầu các báo cáo tài khoản công cụ hoặc báo cáo nhà quảng cáo lớn, bạn nên sử dụng báo cáo không đồng bộ .
Để thực hiện yêu cầu đồng bộ
Gọi cho Reports.generate()
để chỉ định loại dữ liệu mà bạn muốn đưa vào báo cáo nhà quảng cáo hoặc tài khoản công cụ.
Search Ads 360 xác thực yêu cầu, tạo báo cáo và trả về báo cáo dưới dạng tài nguyên Báo cáo trong phần nội dung phản hồi.
Ví dụ về yêu cầu đồng bộ
Sau đây là ví dụ về Reports.generate()
của bạn.
JSON
POST https://www.googleapis.com/doubleclicksearch/v2/reports/generate Authorization: Bearer your OAuth 2.0 access token Content-type: application/json { "reportScope": { "agencyId": "12300000000000456", // Replace with your ID "advertiserId": "21700000000011523", // Replace with your ID "engineAccountId": "700000000073991" // Replace with your ID }, "reportType": "account", // This report covers all revenue and visits in the // engine account specified in reportScope. "columns": [ { "columnName": "date" }, // The date column segments the report by individual days. { "columnName": "dfaRevenue" }, // Here are some metric columns available for keyword { // reports. "columnName": "visits", "startDate": "2013-01-01", // Each metric column can optionally specify its own start "endDate": "2013-01-31", // and end date; by default the report timeRange is used. "headerText": "January visits" // Every column can optionally specify a headerText, which // changes the name of the column in the report. } ], "timeRange" : { "startDate" : "2012-05-01", // Dates are inclusive and specified in YYYY-MM-DD format. "endDate" : "2013-05-01" // Alternatively, try the "changedMetricsSinceTimestamp" or "changedAttributesSinceTimestamp" // options. See Incremental reports. }, "statisticsCurrency": "agency", // Required. See Currency for statistics. "verifySingleTimeZone": false, // Optional. Defaults to false. See Time zone. "includeRemovedEntities": false // Optional. Defaults to false. }
Java
public static void main(String[] args) throws Exception { Doubleclicksearch service = getService(); // See Set Up Your Application. Report report = generateAccountReport(service); outputReport(report, "./"); } /** * Creates an account report using the synchronous Report.generate method. * * @throws IOException */ private static Report generateAccountReport(Doubleclicksearch service) throws IOException { try { return service.reports().generate(generateAccountRequest()).execute(); } catch (GoogleJsonResponseException e) { System.err.println("Report request was rejected."); for (ErrorInfo error : e.getDetails().getErrors()) { System.err.println(error.getMessage()); } System.exit(e.getStatusCode()); return null; // Unreachable code. } } /** * Creates a simple static request that lists the clicks and visits for an engine account. Use * your own agency ID, advertiser ID, and engine account ID. */ private static ReportRequest generateAccountRequest() { return new ReportRequest().setReportScope( new ReportScope() .setAgencyId(20700000000000451L) // Replace with your ID .setAdvertiserId(21700000000010391L) // Replace with your ID .setEngineAccountId(700000000042201L)) // Replace with your ID .setReportType("account") .setColumns(Arrays.asList(new ReportApiColumnSpec[] { new ReportApiColumnSpec().setColumnName("date"), new ReportApiColumnSpec().setColumnName("dfaRevenue"), new ReportApiColumnSpec() .setColumnName("visits") .setHeaderText("January visits") .setStartDate("2013-01-01") .setEndDate("2013-01-31"),})) .setTimeRange(new TimeRange() .setStartDate("2012-05-01") .setEndDate("2013-05-01")) .setStatisticsCurrency("agency"); } /** * Outputs a synchronous report to a file. */ private static void outputReport(Report report, String localPath) throws IOException { FileOutputStream outputStream = new FileOutputStream(new File(localPath, "Report")); final PrintStream printStream = new PrintStream(outputStream); printStream.print(report); printStream.close(); }
Python
def generate_report(service):
"""Generate and print sample report.
Args:
service: An authorized Doubleclicksearch service. See Set Up Your Application.
"""
request = service.reports().generate(
body=
{
"reportScope
"agencyId": "12300000000000456", // Replace with your ID
"advertiserId": "21700000000011523", // Replace with your ID
"engineAccountId": "700000000073991" // Replace with your ID
},
"reportType": "account",
"columns": [
{ "columnName": "date" },
{ "columnName": "dfaRevenue" },
{
"columnName": "visits",
"startDate": "2013-01-01",
"endDate": "2013-01-31",
"headerText": "January visits"
}
],
"timeRange" : {
"startDate" : "2012-05-01",
"endDate" : "2013-05-01"
},
"statisticsCurrency": "agency",
"verifySingleTimeZone": "false",
"includeRemovedEntities": "false"
}
)
pprint.pprint(request.execute())
Báo cáo mẫu
Phản hồi cho yêu cầu đồng bộ là đối tượng báo cáo.
Nếu yêu cầu được xác thực thành công, một số thuộc tính đầu tiên trong đối tượng sẽ chứa siêu dữ liệu
mô tả yêu cầu bạn đã gửi. Bản thân báo cáo nằm trong rows của đối tượng
thuộc tính này.
{
"kind":"doubleclicksearch#report",
"request":{
"columns":[
{"columnName":"date"},
{"columnName":"dfaRevenue"},
{"columnName":"visits","endDate":"2013-01-31","headerText":"visits last month","startDate":"2013-01-01"}
],
"includeDeletedEntities":false,
"reportScope":{
"agencyId":"12300000000000456",
"advertiserId":"21700000000011523",
"engineAccountId":"700000000073991"
},
"reportType":"account",
"rowCount":10000,
"startRow":0,
"statisticsCurrency":"agency",
"timeRange":{
"endDate":"2013-05-01",
"startDate":"2012-05-01"
}
},
"rowCount":366,
"rows":[
{
"date":"2012-05-01",
"dfaRevenue":0.0,
"visits last month":0.0
},
{
"date":"2012-05-02",
"dfaRevenue":0.0,
"visits last month":0.0
},
{
"date":"2012-05-03",
"dfaRevenue":0.0,
"visits last month":0.0
},
{
"date":"2012-05-04",
"dfaRevenue":0.0,
"visits last month":0.0
},
...
]
}
Nếu không xác thực được
Nếu báo cáo không vượt qua quy trình xác thực, Search Ads 360 sẽ trả về phản hồi HTTP 400
có đối tượng lỗi. Ví dụ: yêu cầu mẫu ở trên không chỉ định một thực
đại lý:
{
"error": {
"code": 400,
"message": "statisticsCurrency: the agency in scope does not have a valid currency. Please make sure the agency is properly initialized in Search Ads 360."
}
}Chia các báo cáo đồng bộ thành nhiều phản hồi
Theo mặc định, yêu cầu đồng bộ sẽ trả về 10.000 hàng đầu tiên. Để thay đổi hành vi đó,
sử dụng Reports.request.startRow
và Reports.request.rowCount
để truy xuất các phần cụ thể của báo cáo theo từng yêu cầu.
Ví dụ về cách tách một báo cáo đồng bộ
Ví dụ: yêu cầu này sẽ trả về một trăm hàng đầu tiên (0 đến 99) của một báo cáo đại lý được phân đoạn theo ngày:
{
"reportScope": {
"agencyId": "12300000000000456", // Replace with your ID
"advertiserId": "21700000000011523", // Replace with your ID
"engineAccountId": "700000000073991" // Replace with your ID
},
"reportType": "account",
"columns": [
{ "columnName": "date" },
{ "columnName": "dfaRevenue" }
],
"timeRange" : {
"startDate" : "2012-05-01",
"endDate" : "2013-05-01"
},
"startRow":"0",
"rowCount":"100",
"statisticsCurrency": "agency",
"verifySingleTimeZone": false,
"includeRemovedEntities": false
}
Bạn có thể thực hiện theo yêu cầu này bằng một yêu cầu khác cho các hàng từ 100 đến 199:
{
"reportScope": {
"agencyId": "12300000000000456", // Replace with your ID
"advertiserId": "21700000000011523", // Replace with your ID
"engineAccountId": "700000000073991" // Replace with your ID
},
"reportType": "account",
"columns": [
{ "columnName": "date" },
{ "columnName": "dfaRevenue" }
],
"timeRange" : {
"startDate" : "2012-05-01",
"endDate" : "2013-05-01"
},
"startRow":"100",
"rowCount":"100",
"statisticsCurrency": "agency",
"verifySingleTimeZone": false,
"includeRemovedEntities": false
}