Новый API отчетов Search Ads 360 теперь доступен. Новый API обеспечивает повышенную гибкость для создания пользовательских отчетов и интеграции данных в ваши приложения и процессы отчетности. Узнайте больше о переходе и использовании нового API отчетов Search Ads 360 .
Если вы запрашиваете небольшие или средние отчеты по рекламодателям или системным аккаунтам, вы можете отправить только один синхронный запрос отчета. В ответ на запрос API Search Ads 360 вернет весь отчет в виде объекта JSON. Синхронные запросы:
- Может возвращать только отчеты рекламодателей и системных аккаунтов .
- Заблокируйте своего клиента до тех пор, пока Search Ads 360 не сгенерирует отчет.
Если вы запрашиваете крупные отчеты по рекламодателям или системным аккаунтам, мы рекомендуем асинхронный подход .
Чтобы сделать синхронный запрос
Вызовите Reports.generate() , чтобы указать тип данных, которые вы хотите включить в отчет вашего рекламодателя или учетной записи системы .
Поисковая реклама 360 проверяет запрос, создает отчет и возвращает отчет как ресурс отчетов в тексте ответа.
Пример синхронного запроса
Ниже приведен пример запроса 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.
}
Чтобы отправить этот запрос, используйте служебный скрипт Search Ads 360.
Чтобы отправить необработанный запрос JSON POST, вы можете использовать сценарий sa360Api.py следующим образом:
- Скопируйте пример объекта JSON (все, что находится между двумя фигурными скобками и включая их) в новый текстовый файл с именем
request.txt. - Измените идентификатор агентства, указанный в коде JSON, на свой собственный идентификатор агентства.
- Удалите все комментарии, например
// The date column segments the report by individual days. - Соберите свои учетные данные OAuth 2.0 в одну строку, разделенную запятыми, следующим образом:
client-ID,client-secret,refresh-token
(Это та же строка, которуюsa360Api.pyвыводит при запускеsa360Api.py --login, как описано в разделе «Настройка авторизации» .) - Вызовите
sa360Api.pyследующим образом:
sa360Api.py --cred CREDENTIALS --server API-method --post < request.txt
В приведенной выше команде замените строкуCREDENTIALSна строку, которую вы собрали на предыдущем шаге.
Замените имя метода POST в поле ниже наAPI-method.Например:
sa360Api.py --cred 123456789123.apps.googleusercontent.com,ABCDEFGHIJKLMNOPQR_abcdef,1/HIJklM01OPQR23NOP456rst890uvw --server https://www.googleapis.com/doubleclicksearch/v2/reports/generate --post < request.txt
Ява
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();
}
Питон
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())
Пример отчета
Ответом на синхронный запрос является объект отчета . Если запрос успешно проверен, первые несколько свойств объекта содержат метаданные, описывающие отправленный вами запрос. Сам отчет находится в свойстве rows объекта.
{
"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
},
...
]
}
Если проверка не удалась
Если отчет не проходит проверку, 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."
}
}
Разделение синхронных отчетов на несколько ответов
По умолчанию синхронный запрос возвращает первые 10 000 строк. Чтобы изменить это поведение, используйте свойства Reports.request.startRow и Reports.request.rowCount для получения определенных частей отчета при каждом запросе.
Пример разделения синхронного отчета
Например, этот запрос вернет первые сто строк (от 0 до 99) отчета агентства, сегментированного по дням:
{
"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
}
Вы можете последовать за этим запросом еще одним запросом для строк со 100 по 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
}