Данные отчета по запросу

Метод reportData.query предоставляет синхронный способ получения данных отчета. В отличие от стандартной службы Reports , которая генерирует отчеты в виде файлов (CSV или Excel), этот метод возвращает структурированные данные в формате JSON непосредственно в ответе. Он устраняет необходимость предварительного определения, создания и сохранения ресурса Report , что делает его идеальным для получения и анализа данных в режиме реального времени.

Обзор

Изучите это руководство, чтобы ознакомиться с использованием этой конечной точки для запроса данных отчетов Campaign Manager 360.

Подготовьте запрос

Создайте объект ReportDataQueryRequest указав измерения, метрики, диапазон дат, фильтры и критерии сортировки.

{
  "body": {
    "dateRange": "LAST_7_DAYS",
    "dimensionNames": [
      "advertiser",
      "campaign"
    ],
    "metricNames": [
      "impressions",
      "clicks"
    ],
    "sortBys": [
      {
        "name": "clicks",
        "sortOrder": "DESCENDING"
      }
    ],
    "maxResults": 100
  }
}

dateRange

Объект DateRange , указывающий период времени для запроса. Это может быть пользовательский диапазон дат или относительный диапазон дат.

dimensionNames

Список стандартных названий измерений для группировки.

metricNames

Обязательно. Список стандартных названий метрик для включения.

dimensionFilters

Список объектов DimensionValue, используемых для фильтрации данных отчета. Используйте его для ограничения результатов запроса определенными значениями измерения.

sortBys

Настройки сортировки для измерений или метрик. Каждая настройка включает имя поля и порядок сортировки.

maxResults

Максимальное количество строк, возвращаемых на странице (по умолчанию: 100 , максимум: 1000 ).

Пагинация

Поле maxResults определяет количество результатов, возвращаемых в одном ответе. Например, если вы установите maxResults равным 10 , API вернет не более 10 результатов. Возможно, API вернет меньше 10 результатов, если меньше 10 результатов соответствуют вашему запросу.

Если доступны дополнительные результаты, ответ будет содержать nextPageToken . Чтобы получить следующую страницу результатов, отправьте тот же запрос еще раз, установив в поле pageToken значение этого токена. Все остальные параметры запроса оставьте без изменений.

Отправить запрос

Отправьте HTTP POST-запрос на конечную точку reportdata/query :

POST https://dfareporting.googleapis.com/dfareporting/v5/userprofiles/{profileId}/reportdata/query

Убедитесь, что ваш запрос аутентифицирован с использованием стандартных учетных данных OAuth 2.0 и необходимых областей действия. Дополнительную информацию см. в разделе «Авторизация запросов» .

Успешный ответ

В случае успешного выполнения запроса возвращается HTTP-ответ 200 OK с JSON-данными, содержащими columnHeaders , rows и totalRow .

{
  "columnHeaders": [
    { "name": "advertiser", "type": "DIMENSION" },
    { "name": "campaign", "type": "DIMENSION" },
    { "name": "impressions", "type": "METRIC" },
    { "name": "clicks", "type": "METRIC" }
  ],
  "rows": [
    {
      "values": [ "Test Advertiser", "Summer Campaign", "148672", "420" ]
    },
    {
      "values": [ "Test Advertiser", "Fall Campaign", "2159", "2" ]
    }
  ],
  "totalRow": {
    "values": [ "", "", "150831", "422" ]
  },
  "nextPageToken": "1234567890"
}

columnHeaders

Названия и типы ( DIMENSION или METRIC ) возвращаемых полей.

rows

Список объектов ReportDataRow , содержащих результаты запроса. Строковые значения в каждой строке выравниваются по позиции относительно columnHeaders .

totalRow

Единая сводная строка, представляющая сумму всех соответствующих метрик. Поля измерений и метрики, которые нельзя суммировать (например, метрики охвата, такие как uniqueReachTotalReach ), в этой строке пусты ( "" ).

nextPageToken

Токен, используемый в последующем запросе для получения следующей страницы, если существуют дополнительные строки.

Задержка и тайм-ауты

Поскольку это синхронная конечная точка, запросы выполняются немедленно, и данные возвращаются непосредственно в ответе (до предела пагинации maxResults ). Максимальное время выполнения запросов составляет 60 секунд . Если запрос превышает этот лимит, API завершает операцию и возвращает ошибку HTTP 503 Service Unavailable .

Если вы столкнулись с этой ошибкой, попробуйте сузить диапазон дат, сузить фильтры (например, отфильтровать по конкретным рекламодателям или кампаниям) или уменьшить количество запрашиваемых измерений и показателей. В качестве альтернативы, запустите Report с помощью reports.run , чтобы асинхронно сгенерировать файл отчета для загрузки.

Ограничения и лимиты запросов

Конечная точка reportdata.query устанавливает ряд ограничений для обеспечения надежных ответов. Запросы, нарушающие эти ограничения, отклоняются с ответом HTTP 400 Bad Request .

Ограничения диапазона дат

• Для пользовательских диапазонов дат startDate должно находиться в пределах периода доступности данных для запрашиваемого типа данных отчета. Подробнее см. раздел «Доступность данных» .

Ограничения по метрике и размерности

• В поле metricNames необходимо указать как минимум одну метрику.
• Метрики и измерения в списках metricNames и dimensionNames должны быть уникальными.
• Метрики и параметры, помеченные как «Только для скачивания», не могут быть использованы в этих запросах.

Ограничения квот

Запросы к этому адресу используют следующие квоты:

• Ограничение на количество запросов в минуту на пользователя: 120 запросов в минуту на пользователя (2 запроса в секунду).
• Дневной лимит на проект: 10 000 запросов в день на проект.

Запросы, превышающие эти лимиты, завершаются ошибкой HTTP 429 Too Many Requests . При постраничной навигации по результатам каждый запрос на новую страницу (с использованием параметра pageToken ) считается отдельным запросом и расходует ресурсы из этой квоты.