이제 새 Search Ads 360 Reporting API를 사용할 수 있습니다. 새로운 API를 사용하면 더욱 유연하게 맞춤 보고서를 작성하고, 데이터를 보고 애플리케이션 및 프로세스에 통합할 수 있습니다. 새 Search Ads 360 Reporting API로 이전하고 이를 사용하는 방법에 대해 자세히 알아보세요.
대용량 보고서에 대한 요청은 생성하는 데 시간이 걸릴 수 있으므로 Search Ads 360 API에서는 보고서 요청 및 다운로드를 위한 비동기 기술을 제공합니다. 이 기법을 사용하면 보고서에 원하는 데이터를 지정하는 초기 요청을 보낸 다음 Search Ads 360에서 보고서 생성을 완료할 때까지 추가 폴링 요청을 보냅니다. Search Ads 360에서는 보고서의 크기에 따라 데이터를 여러 파일로 분할합니다. 보고서가 생성되면 각 보고서 파일 다운로드 요청을 보냅니다. 소량의 데이터를 요청하는 경우 단일 동기식 요청만 전송할 수 있습니다.
비동기식 요청 만들기
Reports.request()를 호출하여 보고서에 포함할 데이터 유형을 지정합니다. 요청할 수 있는 데이터 유형은 보고서 유형을 참고하세요.Search Ads 360에서 요청을 검증하고 이 요청의 고유 식별자인 보고서 ID를 반환합니다.
- 보고서 ID를 사용하여
Reports.get()를 호출합니다.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.
}
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가 됩니다. 응답에는 보고서 파일을 다운로드하기 위한 URL이 포함된 추가 필드 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에서 반환할 수 있는 오류 목록은 응답 코드를 참고하세요.
보고서 다운로드
각 보고서 파일 URL을 직접 누르거나 보고서 ID 및 파일 번호 (0 색인이 생성됨)와 함께 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과 새 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()