4. Загрузка данных

После формирования архива data.zip перейдите к загрузке. Выберите один из двух методов в зависимости от размера файла и стабильности сети:

• Стандартный
• Батчинг

Предварительный шаг: Валидация

Рекомендуется проверить архив на ошибки структуры перед загрузкой.

timectl import validate data.zip

Параметры:

• --check-missing-teams — проверять наличие команд, которые указаны в архиве, но отсутствуют на сервере.
• --check-server-duplicates — установить в false, чтобы игнорировать команды, каналы и пользователей, которые уже существуют на сервере (по умолчанию: true).
• --ignore-attachments — пропустить проверку наличия вложений в архиве.
• --team — указать команды, которые следует считать уже существующими на сервере. Флаг можно указывать несколько раз. Автоматически включает проверку --check-missing-teams.

Пример:

timectl import validate data.zip --team myteam --team myotherteam

Если есть ошибки, утилита укажен номер строки в JSONL и описание проблемы.

Метод А: Стандартный импорт

Подходит для сценариев с небольшими архивами (до 100 МБ) или с локальной сетью.

1. Загрузка файла на сервер:

   timectl import upload data.zip

2. Посмотреть список доступных архивов для импорта:

   timectl import list available

   Результат: Команда вернет название загруженного файла {session_id}_{filename}, где session_id выводится в консоли после выполнения предыдущего шага.

3. Запустить джобу по импорту:

   timectl import process 47ri9a7ufpb8jkruxk4w16a37w_data.zip

   В терминале должно вывестись:

   Import process job successfully created, ID: jpkd4ou77prg8c1fqrr3ejsxsr

   где jpkd4ou77prg8c1fqrr3ejsxsr — идентификатор джобы.

4. Мониторинг. Следите за статусом выполнения задачи:

   timectl import job show {job_id}

   где job_id — идентификатор джобы, полученной на предыдущем шаге.

Метод Б: Загрузка частями — Рекомендуемый

Подходит для архивов > 100 Мб или при нестабильном соединении.

🚀 Быстрый запуск (одной командой)

В большинстве случаев вам нужна только эта команда. Она автоматически разобьет файл на части по 50 Мб, загрузит их в 3 потока, соберет на сервере и сразу запустит импорт.

timectl import split upload ./data.zip \
  --chunk-size=50 \
  --workers-count=3 \
  --process

Параметры:

• --chunk-size — максимальный размер чанка в мегабайтах. По умолчанию 100.
• --workers-count — количество параллельных загрузок. По умолчанию: 1.
• --process — автоматически запустить обработку после загрузки. По умолчанию false.
• --upload-retries — Число попыток повторной загрузки при ошибке. По умолчанию 3.
• --work-dir — Рабочая директория для чанков и manifest.json. По умолчанию автогенерация.
• --resume — Возобновить по существующему manifest.json. По умолчанию false. Требует параметра --work-dir.
• --dry-run — Создать чанки без загрузки на сервер. По умолчанию false.
• --retry-failed — Повторно обработать чанки со статусом error. По умолчанию false.
• --continue-on-error — Продолжать при ошибках в отдельных чанках. По умолчанию false.

warning

Используйте флаг --continue-on-error только при осознанной готовности к частичному импорту данных!

При использовании флага обработка продолжится даже если некоторые чанки завершатся с ошибкой. Это может привести к:

• ответам на сообщения без исходных сообщений
• реакциям на отсутствующие объекты
• вложениям без родительских постов

Когда использовать:

• При отладке — чтобы выявить все проблемные чанки за один прогон.
• Когда частичная потеря данных допустима.

Примеры команд с расширенными опциями

Возобновление после сбоя

Если выполнение прервалось (сбой сети, ошибка, ручная остановка), можно возобновить процесс:

timectl import split upload ./data.zip \
  --work-dir=./import_chunks \
  --resume \
  --process

примечание

Флаг --work-dir должен указывать на директорию с файлом manifest.json, созданную при первом запуске, по умолчанию директория называется import_chunks.

Повторная обработка проблемных чанков

Если часть чанков завершилась с ошибкой, можно повторно обработать только их:

timectl import split upload ./data.zip \
  --work-dir=./import_chunks \
  --resume \
  --process \
  --retry-failed

Проверка разбиения без загрузки

Чтобы посмотреть, как архив будет разбит на чанки, без фактической загрузки на сервер:

timectl import split ./data.zip --chunk-size=45

или

timectl import split upload ./data.zip --chunk-size=150 --dry-run

В директории import_chunks/ будут созданы:

• manifest.json — метаданные о разбиении
• chunk_0001.zip, chunk_0002.zip, ... — файлы чанков

Проверка статуса импорта

Файл manifest.json содержит информацию о состоянии каждого чанка.

Общая статистика

cat ./import_chunks/manifest.json | jq '{
  total: .chunks | length,
  success: [.chunks[] | select(.status == "success")] | length,
  uploaded: [.chunks[] | select(.status == "uploaded")] | length,
  failed: [.chunks[] | select(.status == "error")] | length
}'

Просмотр проблемных чанков

cat ./import_chunks/manifest.json | jq '.chunks[] | select(.status == "error") | {
  index,
  zip_name,
  error: .process.error_details
}'

Статусы чанков

Статус	Описание
built	Чанк создан
uploaded	Загружен на сервер, ожидает обработки
success	Успешно обработан
error	Ошибка при загрузке или обработке