Агрегация страниц

POST /v1/pages/aggregate

Подсчёт количества страниц с учётом фильтра и группировка по категориальным полям. Поддерживает функцию count и группировку groupBy.

Поля запроса (body)

Параметр Тип Обяз. Описание
aggregate array нет Массив агрегаций. Для страниц осмысленна { "field": "*", "function": "count" } — числовых полей для sum/avg/min/max у сущности нет. Без параметра возвращается count записей с учётом фильтра
groupBy string | array нет Поле или поля для группировки. Допустимы только поля из aggregatable: siteId, active, deleted, public, folderId, tplId, createdById, modifiedById. До 5 полей
filter object нет Фильтрация по полям страницы.
Синтаксис фильтрации. Пример: { "siteId": 12 }

Примеры

curl — личный ключ

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/pages/aggregate" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "groupBy": "siteId"
  }'

curl — OAuth-приложение

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/pages/aggregate" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "groupBy": "siteId"
  }'

JavaScript — личный ключ

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/pages/aggregate', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    groupBy: 'siteId',
  }),
})

const { success, data } = await res.json()
console.log('Страниц по сайтам:', data.groups)

JavaScript — OAuth-приложение

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/pages/aggregate', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    groupBy: 'siteId',
  }),
})

const { success, data } = await res.json()

Другие сценарии

Общее количество страниц в портале — без выгрузки записей:

JSON 
{}

Количество страниц одного сайта:

JSON 
{ "filter": { "siteId": 12 } }

Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
data.count number Количество страниц, соответствующих фильтру
data.aggregates object Результаты числовых агрегаций. Для страниц остаётся пустым — нет числовых полей
data.groups array Присутствует при groupBy. Каждый элемент — значение измерения плюс count записей в группе
data.meta.totalRecords number Общее количество записей
data.meta.recordsProcessed number Сколько записей обработано
data.meta.truncated boolean Был ли результат ограничен (true при более 5000 записей)
data.meta.groupTotal number Присутствует при groupBy — количество групп
data.meta.groupsTruncated boolean Присутствует при groupBy. true, если число групп превысило лимит и список групп усечён

Пример ответа

Группировка по сайту (groupBy: "siteId"):

JSON 
{
  "success": true,
  "data": {
    "count": 84,
    "aggregates": {},
    "groups": [
      { "siteId": 12, "count": 9, "aggregates": {} },
      { "siteId": 14, "count": 6, "aggregates": {} },
      { "siteId": 27, "count": 11, "aggregates": {} }
    ],
    "meta": {
      "totalRecords": 84,
      "recordsProcessed": 84,
      "truncated": false,
      "groupTotal": 5,
      "groupsTruncated": false
    }
  }
}

Простой подсчёт без группировки ({}):

JSON 
{
  "success": true,
  "data": {
    "count": 84,
    "aggregates": {},
    "meta": {
      "totalRecords": 84,
      "recordsProcessed": 0,
      "truncated": false
    }
  }
}

Пример ответа при ошибке

400 — поле вне списка aggregatable:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "groupBy field 'title' is not aggregatable on this entity. Available: siteId, active, deleted, public, folderId, tplId, createdById, modifiedById."
  }
}

Ошибки

HTTP Код Описание
400 INVALID_PARAMS Поле groupBy вне списка aggregatable или неизвестная функция агрегации
403 SCOPE_DENIED API-ключ не имеет скоупа landing
401 TOKEN_MISSING API-ключ не имеет настроенных токенов

Полный список общих ошибок API — Ошибки.

Известные особенности

Группировка считается по выборке. При более 5000 записей (meta.truncated: true) счётчики групп основаны на выборке из 5000 записей, а верхний count остаётся точным общим числом по фильтру.

Видимость по правам пользователя. В подсчёт попадают только страницы, к которым у владельца API-ключа есть право «просмотр». Если ожидается ненулевой результат, но count равен нулю — проверьте права пользователя, под которым выпущен ключ.

Смотрите также