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

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

Канонічне посилання: https://flashdata.dev/uk/docs/guides/bulk
Переглянуто: 2026-11-05 від 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/uk/docs/guides/enrich-youtube-videos/reference.md)
- [Batch проти Bulk](https://flashdata.dev/uk/docs/reference/batch-and-bulk/reference.md#choose)
- [Bulk API дитячий майданчик](https://flashdata.dev/uk/docs/reference/bulk-processing/reference.md#playground)
- [Масове завантаження відео з YouTube](https://flashdata.dev/uk/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/uk/docs/guides/flashdata-cli/reference.md#install)
- [Створіть ключ API](https://flashdata.dev/app/api-keys)
- [Доступ до агента та вимога](https://flashdata.dev/uk/docs/guides/agent-access/reference.md)
- [Використовуйте HTTP замість](https://flashdata.dev/uk/docs/reference/bulk-processing/reference.md#endpoints)

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

## 1. Приготувати IDs

Запуск у новій папці роботи. Використовуйте UTF-8 текст з одним 11-character відео 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/uk/docs/guides/bulk/reference.md#progress)
- [Відновлення після закінчення часу](https://flashdata.dev/uk/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.

Expect 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/uk/docs/guides/bulk/reference.md#controls)
- [Затримка результатів](https://flashdata.dev/uk/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 NAME до кожного командного рядка.

| Ситуація | Фіксація |
| --- | --- |
| 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/uk/docs/guides/cli-automation/reference.md#recover)
- [Обмеження ставок](https://flashdata.dev/uk/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/uk/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/uk/docs/guides/bulk/reference.md#audit)
- [Manifest, частини та посилання на утримання](https://flashdata.dev/uk/docs/reference/bulk-processing/reference.md#downloadBulkJobManifest)

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

## Додайте до свого сховища

Збережіть свої облікові дані провайдера, як storage.json у робочій папці перед запуском цієї команди. Використовуйте поля провайдера, пов'язані з цим, зберігайте файл. CLI's --storage-config читає цей файл JSON і вибирає result_storage для даних або зберігання для медіа. --options також займає шлях до файлів, не внутраючи JSON.

- [Основні напрямки діяльності компанії](https://flashdata.dev/uk/docs/sources/youtube_download/reference.md#storage)
- [Зберігання доставки та об'єктних шляхів](https://flashdata.dev/uk/docs/reference/bulk-processing/reference.md#storage)
- [Налаштування запиту Bulk API](https://flashdata.dev/uk/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
```

