# Traitement de fichiers Bulk

Traitez un fichier d’identifiants vidéo, récupérez toutes les parties des résultats et vérifiez leur exhaustivité avant d’importer le jeu de données dans votre application.

Référence canonique : https://flashdata.dev/fr/docs/guides/bulk
Vérifié le 2026-11-05 par FlashData

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

## Passer d’un fichier d’identifiants à un jeu de données vérifié

Utilisez ce workflow pour un catalogue vidéo, une collection de recherche ou une file d’ingestion. Chaque fichier utilise une seule source et les mêmes options pour tous les identifiants. Commencez par l’exemple de métadonnées de deux vidéos, puis utilisez votre propre fichier.

### Fichiers produits par ce workflow

```text
video-ids.txt → tâche Bulk → bulk-results.ndjson
  → audit/completed.ndjson       résultats pour votre application
  → audit/failed-video-ids.txt   échecs confirmés à examiner
  → audit/missing.ndjson        entrées dont le résultat manque
  → audit/summary.json          exhaustivité et décompte des résultats
```

- [Conserver les identifiants de vos enregistrements pour une petite liste](https://flashdata.dev/fr/docs/guides/enrich-youtube-videos/reference.md)
- [Choisir entre Batch et Bulk](https://flashdata.dev/fr/docs/reference/batch-and-bulk/reference.md#choose)
- [Playground de l’API Bulk](https://flashdata.dev/fr/docs/reference/bulk-processing/reference.md#playground)
- [Téléchargements YouTube en masse](https://flashdata.dev/fr/products/youtube-download#bulk-downloads)

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

## Avant de commencer

Installez la CLI et utilisez un profil existant ou FLASHDATA_API_KEY avec la permission youtube_metadata. Confirmez data.accessVerified: true et vérifiez le solde disponible, le tarif pour deux requêtes et les limites actuelles. Pour votre propre fichier, utilisez son nombre d’identifiants pour vérifier le prix. Chaque identifiant traité constitue une requête distincte ; le fichier n’est pas facturé au forfait.

Utilisez Bash avec jq ou PowerShell 7 pour les étapes 1 à 3. L’audit d’importation facultatif de l’étape 4 utilise Python 3.10+ et sa bibliothèque standard. La CLI elle-même ne nécessite ni Node.js ni Python.

### Vérifications gratuites de l’accès et du compte

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

- [Installer la CLI](https://flashdata.dev/fr/docs/guides/flashdata-cli/reference.md#install)
- [Créer une clé API](https://flashdata.dev/app/api-keys)
- [Accès des agents et rattachement](https://flashdata.dev/fr/docs/guides/agent-access/reference.md)
- [Utiliser HTTP](https://flashdata.dev/fr/docs/reference/bulk-processing/reference.md#endpoints)

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

## 1. Préparer les identifiants

Travaillez dans un nouveau dossier. Utilisez un fichier texte UTF-8 avec un identifiant vidéo de 11 caractères par ligne, et non une URL YouTube. La taille maximale est de 2 GiB. Supprimez les lignes vides et les doublons : la CLI rejette les entrées mal formées, et les identifiants répétés sont traités séparément.

### 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. Traiter le fichier

La CLI crée une tâche, transfère le fichier, démarre le traitement et regroupe toutes les parties des résultats dans un fichier NDJSON. Utilisez un nouveau chemin de sortie. L’identifiant d’exécution local bulk-first conserve le reçu de la tâche distante pour permettre sa reprise.

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


- [Vérifier la progression dans un autre terminal](https://flashdata.dev/fr/docs/guides/bulk/reference.md#progress)
- [Reprendre après un délai d’attente dépassé](https://flashdata.dev/fr/docs/guides/bulk/reference.md#controls)

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

## 3. Examiner les résultats

Ouvrez bulk-results.ndjson. Chaque ligne est un enregistrement JSON avec index, video_id et status. Les lignes réussies contiennent un tableau results ; les lignes en échec contiennent une erreur. Rapprochez les résultats de l’entrée à l’aide de index, qui commence à zéro, et non selon leur ordre dans le fichier. La commande Bash utilise jq.

### Une ligne réussie · exemple abrégé

```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. Vérifier l’exhaustivité avant l’importation

Enregistrez audit-bulk.py ci-dessous. Exécutez-le avec le fichier d’entrée inchangé et toutes les parties de résultats récupérées. Il vérifie chaque index, identifiant vidéo et source, rejette les lignes de résultat en double et distingue les échecs confirmés des résultats manquants. Pour une autre source, ajoutez --source SOURCE_ID.

L’exemple réussi doit indiquer inputRows: 2, completed: 2, failed: 0, missing: 0 et allSucceeded: true. Importez uniquement les lignes terminées dans les résultats de l’application. Conservez aussi le résumé d’audit et les éléments en échec ou sans résultat.


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

### Enregistrer audit-bulk.py

Créez audit-bulk.py à côté de video-ids.txt et bulk-results.ndjson dans le dossier de travail. Copiez-y le code complet ci-dessous et enregistrez-le.

Le script lit les fichiers ligne par ligne et utilise un index SQLite local plutôt que de charger tout le jeu de données en mémoire. Il nécessite un fichier d’identifiants vidéo préalablement validé. Chaque audit utilise un nouveau répertoire de sortie ; les fichiers partiels restent séparés jusqu’à la fin de l’analyse.

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

### Lancer l’audit d’importation

Exécutez la commande depuis le dossier contenant le script, le fichier d’entrée d’origine et les résultats téléchargés. L’audit lit uniquement des fichiers locaux.

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

### Importer les lignes terminées et conserver l’audit

| Fichier / indicateur | Utilisation |
| --- | --- |
| completed.ndjson | Rapprochez les lignes du fichier d’origine selon index. Utilisez video_id comme clé de catalogue ; conservez l’identité de la tâche ou de l’instantané pour historiser les mises à jour. |
| failed.ndjson + failed-video-ids.txt | Examinez les erreurs avant de relancer volontairement ces identifiants. Les éléments réussis et manquants sont exclus de la liste des identifiants en échec. |
| missing.ndjson | Récupérez toutes les parties de résultats de la tâche existante, puis auditez le fichier récupéré dans un nouveau répertoire. Un résultat manquant n’est pas un échec de requête confirmé. |
| summary.json | coverageComplete vérifie que chaque entrée possède un résultat. allSucceeded exige en plus qu’aucune vidéo n’ait échoué. L’audit renvoie le code de sortie 2 en présence d’échecs ou de lignes manquantes. |
| Code de sortie 1 / aucun summary.json | Données mal formées ou incohérentes : examinez les fichiers enregistrés. Ne publiez pas l’audit partiel comme un jeu de données complet. |

- [Récupérer les résultats existants](https://flashdata.dev/fr/docs/guides/bulk/reference.md#controls)
- [Conservation des résultats](https://flashdata.dev/fr/docs/guides/save-results/reference.md#bulk)

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

## Si certaines vidéos échouent

Une tâche Bulk terminée peut contenir des vidéos en échec. La CLI enregistre aussi ces lignes, puis se termine avec bulk_item_failures. Examinez les erreurs avant de décider de relancer certains identifiants ; ne soumettez pas automatiquement tout le fichier à nouveau.

### Afficher uniquement les enregistrements non réussis · jq

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


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

## Suivre la progression et la capacité

Consultez la tâche enregistrée pendant l’exécution de la commande d’origine. La CLI place l’état sous data ; la réponse HTTP directe le place sous job. Espacez les vérifications avec un délai croissant et respectez Retry-After en cas de 429. Un délai d’attente local dépassé ou un terminal fermé n’annule pas les opérations distantes.

| Champ | Signification |
| --- | --- |
| input.scannedBytes / input.bytes | Progression de la lecture du fichier, et non des requêtes terminées ou des médias transférés. |
| input.complete | Toute l’entrée a été lue ; les requêtes et la préparation des fichiers de résultats peuvent encore être en cours. |
| counts.accepted / completed / failed | Identifiants soumis, vidéos réussies et vidéos en échec. En cours = accepted − completed − failed. |
| counts.invalid / results | Lignes d’entrée invalides / enregistrements déjà inclus dans les fichiers de résultats. HTTP peut accepter des fichiers contenant des lignes invalides ; la CLI valide l’entrée avant son transfert. |
| delivery | Livraison des données au client : uploadedParts, retryCount, storageType et customerStorage. Elle est distincte du transfert du média de chaque vidéo. |

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

### Savoir quand attendre ou intervenir

Bulk soumet progressivement les requêtes dans la limite maxPendingJobs du compte, partagée avec les autres tâches. Des crédits insuffisants ou un abonnement inactif peuvent mettre la tâche en pause. Consultez pauseReason avant de la reprendre.

| État | Action suivante |
| --- | --- |
| awaiting_upload | Transférez le fichier, puis démarrez la tâche existante. |
| running / finalizing | Patientez. La finalisation peut inclure des requêtes inachevées, la préparation des fichiers de résultats et leur livraison au stockage. |
| paused | Corrigez la cause indiquée par pauseReason et reprenez la même tâche. |
| completed | Téléchargez toutes les parties de résultats et examinez les lignes en échec. |
| failed / cancelled | Examinez job.error et le reçu enregistré. Les opérations acceptées peuvent encore se terminer ; aucun manifeste final n’est publié. |


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

## Reprendre un workflow interrompu

Après un délai d’attente local dépassé ou une interruption du téléchargement des résultats, reprenez bulk-first. Cette opération lit la tâche distante existante sans soumettre à nouveau le jeu de données. Utilisez un nouveau nom de fichier de sortie. Une erreur partial_result peut laisser un fichier local partiel ; gardez-le séparé du résultat récupéré.

Conservez le même profil CLI et le même répertoire d’état à toutes les étapes. Pour un profil nommé, ajoutez --profile NAME à chaque commande.

| Situation | Correction |
| --- | --- |
| awaiting_upload | runs recover ne répète ni le transfert du fichier ni le démarrage. Vérifiez l’identifiant enregistré, l’état du transfert et le fichier d’origine avant de continuer explicitement. |
| paused | Corrigez la cause signalée, puis utilisez bulk resume avec l’identifiant enregistré. La récupération ne reprend pas automatiquement une tâche en pause. |
| 401 / 403 | Rétablissez un accès valide au compte et à la source utilisés pour la soumission. Réutilisez la même tâche après avoir corrigé l’authentification. |
| 409 / 410 | 409 : les résultats ne sont pas prêts. 410 : les résultats conservés ont expiré ; utilisez votre copie enregistrée. |
| L’URL de transfert a expiré | Confirmez que l’ancienne tâche n’a jamais démarré avant d’en créer une nouvelle. Si la soumission est incertaine, consultez d’abord son identifiant enregistré. |

### Reprendre l’exécution enregistrée

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

- [Reprise avec la CLI et exécutions récurrentes](https://flashdata.dev/fr/docs/guides/cli-automation/reference.md#recover)
- [Limites de débit](https://flashdata.dev/fr/docs/guides/usage-and-limits/reference.md)

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

### Mettre une tâche en pause ou la reprendre

Remplacez BULK_ID par l’identifiant renvoyé par runs show bulk-first. La pause arrête les nouvelles soumissions et la préparation des fichiers de résultats ; les requêtes acceptées continuent. Corrigez pauseReason avant de reprendre. Pour modifier les options ou les identifiants de stockage, mettez à jour la tâche existante via l’API Bulk.

#### Mettre en pause

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

#### Reprendre après correction

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

- [Mettre à jour une tâche Bulk](https://flashdata.dev/fr/docs/reference/bulk-processing/reference.md#updateBulkJob)

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

### Annuler définitivement

Annulez uniquement si vous souhaitez abandonner la tâche. L’annulation ne revient pas sur les requêtes acceptées et ne rembourse pas les opérations terminées. Les compteurs peuvent encore évoluer et aucun manifeste final n’est publié. La pause est réversible.

#### Annuler la tâche choisie

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


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

## Récupérer toutes les parties des résultats

Pour une tâche existante terminée, la CLI suit le manifeste et regroupe toutes les parties des résultats dans un fichier NDJSON. Utilisez un nouveau chemin de sortie et lancez l’audit d’importation sur le fichier regroupé. Les résultats de téléchargement décrivent les médias livrés ; ils ne contiennent pas les octets MP4 ou audio.

### Récupérer toutes les parties d’une tâche existante

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

- [Vérifier l’exhaustivité du jeu de données](https://flashdata.dev/fr/docs/guides/bulk/reference.md#audit)
- [Référence : manifeste, parties et conservation](https://flashdata.dev/fr/docs/reference/bulk-processing/reference.md#downloadBulkJobManifest)

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

## Livrer vers votre stockage

Enregistrez les identifiants de votre fournisseur dans storage.json, dans le dossier de travail, avant d’exécuter cette commande. Utilisez les champs décrits dans le lien ci-dessous et gardez le fichier privé. L’option CLI --storage-config lit ce fichier JSON et sélectionne result_storage pour les données ou storage pour les médias. --options attend aussi un chemin de fichier, et non du JSON en ligne.

- [Champs d’identification du fournisseur](https://flashdata.dev/fr/docs/sources/youtube_download/reference.md#storage)
- [Livraison au stockage et chemins des objets](https://flashdata.dev/fr/docs/reference/bulk-processing/reference.md#storage)
- [Configurer la requête API Bulk](https://flashdata.dev/fr/docs/reference/bulk-processing/reference.md#playground)

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

### Exécuter avec la configuration de stockage enregistrée

#### Ajouter le stockage au workflow de métadonnées

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

