Артефакты автоматизаций

Артефакт — именованное JSON-значение, которое автоматизация сохраняет на бэкенде внутри своей компании. Это позволяет получать данные из внешней системы, преобразовывать их и хранить последний результат для чтения через API. Данные сохраняются после перезапуска сервиса.

Например, автоматизация раз в час получает остатки из учётной системы и сохраняет их под именем warehouse.stock. Другая интеграция читает этот артефакт, не обращаясь повторно к источнику.

Настройка назначения

В конфигурации с одним источником замените HTTP-назначение:

version: 1
trigger:
  type: schedule
  cron: "0 * * * *"
  timezone: Europe/Moscow
source:
  type: http
  method: GET
  url: https://accounting.example.com/api/stock
  headers:
    Authorization: "Bearer ${secrets.ACCOUNTING_TOKEN}"
  response:
    format: json
transform:
  type: javascript
  timeout_seconds: 2
destination:
  type: artifact
  name: warehouse.stock

Обработчик возвращает данные для сохранения:

function transform(input, context) {
  if (!Array.isArray(input.items)) {
    throw new Error('Источник не вернул список остатков');
  }
  return { items: input.items, received_at: context.started_at };
}

Кнопка с иконкой архива в редакторе конфигурации помогает добавить такое назначение. В режиме source/destination она заменяет прежнее назначение; в режиме steps добавляет ещё один шаг.

Одновременно сохранить и отправить

В steps можно сочетать HTTP-назначения и артефакты. Источники остаются HTTP. Пример шага:

- id: stock_snapshot
  kind: destination
  type: artifact
  name: warehouse.stock
  input: ${transform.output.stock}

Без input сохраняется весь результат обработчика. Селектор поддерживает поля объектов, как у HTTP-назначений. Для артефакта не нужны url, method, headers, request, response и body; эти поля запрещены. В одном pipeline нельзя дважды записать одно имя артефакта.

Артефакты поддерживают ручные запуски, расписание и события. Для событий используются version: 2 и trigger.type: event, источник не указывается. В steps данные HTTP-источников доступны обработчику по их id: например, input.stock_source.

Обновление и ошибки

• Первая запись создаёт версию 1. Каждая следующая запись полностью заменяет значение и увеличивает версию. История содержимого предыдущих версий не хранится.
• Ошибка источника, обработчика или сохранения оставляет предыдущий артефакт доступным. Если данные имеют неверную структуру, обработчик должен явно выбросить ошибку.
• Проверочный запуск ничего не записывает. Чтобы создать артефакт, сохраните pipeline и выполните обычный запуск.
• Назначения исполняются параллельно. Если HTTP-назначение завершилось ошибкой, успешно записанный артефакт остаётся сохранённым; общей транзакции с внешними сервисами нет.
• При одновременной записи одного имени из разных pipeline побеждает последняя завершённая запись. Повторный запуск также увеличивает версию, даже если значение совпадает.
• Автоматического срока удаления нет. При удалении pipeline его артефакты остаются до явного удаления. pipeline_id и run_id показывают происхождение последней записи и могут ссылаться на уже удалённую историю. Ручная запись очищает эти поля.

Просмотр и ручное управление

В разделе Администрирование → Автоматизации → Артефакты доступны список, просмотр JSON, ручное создание, замена и удаление. Список показывает имя, размер, текущую версию и время обновления. Содержимое загружается при открытии отдельного артефакта.

Удаление необратимо. Если автоматизация остаётся включённой, следующий успешный запуск создаст артефакт заново.

API

Все методы ограничены текущей компанией. Нужна активная лицензия API и право admin_edit_provider_integrations. Артефакт другой компании нельзя прочитать или изменить, даже зная его имя.

Метод	Путь	Назначение
GET	/api/v1/automations/artifacts	Список метаданных без содержимого.
GET	/api/v1/automations/artifacts/item?name=warehouse.stock	Метаданные и значение одного артефакта.
POST	/api/v1/automations/artifacts/upsert	Создать или полностью заменить значение.
DELETE	/api/v1/automations/artifacts/delete?name=warehouse.stock	Удалить артефакт.

Для обычного API передаются пользовательский Bearer-токен и X-Provider-Token. Для внешнего OpenAPI используются X-OpenAPI-Token и полученный для той же компании X-Provider-Token. Авторизация и получение токена описаны в интеграциях.

Тело POST:

{ "name": "warehouse.stock", "value": { "items": [{ "sku": "A01", "quantity": 12 }] } }

value — JSON-значение, а не строка с сериализованным JSON. Допускаются объект, массив, строка, число, boolean и явный null; отсутствие value недопустимо.

Все ответы возвращаются в общей оболочке code, status, message, result. Чтение одного артефакта:

{
  "code": 200,
  "result": {
    "name": "warehouse.stock",
    "value": { "items": [{ "sku": "A01", "quantity": 12 }] },
    "size_bytes": 39,
    "version": 1,
    "created_at": "2026-10-13T09:00:00Z",
    "updated_at": "2026-10-13T09:00:00Z"
  }
}

POST возвращает сохранённый артефакт; DELETE — result: { "deleted": true }; список — result: { "items": [...] } без value. Некорректное имя/JSON — 400, отсутствие доступа — 403, отсутствующий артефакт — 404, превышение квоты — 409.

Ограничения и безопасность

Имя начинается с латинской буквы, содержит латинские буквы, цифры, ., _, - и имеет длину до 128 символов. Регистр учитывается. Максимум 100 артефактов на компанию, до 1 МиБ сериализованного JSON на значение и до 64 МиБ суммарно. Обновление существующего имени разрешено при достижении лимита количества, если хватает места.

Артефакты предназначены для прикладных данных. Пароли, API-ключи и токены храните в секретных переменных: содержимое артефакта доступно пользователям с правом управления интеграциями.

Чтение из гибридных микроприложений

В SDK @synchra24/app версии 0.2.0 добавлен метод getArtifact(name). Нужна также версия мобильного приложения с поддержкой нового события моста app.automation.artifact.get и бэкенд с API артефактов.

const synchra = new SynchraApp("SERVICE_TOKEN");
const snapshot = await synchra.getArtifact<{
  items: { sku: string; quantity: number }[];
}>("warehouse.stock");

console.log(snapshot.value.items);
console.log(snapshot.version, snapshot.updated_at);

Мост проверяет токен открытого внутреннего сервиса, а мобильное приложение выполняет запрос от текущего пользователя и компании. Микроприложению не передаются Bearer-токен и токен компании. Указывать компанию, URL API или заголовки не нужно.

Результат содержит name, value, size_bytes, version, created_at, updated_at и необязательные идентификаторы источника pipeline_id, run_id. Сохранённый null возвращается как value: null. Тип в TypeScript описывает ожидаемые данные, но не заменяет проверку структуры при чтении.

Действуют те же права API: лицензия API и admin_edit_provider_integrations. Мост не предоставляет дополнительных прав пользователю. Если артефакт не найден, доступ запрещён или сеть недоступна, Promise отклоняется. В старой версии мобильного приложения, не поддерживающей событие моста, сработает responseTimeout SDK. Предусмотрите состояние недоступных данных в интерфейсе микроприложения.

Метод моста только читает артефакты. Создание, обновление и удаление доступны через автоматизации и API управления. Подробности — в README библиотеки.