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 จะตรวจสอบคำขอและแสดงผลรหัสรายงาน ซึ่งเป็นตัวระบุที่ไม่ซ้ำกันสำหรับคำขอนี้
- โทรไปที่
Reports.get()ด้วยรหัสรายงานการตอบกลับจาก Search Ads 360 ระบุสิ่งต่อไปนี้
- รายงานพร้อมให้ดาวน์โหลดหรือไม่
- หากรายงานพร้อมแล้ว URL อย่างน้อย 1 รายการสําหรับดาวน์โหลดรายงาน
- เรียกใช้
Reports.getFile()เพื่อดาวน์โหลดไฟล์รายงานที่เข้ารหัส หรือเพียงแค่ดาวน์โหลดจาก URL โดยตรงSearch Ads 360 แสดงผลรายงานเป็นไฟล์ที่เข้ารหัส UTF-8
ฉันควรจัดทำแบบสำรวจบ่อยเพียงใดเพื่อดูว่ารายงานพร้อมแล้วหรือไม่
ระยะเวลาที่ Search Ads 360 ต้องใช้ในการสร้างรายงานส่วนใหญ่จะขึ้นอยู่กับจำนวนข้อมูลในรายงาน ลองใช้แบบสำรวจสถานะรายงานหนึ่งครั้งต่อนาที แล้วปรับความถี่หากคำขอรายงานโดยเฉลี่ยใช้เวลาในการดำเนินการเสร็จสิ้นมากกว่าหรือน้อยกว่าอย่างมาก
การแยกรายงานแบบอะซิงโครนัสออกเป็นไฟล์หลายไฟล์
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 จะแสดงรหัสรายงาน นอกจากนี้ 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."
}
}
แบบสำรวจสถานะรายงาน
โทรติดต่อ 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 จะเป็นเท็จ
{
"kind": "doubleclicksearch#report",
"id": "MTMyNDM1NDYK",
"isReportReady": false,
"request": {
...
},
...
}
เมื่อรายงานพร้อมแล้ว
เมื่อรายงานเสร็จสมบูรณ์และพร้อมให้ดาวน์โหลด ช่อง isReportReady จะเป็นจริง การตอบกลับนี้ยังมีช่องเพิ่มเติม 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 1 รหัสพร้อมคำอธิบาย
{
"error" : {
"code" : 410, // Or other error codes.
"message" : "Processing was halted on the backend and will not continue."
}
}
ดูรายการข้อผิดพลาดที่ Search Ads 360 แสดงผลได้ในโค้ดตอบกลับ
ดาวน์โหลดรายงาน
คุณดาวน์โหลดรายงานได้โดยคลิก URL ของไฟล์รายงานแต่ละรายการโดยตรง หรือเรียกใช้ Reports.getFile() ด้วยรหัสรายงานและหมายเลขไฟล์ (จัดทำดัชนีแล้ว 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
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
ดาวน์โหลดไฟล์การแมปรหัส
คุณดาวน์โหลดไฟล์ที่มีการแมปรหัสระหว่าง Search Ads 360 เวอร์ชันเก่าและ 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()