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.
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 có quy mô nhỏ đến vừa phải, bạn có thể chỉ gửi một yêu cầu báo cáo đồng bộ. Để phản hồi 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ề báo cáo của nhà quảng cáo và tài khoản công cụ
- Chặn khách hàng của bạn cho đến khi Search Ads 360 tạo báo cáo
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ộ.
Để tạo yêu cầu đồng bộ
Gọi Reports.generate() để chỉ định loại dữ liệu mà bạn muốn trong 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 nội dung phản hồi.
Ví dụ về yêu cầu đồng bộ
Sau đây là ví dụ về yêu cầu Reports.generate().
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 một yêu cầu đồng bộ là một đối tượng báo cáo.
Nếu yêu cầu được xác thực thành công, một vài 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 mà bạn đã gửi. Báo cáo này nằm trong thuộc tính rows của đối tượng.
{
"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 xác thực thất bại
Nếu báo cáo không vượt qua được quy trình xác thực, Search Ads 360 sẽ trả về phản hồi HTTP 400 kèm theo đối tượng lỗi. Ví dụ: yêu cầu trong ví dụ ở trên không chỉ định một đại lý thực tế:
{
"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."
}
}
Tách 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 đó, hãy sử dụng thuộc tính Reports.request.startRow và Reports.request.rowCount để truy xuất các phần cụ thể của báo cáo theo mỗi yêu cầu.
Ví dụ về việc tách một báo cáo đồng bộ
Ví dụ: yêu cầu này sẽ trả về 100 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 với 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
}