新版 Search Ads 360 Reporting API 现已发布。这一新 API 提供
可以更灵活地生成自定义报告并将数据整合到您的报告应用程序中
和进程。详细了解如何迁移到和使用新版 Search Ads 360 报告
API。
如果您要申请对广告客户或引擎账号生成的小至审核报表，可以执行以下操作： 发送一个同步报告请求。为了响应请求，Search Ads 360 API 会以 JSON 对象的形式返回整个报告。同步请求：
如果您要请求大型广告客户或引擎账号报表，我们建议您使用异步 方法。
发出同步请求
致电Reports.generate()
以指定您要在广告客户或引擎账号报表中使用的数据类型。
Search Ads 360 会验证请求、生成报表，然后将报表作为报表资源返回 响应正文。
同步请求示例
下面是一个 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. }
使用 Search Ads 360 实用程序脚本发送此请求
要发送原始 JSON POST 请求，您可以使用 sa360Api.py 脚本如下：
- 复制示例 JSON 对象（两者之间的所有内容，包括两者之间的内容）
大括号中的内容）复制到名为
request.txt的新文本文件中。 - 将 JSON 代码中的代理机构 ID 更改为您自己的代理机构 ID。
- 移除所有评论，例如
// The date column segments the report by individual days. - 将您的 OAuth 2.0 凭据整合到一个以英文逗号分隔的字符串中，如下所示：
跟随：
client-ID,client-secret,refresh-token
（此字符串与您运行sa360Api.py --login时sa360Api.py输出的字符串相同，如设置 授权。） - 按如下方式调用
sa360Api.py：
sa360Api.py --cred CREDENTIALS --server API-method --post < request.txt
在上面的命令中，将CREDENTIALS替换成您在上一步中组建的字符串。
将API-method替换成下面框中的 POST 方法的名称。例如：
sa360Api.py --cred 123456789123.apps.googleusercontent.com,ABCDEFGHIJKLMNOPQR_abcdef,1/HIJklM01OPQR23NOP456rst890uvw --server https://www.googleapis.com/doubleclicksearch/v2/reports/generate --post < request.txt
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())
示例报告
对同步请求的响应是一个 report 对象。
如果请求成功验证，该对象中的前几个属性将包含
对您提交的请求进行了说明。报告本身位于对象的 rows 中。
属性。
{
"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
},
...
]
}
如果验证失败
如果报告未通过验证，Search Ads 360 会返回 HTTP 400 响应
以及一个错误对象。例如，上面的示例请求并未指定实际
代理机构：
{
"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."
}
}将同步报告拆分为多个响应
默认情况下，同步请求会返回前 10000 行。若要更改这种行为
请使用 Reports.request.startRow
和Reports.request.rowCount
属性检索报告的特定部分。
拆分同步报告的示例
例如，此请求将返回代理机构报表的前 100 行（0 到 99） （按天细分）：
{
"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
}
您可以再请求一次针对第 100 到 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
}