Операции со снимками прослеживаемости

Снимок сохраняет версионированное состояние проекта, группы или портфеля для последующего просмотра, сравнения и экспорта. Используйте REST API с токеном доступа: примеры ниже показывают полный цикл от базового снимка до экспорта сравнения.

Зачем сохранять снимки

Перед изменением или выпуском создайте базовый снимок, затем сохраните второе состояние после обновления показателей проекта. Сравнение по двум идентификаторам показывает сохранённые значения и доступные разницы. Экспорт позволяет передать эти данные команде вместе с исходными снимками.

Последовательность работы: прочитайте политику → создайте базовый снимок → выполните изменение и обновите проверки → создайте текущий снимок → сравните идентификаторы → экспортируйте пакет. Храните оба идентификатора рядом с ревизией выпуска, чтобы повторно открыть те же данные.

Подготовка и область действия

Примеры рассчитаны на Bash и curl 7.76 или новее. Рабочий каталог произвольный; файл экспорта появится в текущем каталоге. Войдите и получите доступ к проекту. Задайте CODEGRAPH_URL как HTTPS-адрес API без конечного /api/v1 и без завершающего /. Сохраните токен доступа в CODEGRAPH_TOKEN в текущем терминале. В CODEGRAPH_PROJECT_ID укажите UUID доступного проекта из ответа API проектов. Храните токен вне репозитория. Перед выполнением примеров отключите трассировку команд в Bash: set +x.

В примерах заголовок авторизации передаётся через стандартный ввод curl -H @-, чтобы токен не попадал в аргументы процесса.

Все операции используют:

/api/v1/traceability/snapshots

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

Операции

Операции
Метод и маршрут	Назначение
`POST /api/v1/traceability/snapshots`	Создать ручной снимок проекта, группы или портфеля.
`GET /api/v1/traceability/snapshots`	Получить доступные снимки с ограниченной пагинацией.
`GET /api/v1/traceability/snapshots/policy`	Прочитать действующую политику неизменяемых снимков.
`GET /api/v1/traceability/snapshots/{snapshot_id}`	Прочитать доступную запись снимка.
`POST /api/v1/traceability/snapshots/compare`	Сравнить два идентификатора снимков или две временные точки проекта.
`POST /api/v1/traceability/snapshots/{snapshot_id}/export`	Экспортировать снимок или сравнение с базовым снимком.

Поля запросов и ответов сверяйте со схемой OpenAPI развёрнутой версии: /api/openapi.json. Она определяет действующие ограничения.

Создание снимка

Сначала прочитайте политику /policy. Проверьте доступные области, правила неизменяемости и хранения. Неизменяемые снимки сохраняются как артефакты; доступны создание, список, просмотр, сравнение и экспорт.

printf 'Authorization: Bearer %s\n' "$CODEGRAPH_TOKEN" |
curl --fail-with-body -H @- "$CODEGRAPH_URL/api/v1/traceability/snapshots/policy" \
  -H "X-Project-ID: $CODEGRAPH_PROJECT_ID"

printf 'Authorization: Bearer %s\n' "$CODEGRAPH_TOKEN" |
curl --fail-with-body -H @- -X POST "$CODEGRAPH_URL/api/v1/traceability/snapshots" \
  -H "X-Project-ID: $CODEGRAPH_PROJECT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "project",
    "reason": "pre-release baseline",
    "trigger_source": "manual",
    "immutable": true,
    "retention_class": "standard"
  }'

Для области project не передавайте project_name, чтобы использовать активный проект. При выборе другого проекта CodeGraph проверяет право доступа.

Успешный запрос возвращает JSON с полем id. Сохраните его в SNAPSHOT_ID. Для сравнения нужны два реально созданных снимка: запишите их идентификаторы в BASELINE_ID и CURRENT_ID. Проверьте в ответе scope_ref, project_name, timestamp, immutable, basis_mode и coherence_status: сохранённый снимок может содержать неполные данные.

Как читать основу снимка

basis_mode описывает режим формирования данных. В режиме best_effort CodeGraph собирает доступное состояние проекта. Режим strict_audit требует согласованной основы анализа для представлений, которые используют этот режим.

coherence_status показывает связь графа кода, запуска аудита и сохранённых результатов:

