如果您要求中小型的廣告客戶或引擎帳戶報表進行管理,您可以 只傳送一個同步報表請求。為回應要求,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. }
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
屬性,以便在每次請求時擷取報表特定部分。
分割同步報表的範例
舉例來說,這項要求會傳回代理商報表的前百列 (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 }