# Przetwarzanie plików Bulk

Przetworzyć plik wideo IDs, pobrać każdą część wyniku i sprawdzić pokrycie przed importem zbioru danych do aplikacji.

Odniesienie kanoniczne: https://flashdata.dev/pl/docs/guides/bulk
Przegląd: 2026-11-05 przez FlashData

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

## Z pliku ID do zaznaczonego zbioru danych

Użyj tego przepływu pracy do katalogu wideo, zbierania badań lub kolejki spożycia. Jeden plik używa jednego źródła i tych samych opcji dla każdego ID. Zacznij od próbki metadanych dwuwideo, a następnie podmień swój własny plik.

### Pliki wytwarzane przez ten przepływ pracy

```text
video-ids.txt → Bulk praca → bulk-results.ndjson
  → Wyniki audit/completed.ndjson dla Twojej aplikacji
  → audit/failed-video-ids.txt potwierdzone niepowodzenie przeglądu
  → Wejścia audit/missing.ndjson, których wyniki są brakujące
  → Zakres audit/summary.json i liczba wyników
```

- [Zachowaj zapis aplikacji IDs z małą listą](https://flashdata.dev/pl/docs/guides/enrich-youtube-videos/reference.md)
- [Batch wobec Bulk](https://flashdata.dev/pl/docs/reference/batch-and-bulk/reference.md#choose)
- [Bulk API plac zabaw dla dzieci](https://flashdata.dev/pl/docs/reference/bulk-processing/reference.md#playground)
- [Masowe pobieranie filmów z YouTube](https://flashdata.dev/pl/products/youtube-download#bulk-downloads)

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

## Zanim zaczniesz

Zainstaluj CLI i użyj istniejącego profilu lub FLASHDATA_API_KEY za pozwoleniem youtube_metadata. Potwierdź data.accessVerified: true i sprawdź dostępne saldo, ceny za dwa wnioski i aktualne limity. Dla własnego pliku, użyj jego ID liczyć podczas sprawdzania cen. Każdy przetworzony ID jest odrębnym zapytaniem, nie jest to jedna płaska opłata za plik.

Należy stosować Bash z jq lub PowerShell 7 w krokach 1–3. Opcjonalny audyt przywozowy na etapie 4 wykorzystuje Python 3.10 + i jego standardową bibliotekę. Sam CLI nie wymaga Node.js ani Python.

### Bezpłatny dostęp i kontrole rachunków

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

- [Zainstaluj CLI](https://flashdata.dev/pl/docs/guides/flashdata-cli/reference.md#install)
- [Utwórz klucz API](https://flashdata.dev/app/api-keys)
- [Dostęp do agenta i roszczenie](https://flashdata.dev/pl/docs/guides/agent-access/reference.md)
- [Użyj HTTP zamiast](https://flashdata.dev/pl/docs/reference/bulk-processing/reference.md#endpoints)

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

## 1. Przygotować IDs

Uruchom nowy folder roboczy. Użyj tekstu UTF-8 z jednym wideo 11- znaków ID na linię, a nie YouTube URL. Maksymalny rozmiar pliku to 2 GiB. Usuń puste linie i duplikaty: CLI odrzuca błędne wejście i powtarzane IDs są przetwarzane oddzielnie.

### 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. Uruchom plik

CLI tworzy zadanie, wysyła plik, rozpoczyna przetwarzanie i zapisuje każdą część wyniku do jednego pliku NDJSON. Użyj nowej ścieżki wyjścia. Lokalny bieg ID bulk- pierwszy zachowuje zdalny pokwitowanie zadania do odzyskania.

### 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
```


- [Sprawdź postęp w innym terminalu](https://flashdata.dev/pl/docs/guides/bulk/reference.md#progress)
- [Odzyskiwanie po przerwie czasowej](https://flashdata.dev/pl/docs/guides/bulk/reference.md#controls)

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

## 3. Sprawdzić wyniki

Otwórz bulk-results.ndjson. Każda linia jest rekordem JSON z indeksem, video_id i statusem. Udane wiersze zawierają tablicę wyników; błędne wiersze zawierają błąd. Dołącz rekordy do wejścia przez indeks zerowy, a nie kolejność plików. Polecenie Bash używa jq.

### Jeden udany wiersz · skrócony przykład

```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. Sprawdź zakres przed przywozem

Zapisz audit-bulk.py poniżej. Uruchom go na niezmienionym pliku wejściowym i wszystkich odzyskanych częściach wyników. Sprawdza każdy indeks, wideo ID i źródło, odrzuca duplikaty wierszy wyników i oddziela potwierdzone błędy od brakujących wyników. Dla innego źródła dodaj --source SOURCE_ID.

Oczekiwanie inputRows: 2, zakończone: 2, nie powiodło się: 0, brakuje: 0 i allSucceeded: true dla udanej próbki. Tylko wypełnione wiersze należą do importu wyniku aplikacji. Utrzymywanie podsumowania audytu i nieskuteczne wyniki obok nich.


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

### Zapisz audit-bulk.py

Utwórz audit-bulk.py obok video-ids.txt i bulk-results.ndjson w katalogu roboczym. Skopiuj do niego cały kod poniżej i zapisz go.

Skrypt odczytuje pliki po linii i używa lokalnego indeksu SQLite zamiast wczytywania całego zbioru danych do pamięci. Wymaga on walidacji pliku wejściowego wideo IDs. Każdy audyt używa nowego katalogu wyjściowego; pliki częściowe pozostają oddzielone do czasu zakończenia parsowania.

#### 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>

### Uruchom audyt przywozu

Uruchom z folderu zawierającego skrypt, oryginalne wejście i pobrane wyniki. Audyt czyta tylko lokalne pliki.

#### 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>

### Import zakończonych wierszy i prowadzenie audytu

| Plik / sygnał | Użyj tego w ten sposób |
| --- | --- |
| completed.ndjson | Dołącz przez indeks do oryginalnego pliku. Użyj video_id jako klucza katalogowego; zachowuj tożsamość job/snapshot podczas przechowywania historii odświeżania. |
| failed.ndjson + failed-video-ids.txt | Przed umyślnym ponownym uruchomieniem tych IDs należy ponownie sprawdzić błędy. Pozytywne i brakujące elementy są wyłączone z listy niepowodzeń- ID. |
| missing.ndjson | Odzyskiwanie wszystkich wyników z istniejącego zadania, a następnie kontrola odzyskanego pliku w nowym katalogu. Brak wyjścia nie jest potwierdzonym nieudanym zapytaniem. |
| summary.json | coverageComplete sprawdza, czy każde wejście ma wynik. allSucceeded również nie wymaga nieudanych filmów. Audyt opuszcza 2 w przypadku awarii lub brakujących wierszy. |
| Exit 1 / no summary.json | Nieprawidłowe lub źle dopasowane dane: sprawdź zapisane pliki. Nie należy publikować audytu częściowego jako kompletnego zbioru danych. |

- [Odzyskanie istniejących wyników](https://flashdata.dev/pl/docs/guides/bulk/reference.md#controls)
- [Retencja wyników](https://flashdata.dev/pl/docs/guides/save-results/reference.md#bulk)

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

## Jeśli niektóre filmy zawiodą

Zakończone zadanie Bulk może zawierać nieudane filmy. CLI również zapisuje te wiersze, a następnie wychodzi z bulk_item_failures. Sprawdź ich błędy przed podjęciem decyzji, czy należy ponownie spróbować IDs; nie usuwaj automatycznie całego pliku.

### Pokaż tylko nieudane rekordy · jq

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


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

## Postępy i przepustowość toru

Przeczytaj zapisane zadanie podczas wykonywania oryginalnego polecenia. Status CLI obejmuje dane; bezpośredni HTTP obejmuje go w trakcie pracy. Sprawdź z opóźnieniem i wycofaniem, i honorować Retry-After na 429. Lokalny timeout lub zamknięty terminal nie anuluje zdalnej pracy.

| Pole | Przeczytaj jako |
| --- | --- |
| input.scannedBytes / input.bytes | Postęp skanowania plików, niezakończone zapytania lub przesłane media. |
| input.complete | Wszystkie dane wejściowe zostały przeczytane; pytania i opakowania mogą być nadal uruchomione. |
| counts.accepted / completed / failed | Przedstawione IDs, udane filmy i nieudane filmy. Wybitny = zaakceptowany − zakończony − nieudany. |
| counts.invalid / results | Nieprawidłowe linie wejściowe / rekordy zapakowane do tej pory. HTTP może akceptować pliki zawierające nieprawidłowe linie; przed wysłaniem uwierzytelnia wejście CLI. |
| delivery | Dostawa danych klienta: uploadedParts, retryCount, storageType i customerStorage. Oddziel się od transmisji każdego wideo. |

### 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>

### Wiedz, kiedy czekać lub działać

Bulk przekazuje stopniowo w ramach pojemności Twojego konta maxPendingJobs, dzielonej z innymi zadaniami. Niewystarczające kredyty lub nieaktywna subskrypcja może wstrzymać pracę. Przed wznowieniem należy sprawdzić pauseReason.

| Państwo | Następna akcja |
| --- | --- |
| awaiting_upload | Wyślij plik, a następnie uruchom istniejące zadanie. |
| running / finalizing | Czekaj. Finalizacja może obejmować niedokończone zapytania, pakowania i przechowywania dostawy. |
| paused | Rozwiąż pauseReason i wznowij tę samą pracę. |
| completed | Pobieranie wszystkich wyników i kontrolowanie nieudanych wierszy. |
| failed / cancelled | Sprawdź job.error i zapisany paragon. Przyjmowana praca może nadal być zgodna z finish; nie publikuje się wypełnionego manifestu. |


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

## Wznowienie przerwanego przepływu pracy

Po lokalnym timeout lub przerywany pobór wyników, odzyskać bulk- pierwszy. Odczytuje to istniejące zdalne zadanie; nie przekazuje ponownie zbioru danych. Użyj nowej nazwy pliku wyjściowego. Błąd partial_result może pozostawić częściowy plik lokalny; należy go oddzielić od odzyskanego wyniku.

Użyj tego samego profilu CLI i katalogu stanu w całym. Dla nazwanego profilu dodaj nazwę --profile do każdego polecenia.

| Sytuacja | Napraw |
| --- | --- |
| awaiting_upload | runs recover nie odtwarza wysyłania ani uruchamiania. Sprawdź zapisany ID, wgraj status i oryginalny plik przed wyraźną kontynuacją. |
| paused | Rozwiąż zgłoszoną przyczynę, a następnie użyj masowego CV z zapisanym ID. Odzyskiwanie nie wznawia automatycznie wstrzymanej pracy. |
| 401 / 403 | Przywróć poprawny dostęp do konta i źródła. Ponowne użycie tego samego zadania po ustaleniu uwierzytelniania. |
| 409 / 410 | 409: wyniki nie są gotowe. 410: zapisane wyniki wygasły; użyj zapisanej kopii. |
| Przeterminowane wysyłanie URL | Potwierdź, że stara praca nigdy nie zaczęła się przed stworzeniem nowej. Niepewne złożenie jest powodem, aby najpierw przeczytać zapisane ID. |

### Odzyskiwanie zapisanego biegu

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

- [Odzyskiwanie CLI i powtarzające się operacje](https://flashdata.dev/pl/docs/guides/cli-automation/reference.md#recover)
- [Limity stóp procentowych](https://flashdata.dev/pl/docs/guides/usage-and-limits/reference.md)

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

### Wstrzymać lub wznowić pracę

Zastąpić BULK_ID za pomocą ID od bulk- pierwszego bulk- runs show. Pauza zatrzymuje nowe zgłoszenia i opakowania wyników; akceptowane pytania nadal. Rozstrzygnij pauseReason przed wznowieniem. W przypadku zmienionych opcji lub uwierzytelniania pamięci, uaktualnij istniejące zadanie za pośrednictwem Bulk API.

#### Pauza

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

#### Wznowić po ustaleniu przyczyny

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

- [Aktualizacja zadania Bulk](https://flashdata.dev/pl/docs/reference/bulk-processing/reference.md#updateBulkJob)

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

### Anuluj na stałe

Odwołaj tylko wtedy, gdy zamierzasz zrezygnować z pracy. Anulowanie nie cofnie zaakceptowanych zapytań lub zwrotu zakończonych prac. Liczenia mogą się jeszcze zmienić, a nie zostanie opublikowany żaden wypełniony manifest. Pauza jest odwracalna.

#### Anuluj wybrane zadanie

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


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

## Pobieranie każdej części wyniku

Dla istniejącego zadania zakończonego, CLI podąża za manifestem i zapisuje każdą część wyniku w jednym pliku NDJSON. Użyj nowej ścieżki wyjścia i uruchom audyt importu w połączonym pliku. Pobieranie wyników opisuje dostarczone media; nie są one MP4 lub audio bajtów.

### Pobierz wszystkie części z istniejącej pracy

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

- [Sprawdź zakres zbioru danych](https://flashdata.dev/pl/docs/guides/bulk/reference.md#audit)
- [Manifest, części i odniesienie do zatrzymania](https://flashdata.dev/pl/docs/reference/bulk-processing/reference.md#downloadBulkJobManifest)

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

## Dostarcz do magazynu

Przed uruchomieniem tego polecenia zapisz swoje referencje dostawcy jako storage.json w folderze roboczym. Użyj pól dostawcy powiązanych poniżej; zachowuj plik w tajemnicy. W CLIjest --storage-config przeczytaj to JSON plik i wybieranie result_storage dla danych lub przechowywania dla mediów. --options pobiera także ścieżkę pliku, a nie inline JSON.

- [Pola kredytowe dostawcy](https://flashdata.dev/pl/docs/sources/youtube_download/reference.md#storage)
- [Składowanie i ścieżki obiektów](https://flashdata.dev/pl/docs/reference/bulk-processing/reference.md#storage)
- [Konfiguracja żądania Bulk API](https://flashdata.dev/pl/docs/reference/bulk-processing/reference.md#playground)

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

### Uruchom z zapisaną konfiguracją pamięci masowej

#### Dodawanie pamięci masowej do przepływu pracy metadanych

```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
```