Как читать основу снимка
Значение	Как читать результат
`coherent`	Артефакты анализа связаны между собой. Сопоставьте их идентификаторы `cpg_revision_id`, `audit_run_id` и `audit_snapshot_id` с проверяемой ревизией.
`stale_cpg`	Граф устарел относительно исходного кода либо аудит использует предыдущую ревизию графа. Обновите граф и выполните аудит.
`stale_audit`	Сохранённый результат аудита относится к другому запуску. Обновите результаты и создайте следующий снимок.
`audit_snapshot_only` / `dashboard_snapshot_only`	Основа содержит сохранённый результат только одного вида. Проверьте, какой второй артефакт нужно сформировать.
`unknown`	В записи используется начальное значение статуса. Проверьте заполнение идентификаторов анализа перед сравнением.

Маршрут ручного создания в этих примерах сохраняет показатели проекта с basis_mode: best_effort, coherence_status: unknown и пустыми идентификаторами анализа. Это относится и к проекту с завершённым аудитом. Используйте такие снимки для просмотра и сравнения сохранённых показателей. Для проверки результатов исправления приложите отчёт аудита и ревизию его графа отдельно; экспорт снимков предоставит сохранённые состояния.

Список и отдельная запись

printf 'Authorization: Bearer %s\n' "$CODEGRAPH_TOKEN" |
curl --fail-with-body -H @- "$CODEGRAPH_URL/api/v1/traceability/snapshots?scope=project&limit=20&offset=0" \
  -H "X-Project-ID: $CODEGRAPH_PROJECT_ID"

printf 'Authorization: Bearer %s\n' "$CODEGRAPH_TOKEN" |
curl --fail-with-body -H @- "$CODEGRAPH_URL/api/v1/traceability/snapshots/$SNAPSHOT_ID" \
  -H "X-Project-ID: $CODEGRAPH_PROJECT_ID"

Если limit не задан, используется настроенный максимум. Допустимы limit от 1 до этого максимума и offset от 0. Превышение максимума или отрицательный offset отклоняется с кодом 422; выбирайте значение по OpenAPI текущего экземпляра. Ответ списка содержит items, total, limit, offset, has_next и has_prev.

Сравнение

Для доказательств выпуска используйте идентификаторы сохранённых неизменяемых снимков:

printf 'Authorization: Bearer %s\n' "$CODEGRAPH_TOKEN" |
curl --fail-with-body -H @- -X POST "$CODEGRAPH_URL/api/v1/traceability/snapshots/compare" \
  -H "X-Project-ID: $CODEGRAPH_PROJECT_ID" \
  -H "Content-Type: application/json" \
  -d "{\"from_snapshot_id\":\"$BASELINE_ID\",\"to_snapshot_id\":\"$CURRENT_ID\",\"include_drilldown\":true}"

Сравнение по времени поддерживается для снимков проекта. Для group и portfolio нужны идентификаторы снимков.

Экспорт

printf 'Authorization: Bearer %s\n' "$CODEGRAPH_TOKEN" |
curl --fail-with-body -H @- -X POST "$CODEGRAPH_URL/api/v1/traceability/snapshots/$CURRENT_ID/export" \
  -H "X-Project-ID: $CODEGRAPH_PROJECT_ID" \
  -H "Content-Type: application/json" \
  -o snapshot-export.bin \
  -d "{\"format\":\"json\",\"language\":\"ru\",\"baseline_snapshot_id\":\"$BASELINE_ID\"}"

При указании baseline_snapshot_id экспорт содержит пакет сравнения:

Экспорт
Поле	Содержание
`target_name`	Имя проекта или группы, к которой относится результат.
`from_snapshot`	Запись базового снимка, включая идентификатор и время.
`to_snapshot`	Запись текущего снимка.
`diff`	Результат сравнения этих снимков.

Для экспорта одного снимка исключите baseline_snapshot_id из тела запроса.

Проверьте успешный HTTP-статус, тип содержимого и наличие нового файла экспорта. Содержимое snapshot-export.bin соответствует запрошенному формату json. Флаг --fail-with-body делает HTTP-ошибку ошибкой команды, но при экспорте тело ошибки тоже может попасть в файл; его наличие само по себе не подтверждает успех.

Эксплуатационная проверка

Прочитайте /policy до того, как опираться на неизменяемость, сроки хранения или поведение экспорта.
Сохраните идентификаторы снимков, проект, время запроса и ревизию выпуска в доказательствах приёмки.
Успешный запрос снимка создаёт один из артефактов для оценки готовности релиза.
При 403 проверьте роль и доступ к выбранному проекту. При 404 проверьте идентификатор снимка и доступ к его проекту.
Сверяйте полный набор операций с OpenAPI развёрнутой версии.

Связанные руководства

Справочник REST API — подключение к API, авторизация и доступ к проектам.
Устранение неполадок — проверка подключения и диагностика ошибок.