# Bulk Dateiverarbeitung

Verarbeiten Sie eine Videodatei IDs, rufen Sie jeden Ergebnisteil ab und überprüfen Sie die Abdeckung, bevor Sie den Datensatz in Ihre Anwendung importieren.

Kanonische Referenz: https://flashdata.dev/de/docs/guides/bulk
Test: 2026-11-05 von FlashData

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

## Von einer ID-Datei zu einem geprüften Datensatz

Verwenden Sie diesen Workflow für einen Videokatalog, eine Forschungssammlung oder eine Aufnahmeschlange. Eine Datei verwendet eine Quelle und die gleichen Optionen für jede ID. Beginnen Sie mit dem Zwei-Video-Metadaten-Sample und ersetzen Sie dann Ihre eigene Datei.

### Dateien, die von diesem Workflow erstellt wurden

```text
video-ids.txt → Bulk Job → bulk-results.ndjson
  → audit/completed.ndjson Ergebnisse für Ihre Anwendung
  → audit/failed-video-ids.txt bestätigte Fehler bei der Überprüfung
  → audit/missing.ndjson-Eingänge, deren Ergebnisse fehlen
  → audit/summary.json Abdeckung und Ergebnis zählt
```

- [Behalten Sie den Anwendungsrekord IDs mit einer kleinen Liste](https://flashdata.dev/de/docs/guides/enrich-youtube-videos/reference.md)
- [Batch versus Bulk](https://flashdata.dev/de/docs/reference/batch-and-bulk/reference.md#choose)
- [Bulk API](https://flashdata.dev/de/docs/reference/bulk-processing/reference.md#playground)
- [YouTube-Videos in großen Mengen herunterladen](https://flashdata.dev/de/products/youtube-download#bulk-downloads)

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

## Bevor Sie anfangen

Installieren Sie CLI und verwenden Sie ein vorhandenes Profil oder FLASHDATA_API_KEY mit youtube_metadata-Berechtigung. Bestätigen Sie data.accessVerified: true und überprüfen Sie den verfügbaren Saldo, die Preise für zwei Anfragen und die aktuellen Limits. Verwenden Sie für Ihre eigene Datei die ID-Zählung, wenn Sie die Preise überprüfen. Jede verarbeitete ID ist eine separate Abfrage, nicht eine Flat Charge für die Datei.

Verwenden Sie Bash mit jq oder PowerShell 7 für die Schritte 1–3. Das optionale Import-Audit in Schritt 4 verwendet Python 3.10+ und seine Standardbibliothek. Der CLI selbst benötigt weder Node.js noch Python.

### Freier Zugang und Kontoprüfungen

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

- [Installieren Sie den CLI](https://flashdata.dev/de/docs/guides/flashdata-cli/reference.md#install)
- [Erstellen Sie einen API-Schlüssel](https://flashdata.dev/app/api-keys)
- [Zugriff auf den Agenten und Anspruch](https://flashdata.dev/de/docs/guides/agent-access/reference.md)
- [Verwenden Sie stattdessen HTTP](https://flashdata.dev/de/docs/reference/bulk-processing/reference.md#endpoints)

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

## 1. Bereiten Sie den IDs vor

Führen Sie einen neuen Arbeitsordner aus. Verwenden Sie UTF-8-Text mit einem 11-Zeichenvideo ID pro Zeile, nicht mit einem YouTube URL. Die maximale Dateigröße ist 2 GiB. Leerzeilen und Duplikate entfernen: Der CLI weist fehlerhafte Eingaben zurück, und wiederholte IDs werden separat verarbeitet.

### 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. Ausführen der Datei

Der CLI erstellt einen Job, lädt die Datei hoch, beginnt mit der Verarbeitung und speichert jeden Ergebnisteil in einer NDJSON-Datei. Verwenden Sie einen neuen Ausgabepfad. Der lokale Run ID bulk-first hält den Remote-Job-Beleg für die Wiederherstellung.

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


- [Überprüfen Sie den Fortschritt in einem anderen Terminal](https://flashdata.dev/de/docs/guides/bulk/reference.md#progress)
- [Erholung nach einem Timeout](https://flashdata.dev/de/docs/guides/bulk/reference.md#controls)

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

## 3. Prüfen Sie die Ergebnisse

Öffnen Sie bulk-results.ndjson. Jede Zeile ist ein JSON-Record mit Index, video_id und Status. Erfolgreiche Zeilen enthalten ein Ergebnis-Array; fehlgeschlagene Zeilen enthalten einen Fehler. Verbinden Sie Datensätze mit der Eingabe durch einen Null-basierten Index, nicht die Dateireihenfolge. Der Befehl Bash verwendet jq.

### Eine erfolgreiche Zeile · abgekürztes Beispiel

```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. Überprüfe die Abdeckung vor dem Import

Speichern Sie audit-bulk.py unten. Führen Sie es gegen die unveränderte Eingabedatei und alle abgerufenen Ergebnisteile aus. Es überprüft jeden Index, Video ID und Quelle, lehnt doppelte Ergebniszeilen ab und trennt bestätigte Fehler von fehlenden Ergebnissen. Für eine andere Quelle fügen Sie --source SOURCE_ID hinzu.

Erwarten Sie inputRows: 2, abgeschlossen: 2, fehlgeschlagen: 0, fehlt: 0 und allSucceeded: true für das erfolgreiche Beispiel. Nur abgeschlossene Zeilen gehören in den Ergebnisimport der Anwendung. Behalten Sie die Zusammenfassung des Audits und die erfolglosen Ergebnisse neben sich.


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

### Speichern Sie audit-bulk.py

Erstellen Sie audit-bulk.py neben video-ids.txt und bulk-results.ndjson im Arbeitsordner. Kopieren Sie den vollständigen Code unten und speichern Sie ihn.

Das Skript liest Dateien Zeile für Zeile und verwendet einen lokalen SQLite-Index, anstatt den gesamten Datensatz in den Speicher zu laden. Es erfordert eine validierte Eingabedatei des Videos IDs. Jedes Audit verwendet ein neues Ausgabeverzeichnis; Teildateien bleiben getrennt, bis das Parsing abgeschlossen ist.

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

### Durchführung des Import-Audits

Führen Sie aus dem Ordner aus, der das Skript, die ursprüngliche Eingabe und die heruntergeladenen Ergebnisse enthält. Das Audit liest nur lokale Dateien.

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

### Importieren Sie vervollständigte Zeilen und führen Sie das Audit

| Datei/Signal | Verwenden Sie es auf diese Weise |
| --- | --- |
| completed.ndjson | Verbinden Sie sich per Index zur Originaldatei. Verwenden Sie video_id für einen Katalogschlüssel; behalten Sie die job/snapshot-Identität beim Speichern des Aktualisierungsverlaufs bei. |
| failed.ndjson + failed-video-ids.txt | Überprüfen Sie Fehler, bevor Sie diese IDs absichtlich wiederholen. Erfolgreiche und fehlende Items werden aus der failed-ID Liste ausgeschlossen. |
| missing.ndjson | Wiederherstellen Sie alle Ergebnisteile aus dem vorhandenen Job und prüfen Sie dann die wiederhergestellte Datei in einem neuen Verzeichnis. Fehlende Ausgabe ist keine bestätigte fehlgeschlagene Abfrage. |
| summary.json | coverageComplete überprüft, ob jede Eingabe ein Ergebnis hat. allSucceeded erfordert auch keine fehlgeschlagenen Videos. Das Audit beendet 2 für Fehler oder fehlende Zeilen. |
| Ausfahrt 1 / keine summary.json | Falsche oder nicht übereinstimmende Daten: Überprüfen Sie die gespeicherten Dateien. Veröffentlichen Sie das Teilaudit nicht als vollständigen Datensatz. |

- [Bestehende Ergebnisse wiederherstellen](https://flashdata.dev/de/docs/guides/bulk/reference.md#controls)
- [Ergebnisrückhaltung](https://flashdata.dev/de/docs/guides/save-results/reference.md#bulk)

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

## Wenn einige Videos fehlschlagen

Ein abgeschlossener Bulk-Job kann fehlgeschlagene Videos enthalten. Der CLI speichert auch diese Zeilen und verlässt dann mit bulk_item_failures. Überprüfen Sie ihre Fehler, bevor Sie entscheiden, ob Sie einzelne IDs erneut versuchen möchten; Übermitteln Sie nicht die gesamte Datei automatisch.

### Zeigen Sie nur erfolglose Aufzeichnungen · jq

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


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

## Gleisfortschritt und -kapazität

Lesen Sie den gespeicherten Job, während der ursprüngliche Befehl ausgeführt wird. Der CLI wickelt den Status unter Daten ein; der direkte HTTP wickelt ihn unter Job ein. Überprüfen Sie mit einer Verzögerung und Backoff, und ehren Retry-After auf 429. Ein lokales Timeout oder ein geschlossenes Terminal storniert keine Remote-Arbeit.

| Feld | Lesen Sie es als |
| --- | --- |
| input.scannedBytes / input.bytes | Fortschritt des Dateiscans, nicht abgeschlossene Abfragen oder hochgeladene Medien. |
| input.complete | Alle Eingaben wurden gelesen; Abfragen und Ergebnisverpackungen können noch ausgeführt werden. |
| counts.accepted / completed / failed | Eingereicht IDs, erfolgreiche Videos und fehlgeschlagene Videos. Herausragend = akzeptiert - abgeschlossen - fehlgeschlagen. |
| counts.invalid / results | Ungültige Eingangsleitungen / Datensätze bisher verpackt. HTTP kann Dateien mit ungültigen Zeilen akzeptieren; der CLI validiert die Eingabe vor dem Hochladen. |
| delivery | Kundendatenlieferung: uploadedParts, retryCount, storageType und customerStorage. Getrennt vom Upload jedes Videos. |

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

### Wissen, wann zu warten oder zu handeln

Bulk übermittelt schrittweise innerhalb der maxPendingJobs-Kapazität Ihres Kontos, die mit anderen Jobs geteilt wird. Unzureichende Credits oder ein inaktives Abonnement können den Job unterbrechen. Überprüfen Sie pauseReason vor der Wiederaufnahme.

| Staat | Nächste Maßnahme |
| --- | --- |
| awaiting_upload | Laden Sie die Datei hoch und starten Sie dann den vorhandenen Job. |
| running / finalizing | Warten Sie. Das Finalisieren kann unvollendete Abfragen, Verpackung und Lagerlieferung umfassen. |
| paused | Lösen Sie pauseReason und nehmen Sie den gleichen Job wieder auf. |
| completed | Laden Sie alle Ergebnisteile herunter und prüfen Sie fehlgeschlagene Zeilen. |
| failed / cancelled | Überprüfen Sie job.error und die gespeicherte Quittung. Akzeptierte Arbeit kann immer noch finish; kein abgeschlossenes Manifest wird veröffentlicht. |


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

## Setzen Sie einen unterbrochenen Workflow fort

Nach einem lokalen Timeout oder einem unterbrochenen Ergebnis-Download stellen Sie Bulk-First wieder her. Dieser liest den vorhandenen Remote-Job; er übermittelt den Datensatz nicht erneut. Verwenden Sie einen neuen Ausgabedateinamen. Ein partial_result-Fehler kann eine teilweise lokale Datei hinterlassen; halten Sie sie vom wiederhergestellten Ergebnis getrennt.

Verwenden Sie das gleiche CLI-Profil und das gleiche Zustandsverzeichnis. Fügen Sie für ein benanntes Profil --profile NAME zu jedem Befehl hinzu.

| Lage | Fixpunkt |
| --- | --- |
| awaiting_upload | runs recover wiederholt keinen Upload oder Start. Überprüfen Sie die gespeicherte ID, laden Sie den Status und die Originaldatei hoch, bevor Sie explizit fortfahren. |
| paused | Beheben Sie die gemeldete Ursache und verwenden Sie dann einen Massenlebenslauf mit dem gespeicherten ID. Die Wiederherstellung setzt die angehaltene Arbeit nicht automatisch fort. |
| 401 / 403 | Wiederherstellen des gültigen Zugriffs auf das einreichende Konto und die Quelle. Verwenden Sie den gleichen Job nach der Authentifizierung behoben ist. |
| 409 / 410 | 409: Ergebnisse sind nicht fertig. 410: Die gespeicherten Ergebnisse sind abgelaufen; verwenden Sie Ihre gespeicherte Kopie. |
| Abgelaufener Upload URL | Bestätigen Sie, dass der alte Job nie begonnen hat, bevor Sie einen neuen erstellt haben. Eine unsichere Einreichung ist ein Grund, zuerst das gespeicherte ID zu lesen. |

### Wiederherstellen des gespeicherten Laufs

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

- [CLI Wiederherstellung und wiederkehrende Runs](https://flashdata.dev/de/docs/guides/cli-automation/reference.md#recover)
- [Zinsbindungen](https://flashdata.dev/de/docs/guides/usage-and-limits/reference.md)

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

### Unterbrechen oder Wiederaufnahme eines Jobs

Ersetzen Sie BULK_ID durch das ID aus runs show bulk-first. Pause stoppt neue Einsendungen und Ergebnisverpackungen; akzeptierte Abfragen werden fortgesetzt. Lösen Sie pauseReason vor der Wiederaufnahme. Aktualisieren Sie für geänderte Optionen oder Speicheranmeldeinformationen den bestehenden Job über Bulk API.

#### Pause

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

#### Resümee nach Behebung der Ursache

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

- [Aktualisieren Sie einen Bulk-Job](https://flashdata.dev/de/docs/reference/bulk-processing/reference.md#updateBulkJob)

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

### Dauerhaft abbrechen

Stornieren Sie nur, wenn Sie beabsichtigen, den Job aufzugeben. Die Stornierung stellt keine akzeptierten Anfragen zurück oder erstattet abgeschlossene Arbeiten. Zählungen können sich noch ändern, und kein abgeschlossenes Manifest wird veröffentlicht. Pause ist reversibel.

#### Stornieren Sie den gewählten Job

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


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

## Jedes Ergebnisteil abrufen

Für einen bestehenden abgeschlossenen Job folgt der CLI seinem Manifest und speichert jeden Ergebnisteil in einer NDJSON-Datei. Verwenden Sie einen neuen Ausgabepfad und führen Sie das Import-Audit für die kombinierte Datei aus. Download-Ergebnisse beschreiben gelieferte Medien; sie sind keine MP4- oder Audiobytes.

### Holen Sie alle Teile aus einem bestehenden Job

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

- [Abdeckung des Datensatzes überprüfen](https://flashdata.dev/de/docs/guides/bulk/reference.md#audit)
- [Manifest, Teile und Aufbewahrungsangaben](https://flashdata.dev/de/docs/reference/bulk-processing/reference.md#downloadBulkJobManifest)

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

## Liefern Sie zu Ihrem Lager

Speichern Sie Ihre Provider-Anmeldeinformationen als storage.json im Arbeitsordner, bevor Sie diesen Befehl ausführen. Verwenden Sie die unten verlinkten Providerfelder; halten Sie die Datei privat. Die --storage-config des CLI liest diese JSON-Datei und wählt result_storage für Daten oder Speicher für Medien aus. --options nimmt auch einen Dateipfad, nicht inline JSON.

- [Anmeldefelder des Anbieters](https://flashdata.dev/de/docs/sources/youtube_download/reference.md#storage)
- [Speicherbereitstellung und Objektpfade](https://flashdata.dev/de/docs/reference/bulk-processing/reference.md#storage)
- [Konfigurieren Sie die Bulk API-Anforderung](https://flashdata.dev/de/docs/reference/bulk-processing/reference.md#playground)

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

### Ausführen mit der gespeicherten Speicherkonfiguration

#### Speicher zum Metadaten-Workflow hinzufügen

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

