由於傳送大型報表的要求可能需要一段時間才能產生,因此 Search Ads 360 API 提供非同步技術,讓您要求及下載報表。使用這項技術時,您必須先傳送指定報表資料的初始要求,然後傳送額外的輪詢要求,直到 Search Ads 360 完成報表製作為止。 Search Ads 360 會根據報表大小,將資料分成多個檔案。報表產生後,您可以傳送要求來下載每個報表檔案。如要要求較少資料,您可以只傳送單一同步要求。
如何提出非同步要求
- 呼叫
Reports.request()
來指定您要在報表中的資料類型。如要瞭解可要求的資料類型,請參閱「報表類型」。Search Ads 360 驗證要求,並傳回報表 ID (這是該要求的專屬 ID)。
- 使用報表 ID 呼叫
Reports.get()
。Search Ads 360 的回應會指出:
- 報表是否可供下載。
- 報表準備就緒時,表示有一或多個用於下載報表的網址。
- 請呼叫
Reports.getFile()
下載編碼過的報表檔案,或直接透過網址下載。Search Ads 360 會以 UTF-8 編碼的檔案傳回報表。
要確認報表是否就緒,應多久進行一次意見調查?
Search Ads 360 產生報表所需的時間主要取決於報表中的資料量。建議您「每分鐘檢查一次」報表狀態,如果平均報表要求的完成時間明顯增加或減少,請調整頻率。
將非同步報表拆分為多個檔案
為回應非同步要求,Search Ads 360 會自動將大型報表分割成多個檔案。使用 Reports.request.maxRowsPerFile
屬性指定檔案大小上限。每個產生的報表檔案最多只能有 maxRowsPerFile
列報表列 (不含標頭)。系統會為每個檔案產生不同網址,並傳回給 Reports.get()
的回應。如要瞭解下載報表檔案的相關資訊,請參閱「下載報告」。
如果是 CSV 報表,每個檔案中的標題都會重複。
非同步範例
以下是使用非同步技巧的要求和回應範例。
JSON
POST https://www.googleapis.com/doubleclicksearch/v2/reports 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 }, "reportType": "keyword", // This report covers all keywords in the // advertiser specified in reportScope. "columns": [ { "columnName": "campaignId" }, // Here are some attribute columns available for keyword { "columnName": "keywordText" }, // reports. { "columnName": "keywordLandingPage" }, { "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": "visits last month" // 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" : "2012-05-02" // Alternatively, try the "changedMetricsSinceTimestamp" or "changedAttributesSinceTimestamp" // options. See Incremental reports. }, "filters": [ { "column" : { "columnName": "keywordLandingPage" }, "operator" : "startsWith", "values" : [ // With this filter, only keywords with landing pages "http://www.foo.com", // rooted at www.foo.com or www.bar.com are returned. "http://www.bar.com" // See Filtered reports. ] } ], "downloadFormat": "csv", "maxRowsPerFile": 6000000, // Required. See Splitting reports into multiple files. "statisticsCurrency": "agency", // Required. See Currency for statistics. "verifySingleTimeZone": false, // Optional. Defaults to false. See Time zone. "includeRemovedEntities": false // Optional. Defaults to false. }
Java
/** * Creates a campaign report request, submits the report, and returns the report ID. */ private static String createReport(Doubleclicksearch service) throws IOException { try { return service.reports().request(createSampleRequest()).execute().getId(); } 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 ID and name of all * campaigns under agency 12300000000000456 and advertiser 21700000000011523. * Substitute your own agency ID and advertiser IDs for the IDs in this sample. */ private static ReportRequest createSampleRequest() { return new ReportRequest() .setReportScope(new ReportScope() .setAgencyId(12300000000000456L) // Replace with your ID .setAdvertiserId(21700000000011523L)) // Replace with your ID .setReportType("campaign") .setColumns(Arrays.asList( new ReportApiColumnSpec[] { new ReportApiColumnSpec().setColumnName("campaignId"), new ReportApiColumnSpec().setColumnName("campaign") })) .setTimeRange(new TimeRange() .setStartDate("2012-05-01") .setEndDate("2012-05-01")) .setDownloadFormat("csv") .setStatisticsCurrency("usd") .setMaxRowsPerFile(5000000); }
.NET
這個函式會建立一份報表,當中列出廣告客戶的廣告活動,並將傳回的權杖指派給reportId
。 using api = Google.Apis.Doubleclicksearch.v2; /// <summary> /// Creates a report with a sample request and returns the report ID. /// </summary> /// <param name="service">Search Ads 360 API service.</param> private static string CreateReport(api.DoubleclicksearchService service) { var req = service.Reports.Request(CreateSampleRequest()); var report = req.Execute(); Console.WriteLine("Created report: ID={0}", report.Id); return report.Id; } /// <summary> /// Returns a simple static request that lists the ID and name of all /// campaigns under an advertiser. /// Substitute your own agency ID and advertiser IDs for the IDs in this sample. /// </summary> private static api.Data.ReportRequest CreateSampleRequest() { return new api.Data.ReportRequest { ReportScope = new api.Data.ReportRequest.ReportScopeData { AgencyId = 12300000000000456, // Replace with your ID AdvertiserId = 21700000000011523 // Replace with your ID }, ReportType = ReportType.CAMPAIGN, Columns = new List<api.Data.ReportApiColumnSpec> { new api.Data.ReportApiColumnSpec { ColumnName = "campaignId", }, new api.Data.ReportApiColumnSpec { ColumnName = "campaign", }, }, TimeRange = new api.Data.ReportRequest.TimeRangeData { StartDate = "2015-01-01", EndDate = "2015-01-07", }, DownloadFormat = "csv", StatisticsCurrency = "usd", MaxRowsPerFile = 5000000, }; }
Python
def request_report(service): """Request sample report and print the report ID that DS returns. See Set Up Your Application. Args: service: An authorized Doubleclicksearch service. Returns: The report id. """ request = service.reports().request( body= { "reportScope": { "agencyId": "12300000000000456", // Replace with your ID "advertiserId": "21700000000011523", // Replace with your ID "engineAccountId": "700000000073991" // Replace with your ID }, "reportType": "keyword", "columns": [ { "columnName": "campaignId" }, { "columnName": "keywordText" }, { "columnName": "keywordLandingPage" }, { "columnName": "date" }, { "columnName": "dfaRevenue" }, { "columnName": "visits", "startDate": "2013-01-01", "endDate": "2013-01-31", "headerText": "visits last month" } ], "timeRange" : { "startDate" : "2012-05-01", "endDate" : "2012-05-02" }, "filters": [ { "column" : { "columnName": "keywordLandingPage" }, "operator" : "startsWith", "values" : [ "http://www.foo.com", "http://www.bar.com" ] } ], "downloadFormat": "csv", "maxRowsPerFile": 6000000, "statisticsCurrency": "agency", "verifySingleTimeZone": "false", "includeRemovedEntities": "false" } ) json_data = request.execute() return json_data['id']
如果驗證成功
如果報表通過驗證,Search Ads 360 會傳回報表 ID。此外,Search Ads 360 也會傳回貨幣代碼和時區的中繼資料。
{ "kind": "adsdartsearch#report", "id": "MTMyNDM1NDYK", // This is the report id. "isReportReady": false, // The report is not finished generating. "request": { // The request that created this report. ... }, "statisticsCurrencyCode": "CAD", // The currency used for statistics. E.g., if // advertiser currency was requested, this would be // currency code of the advertiser in scope. "statisticsTimeZone": "America/New_York" // If all statistics in the report were sourced from // a single time zone, this would be it. If // verifySingleTimeZone was set to true in the request, // then this field will always be populated (or the // request will fail). }
如果驗證失敗
如果報表未通過驗證,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." } }
報表狀態意見調查
使用報表 ID 呼叫 Report.Get()
。
JSON
GET https://www.googleapis.com/doubleclicksearch/v2/reports/MTMyNDM1NDYK
Java
/** * Polls the reporting API with the reportId until the report is ready. * Returns the report. */ private static Report pollUntilReportIsFinished(Doubleclicksearch service, String reportId) throws IOException, InterruptedException { long delay = 1; while (true) { Report report = null; try { report = service.reports().get(reportId).execute(); } catch (GoogleJsonResponseException e) { System.err.println("Report generation has failed."); System.exit(e.getStatusCode()); } if (report.getIsReportReady()) { return report; } System.out.format("Report %s is not ready - waiting %s seconds.%n", reportId, delay); Thread.sleep(TimeUnit.SECONDS.toMillis(delay)); delay = delay + delay; // Double the delay for the next iteration. } }
.NET
using api = Google.Apis.Doubleclicksearch.v2; /// <summary> /// Polls until the report with the given ID completes. /// </summary> /// <param name="service">Search Ads 360 API service.</param> /// <param name="reportId">Report ID to poll.</param> /// <exception cref="ApplicationException"> /// Thrown when the report completes, but has failed. /// </exception> private static api.Data.Report PollUntilReportIsFinished( api.DoubleclicksearchService service, string reportId) { TimeSpan delay = TimeSpan.FromSeconds(1); while (true) { api.Data.Report report; try { report = service.Reports.Get(reportId).Execute(); } catch (Google.GoogleApiException ex) { throw new ApplicationException("Report generation failed", ex); } if (report.IsReportReady.GetValueOrDefault(false)) { return report; } Console.WriteLine("Report is not ready - waiting {0}", delay); Thread.Sleep(delay); delay = delay.Add(delay); // Double the delay for the next iteration. } }
Python
import pprint import simplejson from googleapiclient.errors import HttpError def poll_report(service, report_id): """Poll the API with the reportId until the report is ready, up to ten times. Args: service: An authorized Doubleclicksearch service. report_id: The ID DS has assigned to a report. """ for _ in xrange(10): try: request = service.reports().get(reportId=report_id) json_data = request.execute() if json_data['isReportReady']: pprint.pprint('The report is ready.') # For large reports, DS automatically fragments the report into multiple # files. The 'files' property in the JSON object that DS returns contains # the list of URLs for file fragment. To download a report, DS needs to # know the report ID and the index of a file fragment. for i in range(len(json_data['files'])): pprint.pprint('Downloading fragment ' + str(i) + ' for report ' + report_id) download_files(service, report_id, str(i)) # See Download the report. return else: pprint.pprint('Report is not ready. I will try again.') time.sleep(10) except HttpError as e: error = simplejson.loads(e.content)['error']['errors'][0] # See Response Codes pprint.pprint('HTTP code %d, reason %s' % (e.resp.status, error['reason'])) break
如果報表尚未備妥
如果報表尚未準備就緒,Search Ads 360 會傳回 HTTP 202
回應,而 isReportReady
欄位則為「false」。
{ "kind": "doubleclicksearch#report", "id": "MTMyNDM1NDYK", "isReportReady": false, "request": { ... }, ... }
報告準備就緒時
報表完成並可供下載時,isReportReady
欄位的值為 true。回應中還會有 files
這個額外欄位,其中包含用來下載報表檔案的網址。
{ "kind": "doubleclicksearch#report", "id": "MTMyNDM1NDYK", "isReportReady": true, "request": { ... }, ... "rowCount": 1329, // Total rows in the report, not counting headers. "files": [ { "url": "https://www.googleapis.com/doubleclicksearch/v2/reports/MTMyNDM1NDYK/files/0" "byteCount": "10242323" }, { "url": "https://www.googleapis.com/doubleclicksearch/v2/reports/MTMyNDM1NDYK/files/1" "byteCount": "10242323" } ], }
如果報表產生失敗
如果 Search Ads 360 無法產生報表,就會傳回其中一個 HTTP 錯誤代碼並附上說明。
{ "error" : { "code" : 410, // Or other error codes. "message" : "Processing was halted on the backend and will not continue." } }
如需 Search Ads 360 可能傳回的錯誤清單,請參閱回應代碼。
下載報表
如要下載報表,請點選各報表檔案網址,或用報表 ID 和檔案編號 (已編入索引) 來呼叫 Reports.getFile()
。Search Ads 360 會以 UTF-8 編碼的檔案傳回報表。
以下是 Reports.getFile()
要求的範例:
JSON
GET https://www.googleapis.com/doubleclicksearch/v2/reports/MTMyNDM1NDYK/files/0?alt=media和
GET https://www.googleapis.com/doubleclicksearch/v2/reports/MTMyNDM1NDYK/files/1?alt=media
Java
/** * Downloads the shards of a completed report to the given local directory. * Files are named CampaignReport0.csv, CampaignReport1.csv, and so on. */ private static void downloadFiles( Doubleclicksearch service, Report report, String localPath) throws IOException { for (int i = 0; i < report.getFiles().size(); i++) { FileOutputStream outputStream = new FileOutputStream(new File(localPath, "CampaignReport" + i)); service.reports().getFile(report.getId(), i).executeAndDownloadTo(outputStream); outputStream.close(); } }
.NET
using api = Google.Apis.Doubleclicksearch.v2; /// <summary> /// Downloads the shards of a completed report to the given local directory. /// Files are named CampaignReport0.csv, CampaignReport1.csv, and so on. /// </summary> /// <param name="service">Search Ads 360 API service.</param> /// <param name="report">Report ID to download.</param> /// <param name="localPath">Path of the directory to place downloaded files.</param> private static void DownloadFiles( api.DoubleclicksearchService service, api.Data.Report report, string localPath) { Directory.CreateDirectory(localPath); for (int i = 0; i < report.Files.Count; ++i) { string fileName = Path.Combine( localPath, string.Format("CampaignReport{0}.csv", i)); Console.WriteLine("Downloading shard {0} to {1}", i, fileName); using (Stream dst = File.OpenWrite(fileName)) { service.Reports.GetFile(report.Id, i).Download(dst); } } }
Python
def download_files(service, report_id, report_fragment): """Generate and print sample report. Args: service: An authorized Doubleclicksearch service. report_id: The ID DS has assigned to a report. report_fragment: The 0-based index of the file fragment from the files array. """ f = file('report-' + report_fragment + '.csv', 'w') request = service.reports().getFile_media(reportId=report_id, reportFragment=report_fragment) f.write(request.execute().decode('utf-8')) f.close()
範例報表
以下是 CSV 報表的範例。每個報表檔案片段都有專屬的標題列。如要進一步瞭解此格式,請參閱 RFC 4180。
keywordText,campaignId,landingPageUrl,day,revenue,visits last month,my revenue google,71700000002104742,http://www.google.com,2012-05-01,10.2,5,20 google,71700000002104742,http://www.google.com,2012-05-02,11,10,60.23
下載 ID 對應檔案
您可以下載舊版 Search Ads 360 與新版 Search Ads 360 之間的 ID 對應檔案。針對所要求的廣告客戶,檔案會納入舊版和新版 Search Ads 360 中的所有子實體 (例如引擎帳戶、廣告活動、廣告群組等)。
Python
def download_mapping_file(service, file_name, agency_id, advertiser_id): """Generate and save mapping file to a csv. Args: service: An authorized Doubleclicksearch service. file_name: Filename to write the ID mapping file. agency_id: DS ID of the agency. advertiser_id: DS ID of the advertiser. """ request = service.reports().getIdMappingFile_media(agencyId=agency_id, advertiserId=advertiser_id) response = request.execute() response = response.decode('utf-8') f = open(file_name + '.csv', 'w') f.write(response) f.close()