Se richiedi report su inserzionisti o account motore di piccole o medie dimensioni, puoi inviare una sola richiesta di report sincrona. In risposta alla richiesta, l'API Search Ads 360 restituisce l'intero report in un oggetto JSON. Richieste sincrone:
- Può restituire solo report su inserzionista e account motore
- Blocca il cliente finché Search Ads 360 non genera il report
Se richiedi rapporti su inserzionisti o account motore di grandi dimensioni, ti consigliamo l'approccio asincrono.
Per effettuare una richiesta sincrona
Chiama Reports.generate()
per specificare il tipo di dati da includere nel report sull'inserzionista o sull'account motore.
Search Ads 360 convalida la richiesta, genera il report e lo restituisce come risorsa Report nel corpo della risposta.
Esempio di richiesta sincrona
Di seguito è riportato un esempio di richiesta Reports.generate().
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())
Report di esempio
La risposta a una richiesta sincrona è un oggetto report.
Se la richiesta viene convalidata correttamente, le prime proprietà nell'oggetto contengono metadati che descrivono la richiesta inviata. Il report stesso si trova nella proprietà rows
dell'oggetto.
{
"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
},
...
]
}
Se la convalida non va a buon fine
Se il report non supera la convalida, Search Ads 360 restituisce una risposta 400 HTTP con un oggetto di errore. Ad esempio, nella richiesta di esempio riportata sopra non è stata specificata un'agenzia reale:
{
"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."
}
}
Suddivisione dei report sincroni in più risposte
Per impostazione predefinita, una richiesta sincrona restituisce le prime 10.000 righe. Per modificare questo comportamento,
utilizza le proprietà Reports.request.startRow
e Reports.request.rowCount
per recuperare parti specifiche del report con ogni richiesta.
Esempio di suddivisione di un report sincrono
Ad esempio, questa richiesta restituisce le prime centinaia di righe (da 0 a 99) di un report di agenzia segmentato per giorno:
{
"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
}
Puoi seguire questa richiesta con un'altra richiesta per le righe da 100 a 199:
{
"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
}