Falls Sie kleine bis moderate Berichte von Werbetreibenden oder Engine-Konten anfordern, können Sie eine einzelne, synchrone Berichtsanfrage senden. Als Reaktion auf die Anfrage gibt die Search Ads 360 API den gesamten Bericht in einem JSON-Objekt zurück. Synchrone Anfragen:
- Es können nur Berichte zu Werbetreibenden und Engine-Konten zurückgegeben werden.
- Kunden blockieren, bis Search Ads 360 den Bericht erstellt hat
Wenn Sie umfangreiche Berichte für Werbetreibende oder Engine-Konten anfordern, empfehlen wir den asynchronen Ansatz.
So stellen Sie eine synchrone Anfrage:
Rufen Sie Reports.generate() auf, um den gewünschten Datentyp für den Bericht zu Werbetreibenden oder Engine-Konten anzugeben.
Search Ads 360 validiert die Anfrage, generiert den Bericht und gibt den Bericht als Reports-Ressource im Antworttext zurück.
Beispiel für eine synchrone Anfrage
Hier sehen Sie ein Beispiel für eine Reports.generate()-Anfrage.
JSON
POST https://www.googleapis.com/doubleclicksearch/v2/reports/generate
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
"engineAccountId": "700000000073991" // Replace with your ID
},
"reportType": "account", // This report covers all revenue and visits in the
// engine account specified in reportScope.
"columns": [
{ "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": "January visits" // 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" : "2013-05-01"
// Alternatively, try the "changedMetricsSinceTimestamp" or "changedAttributesSinceTimestamp"
// options. See Incremental reports.
},
"statisticsCurrency": "agency", // Required. See Currency for statistics.
"verifySingleTimeZone": false, // Optional. Defaults to false. See Time zone.
"includeRemovedEntities": false // Optional. Defaults to false.
}
Java
public static void main(String[] args) throws Exception {
Doubleclicksearch service = getService(); // See Set Up Your Application.
Report report = generateAccountReport(service);
outputReport(report, "./");
}
/**
* Creates an account report using the synchronous Report.generate method.
*
* @throws IOException
*/
private static Report generateAccountReport(Doubleclicksearch service) throws IOException {
try {
return service.reports().generate(generateAccountRequest()).execute();
} 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 clicks and visits for an engine account. Use
* your own agency ID, advertiser ID, and engine account ID.
*/
private static ReportRequest generateAccountRequest() {
return new ReportRequest().setReportScope(
new ReportScope()
.setAgencyId(20700000000000451L) // Replace with your ID
.setAdvertiserId(21700000000010391L) // Replace with your ID
.setEngineAccountId(700000000042201L)) // Replace with your ID
.setReportType("account")
.setColumns(Arrays.asList(new ReportApiColumnSpec[] {
new ReportApiColumnSpec().setColumnName("date"),
new ReportApiColumnSpec().setColumnName("dfaRevenue"),
new ReportApiColumnSpec()
.setColumnName("visits")
.setHeaderText("January visits")
.setStartDate("2013-01-01")
.setEndDate("2013-01-31"),}))
.setTimeRange(new TimeRange()
.setStartDate("2012-05-01")
.setEndDate("2013-05-01"))
.setStatisticsCurrency("agency");
}
/**
* Outputs a synchronous report to a file.
*/
private static void outputReport(Report report, String localPath)
throws IOException {
FileOutputStream outputStream = new FileOutputStream(new File(localPath, "Report"));
final PrintStream printStream = new PrintStream(outputStream);
printStream.print(report);
printStream.close();
}
Python
def generate_report(service):
"""Generate and print sample report.
Args:
service: An authorized Doubleclicksearch service. See Set Up Your Application.
"""
request = service.reports().generate(
body=
{
"reportScope
"agencyId": "12300000000000456", // Replace with your ID
"advertiserId": "21700000000011523", // Replace with your ID
"engineAccountId": "700000000073991" // Replace with your ID
},
"reportType": "account",
"columns": [
{ "columnName": "date" },
{ "columnName": "dfaRevenue" },
{
"columnName": "visits",
"startDate": "2013-01-01",
"endDate": "2013-01-31",
"headerText": "January visits"
}
],
"timeRange" : {
"startDate" : "2012-05-01",
"endDate" : "2013-05-01"
},
"statisticsCurrency": "agency",
"verifySingleTimeZone": "false",
"includeRemovedEntities": "false"
}
)
pprint.pprint(request.execute())
Beispielbericht
Die Antwort auf eine synchrone Anfrage ist ein report-Objekt.
Wenn die Anfrage erfolgreich validiert wurde, enthalten die ersten Attribute im Objekt Metadaten, die die von Ihnen gesendete Anfrage beschreiben. Der Bericht selbst befindet sich in der rows-Property des Objekts.
{
"kind":"doubleclicksearch#report",
"request":{
"columns":[
{"columnName":"date"},
{"columnName":"dfaRevenue"},
{"columnName":"visits","endDate":"2013-01-31","headerText":"visits last month","startDate":"2013-01-01"}
],
"includeDeletedEntities":false,
"reportScope":{
"agencyId":"12300000000000456",
"advertiserId":"21700000000011523",
"engineAccountId":"700000000073991"
},
"reportType":"account",
"rowCount":10000,
"startRow":0,
"statisticsCurrency":"agency",
"timeRange":{
"endDate":"2013-05-01",
"startDate":"2012-05-01"
}
},
"rowCount":366,
"rows":[
{
"date":"2012-05-01",
"dfaRevenue":0.0,
"visits last month":0.0
},
{
"date":"2012-05-02",
"dfaRevenue":0.0,
"visits last month":0.0
},
{
"date":"2012-05-03",
"dfaRevenue":0.0,
"visits last month":0.0
},
{
"date":"2012-05-04",
"dfaRevenue":0.0,
"visits last month":0.0
},
...
]
}
Wenn die Überprüfung fehlschlägt
Wenn der Bericht die Validierung nicht besteht, gibt Search Ads 360 eine HTTP-400-Antwort mit einem Fehlerobjekt zurück. In der Beispielanfrage oben wurde beispielsweise kein echter Betreiber angegeben:
{
"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."
}
}
Synchrone Berichte in mehrere Antworten aufteilen
Standardmäßig gibt eine synchrone Anfrage die ersten 10.000 Zeilen zurück. Verwenden Sie zum Ändern dieses Verhaltens die Properties Reports.request.startRow und Reports.request.rowCount, um bei jeder Anfrage bestimmte Teile des Berichts abzurufen.
Beispiel für die Aufteilung eines synchronen Berichts
Diese Anfrage gibt beispielsweise die ersten hundert Zeilen (0 bis 99) eines Agenturberichts zurück, der nach Tag segmentiert ist:
{
"reportScope": {
"agencyId": "12300000000000456", // Replace with your ID
"advertiserId": "21700000000011523", // Replace with your ID
"engineAccountId": "700000000073991" // Replace with your ID
},
"reportType": "account",
"columns": [
{ "columnName": "date" },
{ "columnName": "dfaRevenue" }
],
"timeRange" : {
"startDate" : "2012-05-01",
"endDate" : "2013-05-01"
},
"startRow":"0",
"rowCount":"100",
"statisticsCurrency": "agency",
"verifySingleTimeZone": false,
"includeRemovedEntities": false
}
Sie können auf diese Anforderung eine weitere Anfrage für die Zeilen 100 bis 199 anwenden:
{
"reportScope": {
"agencyId": "12300000000000456", // Replace with your ID
"advertiserId": "21700000000011523", // Replace with your ID
"engineAccountId": "700000000073991" // Replace with your ID
},
"reportType": "account",
"columns": [
{ "columnName": "date" },
{ "columnName": "dfaRevenue" }
],
"timeRange" : {
"startDate" : "2012-05-01",
"endDate" : "2013-05-01"
},
"startRow":"100",
"rowCount":"100",
"statisticsCurrency": "agency",
"verifySingleTimeZone": false,
"includeRemovedEntities": false
}