이제 새 Search Ads 360 Reporting API를 사용할 수 있습니다. 새로운 API는
맞춤 보고서를 작성하고 보고 애플리케이션에 데이터를 통합할 수 있는 유연성 향상
프로세스입니다 새 Search Ads 360 보고서로 이전하고 이를 사용하는 방법에 대해 자세히 알아보기
API를 참고하세요.
대용량 보고서의 요청은 생성하는 데 시간이 걸릴 수 있으므로 Search Ads 360 API는 는 보고서 요청 및 다운로드를 위한 비동기 기법을 제공합니다. 이 보고서에서 원하는 데이터를 지정하는 초기 요청을 보내고, Search Ads 360에서 보고서 생성을 완료할 때까지 추가 폴링 요청을 보냅니다. 보고서의 크기에 따라 Search Ads 360에서는 데이터를 여러 파일로 분할합니다. 일단 보고서가 생성되면 각 보고서 파일을 다운로드하라는 요청을 보냅니다. 만약 더 적은 양의 데이터를 요청하는 경우 단일 동기식 요청을 참조하세요.
비동기식 요청을 하려면
Reports.request()에 전화 걸기 보고서에 포함할 데이터 유형을 지정합니다. 관리하는 데이터 유형은 보고서 유형을 참조하세요. 요청할 수 있습니다Search Ads 360에서 요청을 검증하고 이에 대한 고유 식별자인 보고서 ID를 반환합니다. 합니다.
Reports.get()에 전화 걸기 보고서 ID로 바꿉니다.Search Ads 360의 응답은 다음과 같습니다.
- 보고서를 다운로드할 준비가 되었는지 여부입니다.
- 보고서가 준비되면 보고서를 다운로드할 하나 이상의 URL입니다.
Reports.getFile()에 전화 걸기 인코딩된 보고서 파일을 다운로드하거나 URL에서 직접 다운로드할 수 있습니다.Search Ads 360은 UTF-8로 인코딩된 파일로 보고서를 반환합니다.
보고서가 준비되었는지 확인하려면 얼마나 자주 보고서를 폴링해야 하나요?
Search Ads 360에서 보고서를 생성하는 데 필요한 시간은 주로 보고서의 데이터 양에 따라 있습니다. 1분에 한 번 보고서 상태를 폴링한 다음 평균적인 보고서 요청에 걸리는 시간이 훨씬 더 길거나 짧으면 빈도를 조정합니다. 완료합니다.
비동기 보고서를 여러 파일로 분할하기
비동기식 요청에 대한 응답으로 Search Ads 360에서는 자동으로 대용량 보고서를
여러 파일이 있습니다 Reports.request.maxRowsPerFile 사용
속성을 사용하여 최대 파일 크기를 지정합니다. 각 결과 보고서 파일에는
최대 maxRowsPerFile개의 보고서 행 (헤더는 포함되지 않음)을 포함할 수 있습니다. 다른 URL
각 파일에 대해 생성되고 Reports.get()에 대한 응답으로 반환됩니다. 정보
자세한 내용은 보고서 다운로드
보고서를 참조하세요.
CSV 보고서의 경우 각 파일에서 헤더가 반복됩니다.
참고: API는 비동기식 요청에 대한 페이징을 지원하지 않습니다. 즉, 어떤 행을 반환할지 지정할 수 없습니다.
원하는 보고서 파일을 선택합니다. 파일 간에 행이 분할되는 방식은 다음과 같습니다.
임의적이며 동일한 보고서가 다시 실행될 경우 변경될 수 있습니다.
비동기 예
다음은 비동기 기법을 사용한 샘플 요청 및 응답입니다.
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. }
자바
/** * 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
자바
/** * 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도 있습니다.
보고서 파일을 다운로드하기 위한 URL을 포함합니다.
{
"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."
}
}
응답 코드에서 오류를 반환합니다.
보고서 다운로드
각 보고서 파일 URL을 직접 누르거나 다음을 사용하여 Reports.getFile()를 호출하여 보고서를 다운로드할 수 있습니다.
보고서 ID와 파일 번호 (0으로 색인이 생성됨) 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
자바
/** * 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 요청된 광고주의 경우 파일에는 모든 하위 항목 (예: 엔진 계정, 캠페인, 광고 그룹 등)를 설정할 수 있습니다. 새 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()