# Trattamento file Bulk

Elaborare un file di video IDs, recuperare ogni parte del risultato e controllare la copertura prima di importare il set di dati nella vostra applicazione.

Riferimento canonico: https://flashdata.dev/it/docs/guides/bulk
Recensito: 2026-11-05 da FlashData

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

## Da un file ID a un set di dati controllato

Utilizzare questo flusso di lavoro per un catalogo video, una raccolta di ricerca o una coda di ingestione. Un file utilizza una fonte e le stesse opzioni per ogni ID. Iniziare con il campione di metadati a due video, quindi sostituire il proprio file.

### File prodotti da questo flusso di lavoro

```text
video-ids.txt → Lavoro Bulk → bulk-results.ndjson
  → audit/completed.ndjson risultati per la vostra applicazione
  → audit/failed-video-ids.txt ha confermato i guasti alla recensione
  → Ingressi audit/missing.ndjson i cui risultati sono mancanti
  → Copertura audit/summary.json e conteggi dei risultati
```

- [Mantenere il record di applicazione IDs con una piccola lista](https://flashdata.dev/it/docs/guides/enrich-youtube-videos/reference.md)
- [Batch rispetto a Bulk](https://flashdata.dev/it/docs/reference/batch-and-bulk/reference.md#choose)
- [Bulk API parco giochi](https://flashdata.dev/it/docs/reference/bulk-processing/reference.md#playground)
- [Download in massa di video YouTube](https://flashdata.dev/it/products/youtube-download#bulk-downloads)

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

## Prima di iniziare

Installare lo CLI e utilizzare un profilo esistente o FLASHDATA_API_KEY con il permesso youtube_metadata. Confermare data.accessVerified: true e rivedere l'equilibrio disponibile, i prezzi per due richieste e i limiti attuali. Per il proprio file, utilizzare il suo conteggio ID quando si controllano i prezzi. Ogni ID processato è una query separata, non una carica piatta per il file.

Utilizzare Bash con jq o PowerShell 7 per i passaggi 1–3. L'audit di importazione opzionale nella fase 4 utilizza Python 3.10+ e la sua libreria standard. Lo CLI stesso non richiede né Node.js né Python.

### Accesso gratuito e assegni account

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

- [Installare la CLI](https://flashdata.dev/it/docs/guides/flashdata-cli/reference.md#install)
- [Creare una chiave API](https://flashdata.dev/app/api-keys)
- [Accesso e rivendicazione dell'agente](https://flashdata.dev/it/docs/guides/agent-access/reference.md)
- [Utilizzare HTTP invece](https://flashdata.dev/it/docs/reference/bulk-processing/reference.md#endpoints)

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

## 1. Preparare la IDs

Eseguire in una nuova cartella di lavoro. Utilizzare il testo UTF-8 con un video 11-character ID per linea, non un YouTube URL. La dimensione massima del file è 2 GiB. Rimuovere le linee vuote e i duplicati: lo CLI rifiuta l'ingresso malformato e i ripetuti IDs vengono elaborati separatamente.

### 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. Eseguire il file

Lo CLI crea un lavoro, carica il file, inizia l'elaborazione e salva ogni parte del risultato in un file NDJSON. Utilizzare un nuovo percorso di uscita. Il locale run ID in primo luogo mantiene la ricevuta di lavoro remota per il recupero.

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


- [Controllare i progressi in un altro terminale](https://flashdata.dev/it/docs/guides/bulk/reference.md#progress)
- [Recuperare dopo un timeout](https://flashdata.dev/it/docs/guides/bulk/reference.md#controls)

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

## 3. Ispezione dei risultati

Aprire bulk-results.ndjson. Ogni linea è un record JSON con indice, video_id e stato. Le righe di successo contengono un array di risultati; le righe fallite contengono un errore. Unisci i record all'ingresso per indice zero-based, non l'ordine di file. Il comando Bash utilizza jq.

### Una riga di successo · esempio abbreviato

```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. Controllare la copertura prima di importare

Salva audit-bulk.py qui sotto. Eseguire contro il file di input invariato e tutte le parti di risultato recuperate. Controlla ogni indice, video ID e sorgente, rifiuta le righe dei risultati duplicati e separa i guasti confermati dai risultati mancanti. Per un'altra fonte, aggiungere --source SOURCE_ID.

inputRows: 2, completato: 2, fallito: 0, mancante: 0 e allSucceeded: true per il campione di successo. Solo le righe completate appartengono all'importazione dei risultati dell'applicazione. Tenere il riepilogo dell'audit e i risultati senza successo accanto a loro.


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

### Salvare audit-bulk.py

Creare audit-bulk.py accanto a video-ids.txt e bulk-results.ndjson nella cartella di lavoro. Copia il codice completo qui sotto e salvalo.

Lo script legge i file linea per riga e utilizza un indice SQLite locale invece di caricare l'intero set di dati in memoria. Richiede un file di input convalidato del video IDs. Ogni audit utilizza una nuova directory di output; i file parziali rimangono separati fino a quando la parsing non finisce.

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

### Eseguire l'audit di importazione

Eseguire dalla cartella contenente lo script, l'ingresso originale e i risultati scaricati. L'audit legge solo i file locali.

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

### Importare righe completate e mantenere l'audit

| File / segnale | Usalo in questo modo |
| --- | --- |
| completed.ndjson | Iscriviti per indice al file originale. Utilizzare video_id per una chiave di catalogo; conservare l'identità job/snapshot quando si memorizza la cronologia di aggiornamento. |
| failed.ndjson + failed-video-ids.txt | Rivedere gli errori prima di riprovare deliberatamente questi IDs. Gli elementi di successo e mancanti sono esclusi dall'elenco fallito-ID. |
| missing.ndjson | Recuperare tutte le parti del risultato dal lavoro esistente, quindi controllare il file recuperato in una nuova directory. L'uscita mancante non è una domanda fallita confermata. |
| summary.json | coverageComplete verifica che ogni input ha un risultato. allSucceeded non richiede anche video falliti. L'audit esce da 2 per guasti o righe mancanti. |
| Uscita 1 / no summary.json | Dati malformati o errati: ispezionare i file salvati. Non pubblicare l'audit parziale come set di dati completo. |

- [Recuperare i risultati esistenti](https://flashdata.dev/it/docs/guides/bulk/reference.md#controls)
- [Ritenzione dei risultati](https://flashdata.dev/it/docs/guides/save-results/reference.md#bulk)

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

## Se alcuni video falliscono

Un lavoro Bulk completato può contenere video falliti. Lo CLI salva anche quelle righe, poi esce con bulk_item_failures. Ispezionare i loro errori prima di decidere se ripristinare il singolo IDs; non risottomettere l'intero file automaticamente.

### Mostra solo record non riusciti · jq

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


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

## Traccia il progresso e la capacità

Leggi il lavoro salvato mentre il comando originale viene eseguito. Lo stato CLI avvolge i dati; HTTP lo avvolge direttamente sotto lavoro. Controllare con un ritardo e un backoff, e onorare Retry-After su 429. Un timeout locale o un terminale chiuso non cancella il lavoro remoto.

| Campo di applicazione | Leggilo come |
| --- | --- |
| input.scannedBytes / input.bytes | avanzamento della scansione dei file, non domande completate o supporti caricati. |
| input.complete | Tutti gli input sono stati letti; le query e l'imballaggio dei risultati possono ancora essere in esecuzione. |
| counts.accepted / completed / failed | Presentato IDs, video di successo e video falliti. Eccezionale = accettato − completato − fallito. |
| counts.invalid / results | Linee di ingresso non valide / record imballati finora. HTTP può accettare file contenenti linee non valide; CLI convalida l'ingresso prima del caricamento. |
| delivery | Consegna dei dati del cliente: uploadedParts, retryCount, storageType e customerStorage. Separato dal caricamento dei media di ogni video. |

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

### Sapere quando aspettare o agire

Bulk si presenta gradualmente all'interno della capacità maxPendingJobs del tuo account, condivisa con altri lavori. I crediti insufficienti o un abbonamento inattivo possono mettere in pausa il lavoro. Controllare pauseReason prima di riprendere.

| Stato | Prossima azione |
| --- | --- |
| awaiting_upload | Caricare il file, quindi avviare il lavoro esistente. |
| running / finalizing | Aspetta. Finalizzazione può includere domande incompiute, imballaggio e consegna di stoccaggio. |
| paused | Risolvere pauseReason e riprendere lo stesso lavoro. |
| completed | Scarica tutte le parti dei risultati e ispeziona le righe fallite. |
| failed / cancelled | Ispezionare job.error e la ricevuta salvata. Il lavoro accettato può ancora finish; non viene pubblicato nessun manifesto completato. |


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

## Riprendi un flusso di lavoro interrotto

Dopo un timeout locale o interrotto il download dei risultati, recuperare bulk-first. Questo legge il lavoro remoto esistente; non invia nuovamente il dataset. Utilizzare un nuovo nome file di output. Un errore partial_result può lasciare un file locale parziale; tenerlo separato dal risultato recuperato.

Utilizzare lo stesso profilo CLI e directory di stato in tutto. Per un profilo di nome, aggiungere --profile NAME ad ogni comando.

| Situazione | Risolto |
| --- | --- |
| awaiting_upload | runs recover non riproduce un upload o un inizio. Controllare lo stato di upload e il file originale salvato ID, prima di continuare esplicitamente. |
| paused | Risolvere la causa segnalata, quindi utilizzare il curriculum di massa con il ID salvato. Il recupero non riprende automaticamente il lavoro in pausa. |
| 401 / 403 | Ripristina l'accesso valido all'account e alla fonte di presentazione. Riutilizzare lo stesso lavoro dopo la correzione dell'autenticazione. |
| 409 / 410 | 409: i risultati non sono pronti. 410: i risultati memorizzati sono scaduti; utilizzare la copia salvata. |
| Caricamento scaduto URL | Conferma che il vecchio lavoro non è mai iniziato prima di crearne uno nuovo. Una presentazione incerta è un motivo per leggere il suo salvato ID prima. |

### Recuperare l'esecuzione salvata

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

- [CLI di recupero e ripetizione](https://flashdata.dev/it/docs/guides/cli-automation/reference.md#recover)
- [Limiti di tasso](https://flashdata.dev/it/docs/guides/usage-and-limits/reference.md)

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

### Pausa o riprendere un lavoro

Sostituire BULK_ID con ID dal primo blocco runs show. Pause ferma nuove presentazioni e il packaging dei risultati; le domande accettate continuano. Risolvere pauseReason prima di riprendere. Per le opzioni modificate o le credenziali di archiviazione, aggiornare il lavoro esistente tramite Bulk API.

#### Pausa

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

#### Riprendi dopo aver risolto la causa

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

- [Aggiornare un lavoro Bulk](https://flashdata.dev/it/docs/reference/bulk-processing/reference.md#updateBulkJob)

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

### Annullare definitivamente

Cancella solo quando hai intenzione di abbandonare il lavoro. La cancellazione non annulla le domande accettate o rimborsa il lavoro completato. I conti possono ancora cambiare, e nessun manifesto completato è pubblicato. La pausa e' reversibile.

#### Annullare il lavoro scelto

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


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

## Recuperare ogni parte del risultato

Per un lavoro completato esistente, lo CLI segue il suo manifesto e salva ogni parte del risultato in un file NDJSON. Utilizzare un nuovo percorso di output ed eseguire l'audit di importazione sul file combinato. I risultati del download descrivono i supporti consegnati; non sono MP4 o byte audio.

### Prelevare tutte le parti da un lavoro esistente

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

- [Verificare la copertura dei dataset](https://flashdata.dev/it/docs/guides/bulk/reference.md#audit)
- [Manifest, parti e riferimenti di ritenzione](https://flashdata.dev/it/docs/reference/bulk-processing/reference.md#downloadBulkJobManifest)

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

## Consegna al tuo storage

Salvare le credenziali del provider come storage.json nella cartella di lavoro prima di eseguire questo comando. Utilizzare i campi del fornitore collegati di seguito; mantenere il file privato. Lo CLI --storage-config legge questo file JSON e seleziona result_storage per i dati o lo storage per i media. --options prende anche un percorso di file, non inline JSON.

- [Fornitore campi credenziali](https://flashdata.dev/it/docs/sources/youtube_download/reference.md#storage)
- [Consegna di stoccaggio e percorsi oggetti](https://flashdata.dev/it/docs/reference/bulk-processing/reference.md#storage)
- [Configurare la richiesta Bulk API](https://flashdata.dev/it/docs/reference/bulk-processing/reference.md#playground)

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

### Eseguire con la configurazione di archiviazione salvata

#### Aggiungere lo storage al flusso di lavoro dei metadati

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

