Karena permintaan untuk laporan berukuran besar dapat memerlukan waktu beberapa saat, Search Ads 360 API menyediakan teknik asinkron untuk meminta dan mengunduh laporan. Dengan ini Anda mengirim permintaan awal yang menetapkan data yang Anda inginkan dalam laporan, lalu mengirim permintaan polling tambahan hingga Search Ads 360 selesai membuat laporan. Bergantung pada ukuran laporan, Search Ads 360 membagi data menjadi beberapa file. Setelah laporan dibuat, Anda mengirim permintaan untuk mengunduh setiap file laporan. Jika Anda meminta jumlah data yang lebih sedikit, Anda dapat mengirim satu permintaan permintaan.
Untuk membuat permintaan asinkron
- Telepon
Reports.request()
untuk menentukan jenis data yang Anda inginkan dalam laporan. Lihat Jenis Laporan untuk mengetahui jenis data yang Anda dapat meminta.Search Ads 360 akan memvalidasi permintaan tersebut dan menampilkan ID laporan, yaitu ID unik untuk permintaan ini permintaan.
- Telepon
Reports.get()
dengan ID laporan.Respons dari Search Ads 360 menunjukkan:
- Apakah laporan siap didownload.
- Jika laporan sudah siap, satu atau beberapa URL untuk mendownload laporan.
- Telepon
Reports.getFile()
untuk mengunduh file laporan yang dienkode, atau langsung mengunduhnya dari URL.Search Ads 360 akan menampilkan laporan dalam file yang berenkode UTF-8.
Seberapa sering saya harus melakukan polling laporan untuk mengetahui apakah laporan tersebut siap?
Waktu yang diperlukan Search Ads 360 untuk membuat laporan sebagian besar bergantung pada jumlah data di dalam laporan. Coba lakukan polling untuk mengetahui status laporan sekali per menit, lalu menyesuaikan frekuensi jika permintaan laporan rata-rata memerlukan lebih banyak atau lebih sedikit waktu secara signifikan hingga selesai.
Memisahkan laporan asinkron menjadi beberapa file
Sebagai respons terhadap permintaan asinkron, Search Ads 360 secara otomatis membagi laporan besar menjadi
beberapa file. Menggunakan Reports.request.maxRowsPerFile
untuk menentukan ukuran file maksimum. Setiap file laporan yang dihasilkan dijamin memiliki
maksimal maxRowsPerFile
baris laporan (tidak termasuk header). URL yang berbeda
dibuat untuk setiap file dan ditampilkan sebagai respons terhadap Reports.get()
. Untuk informasi
tentang mengunduh file laporan, lihat Download
laporan.
Untuk laporan CSV, header diulang di setiap file.
Contoh Asinkron
Berikut adalah contoh permintaan dan respons menggunakan teknik asinkron.
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
Fungsi ini membuat laporan yang mencantumkan kampanye di bawah pengiklan dan menetapkan token yang ditampilkan kereportId
.
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']
Jika validasi berhasil
Jika laporan lulus validasi, Search Ads 360 akan menampilkan ID laporan. Search Ads 360 juga mengembalikan metadata kode mata uang dan zona waktu.
{ "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). }
Jika validasi gagal
Jika laporan tidak lulus validasi, Search Ads 360 akan menampilkan respons 400
HTTP
dengan objek error. Misalnya, contoh permintaan di atas tidak menentukan
agensi:
{ "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." } }
Polling untuk status laporan
Panggil Report.Get()
dengan ID laporan.
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
Jika laporan belum siap
Jika laporan belum siap, Search Ads 360 akan menampilkan respons 202
HTTP, dan isReportReady
adalah false.
{ "kind": "doubleclicksearch#report", "id": "MTMyNDM1NDYK", "isReportReady": false, "request": { ... }, ... }
Saat laporan sudah siap
Saat laporan selesai dan siap didownload, isReportReady
adalah true (benar). Respons juga memiliki kolom tambahan, files
,
yang berisi URL untuk mendownload file laporan.
{ "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" } ], }
Jika pembuatan laporan gagal
Jika tidak dapat membuat laporan, Search Ads 360 akan menampilkan salah satu dari beberapa kode error, beserta deskripsi.
{ "error" : { "code" : 410, // Or other error codes. "message" : "Processing was halted on the backend and will not continue." } }
Lihat Kode Respons untuk mengetahui daftar error yang dapat ditampilkan Search Ads 360.
Download laporannya
Anda dapat mendownload laporan dengan langsung mengklik setiap URL file laporan, atau dengan memanggil Reports.getFile()
dengan
ID laporan dan nomor file (0 diindeks). Search Ads 360 akan menampilkan laporan dalam file yang berenkode UTF-8.
Berikut adalah contoh permintaan 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()
Contoh laporan
Berikut adalah contoh laporan CSV. Setiap fragmen file laporan memiliki header-nya sendiri baris. Untuk detail tentang format ini, lihat 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
Download file pemetaan ID
Anda dapat mendownload file yang berisi pemetaan ID antara Search Ads 360 versi sebelumnya dan Search Ads 360 versi baru. Untuk pengiklan yang diminta, file mencakup semua entitas turunan (mis. akun mesin, kampanye, grup iklan, dll.) yang ada di Search Ads 360 versi sebelumnya dan Search Ads 360 versi baru.
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()