Источники проектов: чтение и подготовка изменения

Для просмотра источников используйте view=read. Для подготовки изменения одного проекта — view=edit. Это две формы одного метода: GET /v1/external/cabinets/{cabinetId}/projects/sources. Нужен cabinet:read и текущий доступ к кабинету.

Посмотреть источники

curl \
  'https://api.alitos.io/v1/external/cabinets/123456789/projects/sources?view=read&limit=20' \
  --header "Authorization: Bearer ${ALITOS_EXTERNAL_JWT}"

Замените 123456789 ID доступного кабинета. Чтобы выбрать конкретные проекты, передайте projectIds повторно для каждого ID. Идентификаторы — положительные 64-битные значения; сохраняйте их строками, не преобразуйте в JavaScript number.

Если есть nextCursor, передайте его без изменений в следующий запрос с теми же фильтрами и view. Cursor чтения нельзя использовать для редактирования и наоборот.

Как понимать объём ответа

В view=read проекты разбиты на страницы. Параметр limit задаёт число проектов: по умолчанию 100, допустимо от 1 до 200.

Поле или параметр	Значение в `view=read`
`totalProjects`	Число проектов во всей выборке
`totalSources`	Число источников в проектах текущей страницы
`returnedSources`	Сколько источников передано в ответе
`maxSources`	Общий предел возвращаемых источников на текущей странице
`maxSourcesPerProject`	Предел возвращаемых источников одного проекта
`omittedByProjectLimit`	Источники проекта, не попавшие в ответ из-за его предела
`omittedByPageBudget`	Источники проекта, не попавшие из-за общего предела страницы

sourceCountScope и sourceBudgetScope равны page. Не складывайте totalProjects с каждой страницы и не считайте totalSources итогом по кабинету. Проверяйте truncated и счётчики пропущенных источников, прежде чем делать вывод о полноте данных.

maxSources допускает от 1 до 5000, по умолчанию 5000. maxSourcesPerProject допускает от 1 до 5000, по умолчанию 1000. Эти пределы ограничивают источники, а limit — проекты.

Подготовить изменение одного проекта

Запросите view=edit и один конкретный projectIds. Если проект найден, сохраните сильный ETag из заголовка и передайте его в If-Match при обновлении. Порядок действий и ответы 400, 412 и 428 описаны в защите от параллельных изменений.

view=edit остаётся формой по умолчанию для совместимости. В ней maxSources ограничивает источники всей выбранной совокупности, а не только текущей страницы проектов. Только ответ для одного явно выбранного и найденного проекта имеет сильный ETag. Остальные edit-страницы возвращают слабый ETag.

view=read не содержит sourcesFingerprint и не возвращает ETag. Такой ответ нельзя использовать для подготовки защищённого обновления.

Источники и аналитика B4

Эта страница описывает список настроенных источников, а не полный расчёт их эффективности. Для аналитики B4 используйте сценарий аналитики: после завершения операции result?view=all возвращает все подходящие источники одним ответом, без пагинации.

Параметры выбора активных и удалённых проектов, типы полей и полные ответы: OpenAPI.