# Обработка файлов Bulk

Обработайте файл видео IDs, извлеките каждую часть результата и проверьте покрытие перед импортом набора данных в ваше приложение.

Каноническая ссылка: https://flashdata.dev/ru/docs/guides/bulk
Разработчик: 2026-11-05 by FlashData

<a id="first-task"></a>

## От файла ID до проверенного набора данных

Используйте этот рабочий процесс для видео каталога, коллекции исследований или очереди приема. Один файл использует один источник и один и тот же параметр для каждого ID. Начните с двухвидео-образца метаданных, а затем замените свой собственный файл.

### Файлы, созданные этим рабочим процессом

```text
video-ids.txt → Работа Bulk → bulk-results.ndjson
  Результаты audit/completed.ndjson для вашего приложения
  audit/failed-video-ids.txt подтвердил неполадки в обзоре
  Вводы audit/missing.ndjson, результаты которых отсутствуют
  Покрытие audit/summary.json и подсчет результатов
```

- [Храните запись приложения IDs с небольшим списком](https://flashdata.dev/ru/docs/guides/enrich-youtube-videos/reference.md)
- [Batch против Bulk](https://flashdata.dev/ru/docs/reference/batch-and-bulk/reference.md#choose)
- [Игровая площадка Bulk API](https://flashdata.dev/ru/docs/reference/bulk-processing/reference.md#playground)
- [Массовая загрузка видео с YouTube](https://flashdata.dev/ru/products/youtube-download#bulk-downloads)

<a id="before-you-start"></a>

## Прежде чем начать

Установите CLI и используйте существующий профиль или FLASHDATA_API_KEY с разрешения youtube_metadata. Подтвердите data.accessVerified: true и просмотрите баланс, цены на два запроса и текущие лимиты. Для вашего собственного файла используйте счет ID при проверке цены. Каждый обработанный ID представляет собой отдельный запрос, а не один фиксированный заряд для файла.

Используйте Bash с jq или PowerShell 7 для шагов 1–3. Факультативный аудит импорта на этапе 4 использует Python 3.10+ и его стандартную библиотеку. Сам CLI не требует ни Node.js, ни Python.

### Бесплатный доступ и проверка аккаунта

```bash
flashdata auth status --json
flashdata account balance --json
flashdata account pricing --source youtube_metadata --request-count 2
flashdata account limits
```

- [Установите CLI](https://flashdata.dev/ru/docs/guides/flashdata-cli/reference.md#install)
- [Создайте ключ API](https://flashdata.dev/app/api-keys)
- [Агентский доступ и претензии](https://flashdata.dev/ru/docs/guides/agent-access/reference.md)
- [Используйте HTTP вместо](https://flashdata.dev/ru/docs/reference/bulk-processing/reference.md#endpoints)

<a id="prepare"></a>

## 1. Подготовить IDs

Запустите новую рабочую папку. Используйте текст UTF-8 с одним 11-символом видео ID в строке, а не YouTube URL. Максимальный размер файла 2 GiB. Удалите пустые строки и дубликаты: CLI отклоняет неправильно сформированный вход, а повторный IDs обрабатывается отдельно.

### Bash

#### Bash

```bash
# Run in a new working directory.
(
  set -euC
  printf '%s\n' 'jNQXAC9IVRw' 'dQw4w9WgXcQ' > video-ids.txt
)
cat video-ids.txt
```


### PowerShell 7

#### PowerShell 7

```powershell
if (Test-Path -LiteralPath video-ids.txt) { throw 'Keep the existing file or use a new folder.' }
$idsFile = Join-Path (Get-Location) 'video-ids.txt'
$idsText = [string]::Join([char]10, @('jNQXAC9IVRw', 'dQw4w9WgXcQ', ''))
[IO.File]::WriteAllText($idsFile, $idsText, [Text.UTF8Encoding]::new($false))
Get-Content -LiteralPath video-ids.txt
```



<a id="run"></a>

## 2. Запустите файл

CLI создает работу, загружает файл, начинает обработку и сохраняет каждую часть результата в один файл NDJSON. Используйте новый выходной путь. Местный забег ID в первую очередь сохраняет удаленную квитанцию о работе для восстановления.

### Bash

#### Bash

```bash
flashdata bulk run --source youtube_metadata \
  --input video-ids.txt --run-id bulk-first \
  --output bulk-results.ndjson --timeout 30m --json
```


### PowerShell 7

#### PowerShell 7

```powershell
flashdata bulk run --source youtube_metadata `
  --input video-ids.txt --run-id bulk-first `
  --output bulk-results.ndjson --timeout 30m --json
```


- [Проверить прогресс в другом терминале](https://flashdata.dev/ru/docs/guides/bulk/reference.md#progress)
- [Восстановление после тайм-аута](https://flashdata.dev/ru/docs/guides/bulk/reference.md#controls)

<a id="results"></a>

## 3. Проверить результаты

Открыть bulk-results.ndjson. Каждая строка представляет собой запись JSON с индексом, video_id и статусом. Успешные строки содержат массив результатов; неудачные строки содержат ошибку. Присоединяйтесь к записям на входе по нулевому индексу, а не по порядку файлов. Команда Bash использует jq.

### Один успешный ряд · сокращенный пример

```json
{"index":0,"video_id":"jNQXAC9IVRw","source":"youtube_metadata","status":"completed","results":[{"videoId":"jNQXAC9IVRw","title":"Example video title"}]}
```

### Bash

#### Bash

```bash
# Bash + jq: read each record without loading the whole file.
jq -c '{index, video_id, status, title: .results[0].title, error}' bulk-results.ndjson
```


### PowerShell 7

#### PowerShell 7

```powershell
Get-Content -LiteralPath bulk-results.ndjson | ForEach-Object {
  $row = $_ | ConvertFrom-Json
  $title = if ($row.results) { $row.results[0].title } else { $null }
  [pscustomobject]@{ index = $row.index; video_id = $row.video_id; status = $row.status; title = $title; error = $row.error }
}
```



<a id="audit"></a>

## 4. Проверьте покрытие перед импортом

Сохраните audit-bulk.py ниже. Запустите его против неизмененного входного файла и всех извлеченных частей результата. Он проверяет каждый индекс, видео ID и источник, отклоняет дубликаты строк результатов и отделяет подтвержденные сбои от отсутствующих результатов. Для другого источника добавьте --source SOURCE_ID.

Ожидайте inputRows: 2, завершенный: 2, неудачный: 0, пропущенный: 0 и allSucceeded: true для успешной выборки. Только заполненные строки относятся к импорту результата приложения. Сохраняйте вместе с ними резюме аудита и неудачные результаты.


<a id="audit-script"></a>

### Скачать audit-bulk.py

Создайте audit-bulk.py рядом с video-ids.txt и bulk-results.ndjson в рабочей папке. Скопируйте полный код ниже и сохраните его.

Скрипт считывает файлы строка за строкой и использует локальный индекс SQLite вместо загрузки всего набора данных в память. Для этого требуется валидированный входной файл видео IDs. Каждый аудит использует новый каталог вывода; частичные файлы остаются отдельными до окончания анализа.

#### audit-bulk.py

```python
# audit-bulk.py — Python 3.10+, standard library only; no network requests.
import argparse
import json
import re
import sqlite3
import sys
from contextlib import ExitStack
from pathlib import Path

parser = argparse.ArgumentParser()
parser.add_argument('--input', required=True)
parser.add_argument('--results', required=True)
parser.add_argument('--out', required=True)
parser.add_argument('--source', default='youtube_metadata')
args = parser.parse_args()
out = Path(args.out)
try:
    out.mkdir()  # Keep any previous audit. Use a new directory for another attempt.
    with ExitStack() as stack:
        db = sqlite3.connect(out / 'index.sqlite')
        stack.callback(db.close)
        db.execute('CREATE TABLE inputs (idx INTEGER PRIMARY KEY, video_id TEXT, outcome TEXT)')
        count = 0
        with open(args.input, encoding='utf-8-sig') as inputs:
            for index, line in enumerate(inputs):
                video_id = line.strip()
                if not re.fullmatch(r'[A-Za-z0-9_-]{11}', video_id):
                    raise ValueError('Invalid ID on input line ' + str(index + 1))
                db.execute('INSERT INTO inputs VALUES (?, ?, NULL)', (index, video_id))
                count += 1
        if not count:
            raise ValueError('The input file is empty.')
        db.commit()
        files = {name: stack.enter_context(open(out / (name + '.part'), 'x', encoding='utf-8'))
                 for name in ['completed.ndjson', 'failed.ndjson', 'missing.ndjson', 'failed-video-ids.txt']}
        completed = failed = 0
        with open(args.results, encoding='utf-8-sig') as results:
            for line_number, line in enumerate(results, 1):
                if not line.strip():
                    continue
                row = json.loads(line)
                if not isinstance(row, dict) or type(row.get('index')) is not int:
                    raise ValueError('Invalid result index on line ' + str(line_number))
                expected = db.execute('SELECT video_id, outcome FROM inputs WHERE idx = ?',
                                      (row['index'],)).fetchone()
                if (not expected or row.get('video_id') != expected[0]
                        or row.get('source') != args.source or expected[1] is not None):
                    raise ValueError('Unknown, duplicate or mismatched result on line ' + str(line_number))
                status = row.get('status')
                if status not in ['completed', 'failed']:
                    raise ValueError('Unexpected item status on line ' + str(line_number))
                if status == 'completed':
                    if not isinstance(row.get('results'), list):
                        raise ValueError('Completed row is missing its results array.')
                    if args.source == 'youtube_metadata' and (len(row['results']) != 1
                            or not isinstance(row['results'][0], dict)
                            or row['results'][0].get('videoId') != expected[0]):
                        raise ValueError('Metadata does not belong to the requested video.')
                    completed += 1
                else:
                    failed += 1
                db.execute('UPDATE inputs SET outcome = ? WHERE idx = ?', (status, row['index']))
                files[status + '.ndjson'].write(json.dumps(row, ensure_ascii=False) + '\n')
        db.commit()
        missing = 0
        for index, video_id in db.execute('SELECT idx, video_id FROM inputs WHERE outcome IS NULL ORDER BY idx'):
            files['missing.ndjson'].write(json.dumps({'index': index, 'video_id': video_id,
                                                     'status': 'missing_result'}) + '\n')
            missing += 1
        for (video_id,) in db.execute("SELECT video_id FROM inputs WHERE outcome = 'failed' GROUP BY video_id ORDER BY MIN(idx)"):
            files['failed-video-ids.txt'].write(video_id + '\n')
        summary = {'source': args.source, 'inputRows': count, 'completed': completed,
                   'failed': failed, 'missing': missing, 'coverageComplete': missing == 0,
                   'allSucceeded': failed == 0 and missing == 0}
    for name in files:
        (out / (name + '.part')).rename(out / name)
    with open(out / 'summary.json', 'x', encoding='utf-8') as output:
        json.dump(summary, output, indent=2)
    print(json.dumps(summary, indent=2))
    sys.exit(0 if summary['allSucceeded'] else 2)
except Exception as error:
    print(str(error), file=sys.stderr)
    print('Audit not complete. Preserve this directory and inspect the inputs/results.', file=sys.stderr)
    sys.exit(1)
```


<a id="run-audit"></a>

### Провести импортный аудит

Запустите из папки, содержащей сценарий, исходный ввод и загруженные результаты. Аудит считывает только локальные файлы.

#### Bash

##### Bash

```bash
python3 audit-bulk.py --input video-ids.txt --results bulk-results.ndjson --out audit
```


#### PowerShell 7

##### PowerShell 7

```powershell
python audit-bulk.py --input video-ids.txt --results bulk-results.ndjson --out audit
```



<a id="import"></a>

### Импорт завершенных строк и проведение аудита

| Файл / сигнал | Используйте его таким образом |
| --- | --- |
| completed.ndjson | Присоединяйтесь по индексу к исходному файлу. Используйте video_id для ключа каталога; сохраняйте идентификатор job/snapshot при хранении истории обновления. |
| failed.ndjson + failed-video-ids.txt | Проверяйте ошибки перед тем, как повторно использовать IDs. Успешные и отсутствующие элементы исключены из списка неудачных ID. |
| missing.ndjson | Восстановите все части результатов из существующей работы, а затем проверьте восстановленный файл в новом каталоге. Пропущенный результат не является подтвержденным неудавшимся запросом. |
| summary.json | coverageComplete проверяет, что каждый ввод имеет результат. allSucceeded также не требует неудачных видео. Аудит выходит из 2 либо из-за сбоев, либо из-за пропущенных строк. |
| Выход 1/нет summary.json | Неверные или несоответствующие данные: проверьте сохраненные файлы. Не публикуйте частичный аудит как полный набор данных. |

- [Восстановление существующих результатов](https://flashdata.dev/ru/docs/guides/bulk/reference.md#controls)
- [Результат удержания](https://flashdata.dev/ru/docs/guides/save-results/reference.md#bulk)

<a id="item-failures"></a>

## Если некоторые видео провалятся

Завершенная работа Bulk может содержать неудачные видео. CLI также сохраняет эти строки, а затем выходит с bulk_item_failures. Проверьте свои ошибки, прежде чем решить, следует ли повторно использовать отдельные IDs; не отправляйте весь файл автоматически.

### Показать только неудачные записи · jq

```bash
jq -c 'select(.status != "completed") | {index, video_id, status, error}' bulk-results.ndjson
```


<a id="progress"></a>

## Отслеживание прогресса и потенциала

Прочитайте сохраненную работу, пока исходная команда работает. CLI обертывает статус под данные; прямой HTTP обертывает его под работу. Проверьте с задержкой и обратной связью и отметьте Retry-After на 429. Местный тайм-аут или закрытый терминал не отменяют удаленную работу.

| Поле | Читайте так, как |
| --- | --- |
| input.scannedBytes / input.bytes | Прогресс сканирования файлов, не завершенные запросы или загруженные носители. |
| input.complete | Все вводимые данные были прочитаны; запросы и упаковка результатов все еще могут работать. |
| counts.accepted / completed / failed | Представлены IDs, успешные видео и неудачные видео. Выдающийся = принятый − завершенный − провалился. |
| counts.invalid / results | Недействительные входные линии / записи, упакованные до сих пор. HTTP может принимать файлы, содержащие недействительные строки; CLI проверяет ввод перед загрузкой. |
| delivery | Доставка клиентских данных: uploadedParts, retryCount, storageType и customerStorage. Отдельно от загрузки медиа каждого видео. |

### Bash

#### Bash

```bash
(
set -eu
BULK_ID=$(flashdata runs show bulk-first --json | jq -er '.data.remoteId')
flashdata bulk get "$BULK_ID" --json
)
```


### PowerShell 7

#### PowerShell 7

```powershell
$run = flashdata runs show bulk-first --json | ConvertFrom-Json
if ($LASTEXITCODE -ne 0 -or -not $run.data.remoteId) { throw 'Read the saved run before continuing.' }
flashdata bulk get $run.data.remoteId --json
```



<a id="states"></a>

### Знать, когда ждать или действовать

Bulk подается постепенно в пределах емкости maxPendingJobs вашей учетной записи, совместно с другими вакансиями. Недостаточные кредиты или неактивная подписка могут приостановить работу. Проверьте pauseReason перед возобновлением.

| государство | Следующее действие |
| --- | --- |
| awaiting_upload | Загрузите файл, а затем начните уже существующую работу. |
| running / finalizing | Подожди. Завершение может включать незавершенные запросы, упаковку и доставку на хранение. |
| paused | Разрешите pauseReason и возобновите ту же работу. |
| completed | Скачайте все части результата и проверьте неудачные строки. |
| failed / cancelled | Проверьте job.error и сохраненную квитанцию. Принятая работа может по-прежнему быть finish; заполненный манифест не публикуется. |


<a id="controls"></a>

## Возобновить прерванный рабочий процесс

После локального тайм-аута или прерывания результата загрузки, сначала восстановите оптом. Это считывает существующую удаленную работу; он не отправляет набор данных снова. Используйте новое имя выходного файла. Ошибка partial_result может оставлять частичный локальный файл, сохраняя его отдельно от восстановленного результата.

Используйте один и тот же профиль CLI и каталог состояния во всем. Для именованного профиля добавьте имя --profile в каждую команду.

| Положение | исправлять |
| --- | --- |
| awaiting_upload | runs recover не воспроизводит загрузку или запуск. Проверьте сохраненный ID, загрузите статус и исходный файл, прежде чем явно продолжить. |
| paused | Решите заявленную причину, а затем используйте объемное резюме с сохраненным ID. Восстановление не возобновляет автоматически приостановленную работу. |
| 401 / 403 | Восстановить действительный доступ к учетной записи и источнику. Повторно использовать ту же работу после аутентификации. |
| 409 / 410 | 409: результаты не готовы. 410: сохраненные результаты истекли; используйте сохраненную копию. |
| Скачать URL | Подтвердите, что старая работа никогда не начиналась до создания новой. Неопределенное представление является причиной, чтобы сначала прочитать сохраненный ID. |

### Восстановить сохраненный забег

```bash
flashdata runs show bulk-first --json
flashdata runs recover bulk-first --output recovered-results.ndjson --timeout 30m --json
```

- [CLI Восстановление и повторяющиеся запуски](https://flashdata.dev/ru/docs/guides/cli-automation/reference.md#recover)
- [Ограничения по ставкам](https://flashdata.dev/ru/docs/guides/usage-and-limits/reference.md)

<a id="pause"></a>

### Приостановить или возобновить работу

Замените BULK_ID на ID от runs show с первой массой. Пауза останавливает новые представления и упаковку результатов; принятые запросы продолжаются. Решите pauseReason перед возобновлением. Для измененных опций или учетных данных хранения обновите существующую работу через Bulk API.

#### Пауза

```bash
flashdata bulk pause BULK_ID --json
```

#### Резюме после устранения причины

```bash
flashdata bulk resume BULK_ID --json
```

- [Обновление работы Bulk](https://flashdata.dev/ru/docs/reference/bulk-processing/reference.md#updateBulkJob)

<a id="cancel"></a>

### Отменить навсегда

Отменять только тогда, когда вы намерены отказаться от работы. Отмена не отменяет принятые запросы или возврат выполненных работ. Графики все еще могут меняться, и ни один заполненный манифест не публикуется. Пауза обратима.

#### Отменить выбранную работу

```bash
flashdata bulk cancel BULK_ID --json
```


<a id="manifest"></a>

## Восстановить каждую часть результата

Для существующей завершенной работы CLI следует своему манифесту и сохраняет каждую часть результата в один файл NDJSON. Используйте новый выходной путь и запустите аудит импорта в объединенном файле. Результаты загрузки описывают доставленные носители; они не являются MP4 или аудио байтами.

### Получите все части от существующей работы

```bash
flashdata bulk results BULK_ID --output saved-results.ndjson --timeout 30m --json
```

- [Проверить наличие набора данных](https://flashdata.dev/ru/docs/guides/bulk/reference.md#audit)
- [Манифест, части и ссылка на удержание](https://flashdata.dev/ru/docs/reference/bulk-processing/reference.md#downloadBulkJobManifest)

<a id="storage"></a>

## Доставить в ваше хранилище

Сохраните учетные данные вашего провайдера в виде storage.json в рабочей папке перед запуском этой команды. Используйте поля провайдера, связанные ниже; сохраняйте файл приватным. CLI --storage-config читает этот файл JSON и выбирает result_storage для данных или хранения для носителей. --options также принимает путь файла, а не встроенный JSON.

- [Поля учетных данных провайдера](https://flashdata.dev/ru/docs/sources/youtube_download/reference.md#storage)
- [Доставка хранения и пути объекта](https://flashdata.dev/ru/docs/reference/bulk-processing/reference.md#storage)
- [Настройка запроса Bulk API](https://flashdata.dev/ru/docs/reference/bulk-processing/reference.md#playground)

<a id="storage-run"></a>

### Запуск с сохраненной конфигурацией хранилища

#### Добавить хранилище в рабочий процесс метаданных

```bash
flashdata bulk run --source youtube_metadata --input video-ids.txt --storage-config storage.json --run-id bulk-with-storage --output stored-results.ndjson --timeout 30m --json
```

