# Enrichir un fichier d’identifiants vidéo

Transformez un fichier d’identifiants YouTube en métadonnées JSON et CSV, avec un résultat par vidéo. Utilisez Python ou Bash avec la CLI FlashData.

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

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

## Avant de commencer

Installez la CLI FlashData v1.2.1 dans PATH, ainsi que Python 3.10+ (bibliothèque standard uniquement), ou Bash avec jq et OpenSSL. Les deux versions utilisent la CLI pour l’envoi du fichier, la reprise de la tâche et la récupération des parties de résultats. Sous Windows, utilisez Git Bash pour la version Bash.

Vous devez disposer d’une clé API de propriétaire autorisant youtube_metadata et de crédits disponibles. Réutilisez votre connexion propriétaire enregistrée, ou exécutez auth login une fois et saisissez la clé à l’invite masquée. Les agents peuvent fournir FLASHDATA_API_KEY depuis leur gestionnaire de secrets.

Ces exemples utilisent le profil et le dossier d’état par défaut de la CLI. Conservez le même compte et cet état enregistré pour la reprise. Si auth status indique un accès temporary, rattachez-le à votre compte avant de lancer Bulk.

### Uniquement sans connexion propriétaire enregistrée

```bash
flashdata auth login
```

### Vérifier l’accès et le coût de cet exemple à deux vidéos

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

- [Installer la CLI](https://flashdata.dev/fr/docs/guides/flashdata-cli/reference.md#install)
- [Obtenir une clé API](https://flashdata.dev/app/api-keys)
- [Essai agent et rattachement au compte](https://flashdata.dev/fr/docs/guides/agent-onboarding/reference.md)

<a id="input"></a>

## 1. Préparer les identifiants vidéo

Créez un dossier bulk-enrichment et enregistrez-y video-ids.txt. Ouvrez un terminal dans ce dossier. Placez un identifiant à 11 caractères par ligne, sans en-tête, ligne vide ni URL YouTube complète.

Choisissez un script de préparation et enregistrez-le à côté de video-ids.txt. Il refuse les identifiants invalides et les doublons, puis conserve une copie normalisée de l’entrée, les options de métadonnées et l’identifiant d’exécution sous prepared/. L’ordre d’entrée est préservé.

### bulk-enrichment/video-ids.txt

```text
jNQXAC9IVRw
dQw4w9WgXcQ
```

### Python

#### bulk-enrichment/prepare.py

```python
# Save as bulk-enrichment/prepare.py. Python 3.10+, standard library only.
import hashlib
import json
import os
import re
import sys
from pathlib import Path
from subprocess import run, CalledProcessError, DEVNULL

ROOT = Path(__file__).resolve().parent
try:
    os.umask(0o077)
    run_id = sys.argv[1]
    if not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9_.:@+-]{0,159}", run_id):
        raise ValueError("Choose a valid, stable run ID.")
    ids = (ROOT / "video-ids.txt").read_text(encoding="utf-8-sig").splitlines()
    ids = [line.strip() for line in ids]
    if not ids or any(not re.fullmatch(r"[A-Za-z0-9_-]{11}", value) for value in ids):
        raise ValueError("Use one 11-character video ID per line, with no blank rows or URLs.")
    if len(set(ids)) != len(ids):
        raise ValueError("Remove duplicate IDs before submitting; they would be processed separately.")
    data = ("\n".join(ids) + "\n").encode("utf-8")
    prepared = ROOT / "prepared"
    prepared.mkdir(mode=0o700)  # Refuse to overwrite an existing input snapshot.
    (prepared / "video-ids.txt").write_bytes(data)
    (prepared / "options.json").write_text(json.dumps({
        "include_formats": False, "include_chapters": False,
    }, indent=2), encoding="utf-8")
    if os.name == "nt":
        # The CLI requires a private options file, including on Windows.
        command = """
$ErrorActionPreference = 'Stop'
$path = [System.IO.Path]::GetFullPath("./prepared/options.json")
$user = [System.Security.Principal.WindowsIdentity]::GetCurrent().User
$acl = [System.Security.AccessControl.FileSecurity]::new()
$acl.SetAccessRuleProtection($true, $false)
$acl.AddAccessRule([System.Security.AccessControl.FileSystemAccessRule]::new($user, 'FullControl', 'Allow'))
[System.IO.File]::SetAccessControl($path, $acl)
"""
        run(["powershell.exe", "-NoProfile", "-NonInteractive", "-Command", command],
            cwd=ROOT, stdin=DEVNULL, check=True, capture_output=True)
    plan = {"run_id": run_id, "source": "youtube_metadata", "input_count": len(ids),
            "input_sha256": hashlib.sha256(data).hexdigest()}
    (prepared / "plan.json").write_text(json.dumps(plan, indent=2), encoding="utf-8")
    print("Prepared", len(ids), "unique videos for", run_id)
except (IndexError, OSError, ValueError, CalledProcessError) as error:
    print(str(error), file=sys.stderr)
    sys.exit(1)
```

#### Exécuter depuis bulk-enrichment/

```bash
python prepare.py videos-001
```


### Bash

#### Vérifier les outils locaux

```bash
jq --version
openssl version
```

#### bulk-enrichment/prepare.sh

```bash
#!/usr/bin/env bash
# Save as bulk-enrichment/prepare.sh.
set -euo pipefail
trap 'exit 1' ERR
umask 077
cd -- "$(dirname -- "$0")"
case "$(uname -s)" in
  MINGW*|MSYS*|CYGWIN*) jq() { command jq --binary "$@"; } ;;
esac
run_id=${1:?Usage: bash prepare.sh videos-001}
[[ "$run_id" =~ ^[A-Za-z0-9][A-Za-z0-9_.:@+-]{0,159}$ ]] || exit 2
# Validate before creating the snapshot; normalize BOM, CRLF and surrounding spaces.
ids=$(jq -Rsc '
  sub("^\uFEFF"; "") | split("\n")
  | if .[-1] == "" then .[:-1] else . end
  | map(gsub("^\\s+|\\s+$"; ""))
  | if length == 0 or any(.[]; test("^[A-Za-z0-9_-]{11}$") | not)
    then error("Use one 11-character ID per line, with no blank rows or URLs.")
    elif length != (unique | length)
    then error("Remove duplicate IDs before submitting.")
    else . end
' video-ids.txt)
mkdir prepared
printf '%s' "$ids" | jq -r '.[]' > prepared/video-ids.txt
printf '%s\n' '{"include_formats":false,"include_chapters":false}' > prepared/options.json
case "$(uname -s)" in
  MINGW*|MSYS*|CYGWIN*)
    powershell.exe -NoProfile -NonInteractive -Command '
      $ErrorActionPreference = "Stop"
      $path = [System.IO.Path]::GetFullPath("./prepared/options.json")
      $user = [System.Security.Principal.WindowsIdentity]::GetCurrent().User
      $acl = [System.Security.AccessControl.FileSecurity]::new()
      $acl.SetAccessRuleProtection($true, $false)
      $acl.AddAccessRule([System.Security.AccessControl.FileSystemAccessRule]::new($user, "FullControl", "Allow"))
      [System.IO.File]::SetAccessControl($path, $acl)
    ' </dev/null ;;
esac
hash=$(openssl dgst -sha256 prepared/video-ids.txt | awk '{print $NF}')
printf '%s' "$ids" | jq --arg run "$run_id" --arg hash "$hash" '
  {run_id:$run, source:"youtube_metadata", input_count:length, input_sha256:$hash}
' > prepared/plan.json
jq '"Prepared \(.input_count) unique videos for \(.run_id)"' -r prepared/plan.json
```

#### Exécuter depuis bulk-enrichment/

```bash
bash prepare.sh videos-001
```



<a id="plan"></a>

### Fichiers préparés

Le message attendu est Prepared 2 unique videos for videos-001. Ne modifiez pas prepared/. Les métadonnées utilisent include_formats: false et include_chapters: false. Chaque vidéo acceptée est facturée séparément ; les lignes en double seraient traitées séparément, donc cet exemple les bloque avant la soumission.

Choisissez un identifiant d’exécution que vous n’avez pas utilisé pour une autre tâche. Conservez videos-001 pour les nouvelles tentatives et la reprise de cette tâche. Un nouvel identifiant sert à demander volontairement un nouveau jeu de données ou une actualisation.

- [Choisir les champs de métadonnées](https://flashdata.dev/fr/docs/guides/video-metadata-recipe/reference.md#fields)

<a id="submit"></a>

## 2. Soumettre et collecter les résultats

Enregistrez process.py ou process.sh dans bulk-enrichment avant de l’exécuter. La CLI crée une tâche Bulk, envoie les identifiants préparés, lance le traitement et enregistre toutes les parties de résultats dans bulk-results.ndjson. L’attente locale s’arrête après 30 minutes ; le travail accepté par le serveur continue.

Chaque tentative possède son dossier sous attempts/, avec le reçu CLI, l’erreur et l’exécution enregistrée. ready.txt pointe vers le dernier résultat complet. Le code de sortie 2 indique que les résultats complets contiennent des vidéos en échec ; poursuivez l’export et examinez ces lignes.

### Python

#### bulk-enrichment/process.py

```python
# Save as bulk-enrichment/process.py. Requires the FlashData CLI on PATH.
import hashlib
import json
import os
import sys
import tempfile
from pathlib import Path
from subprocess import run, DEVNULL

ROOT = Path(__file__).resolve().parent


def read_json(path):
    return json.loads(path.read_text(encoding="utf-8"))


def main(action):
    os.umask(0o077)
    plan = read_json(ROOT / "prepared/plan.json")
    ids = ROOT / "prepared/video-ids.txt"
    if hashlib.sha256(ids.read_bytes()).hexdigest() != plan["input_sha256"]:
        raise ValueError("The prepared input changed. Restore it before recovery.")
    # Use the same default profile and state directory as auth login/status.
    flags = ["--json", "--non-interactive"]
    def cli(*args):
        return run(["flashdata", *args, *flags], cwd=ROOT, stdin=DEVNULL,
                   capture_output=True, text=True, encoding="utf-8")
    if action == "status":
        result = cli("runs", "show", plan["run_id"])
        if result.returncode:
            raise ValueError(result.stderr)
        saved = json.loads(result.stdout)["data"]
        print(json.dumps({k: saved.get(k) for k in
                          ("id", "remoteId", "status", "stage", "errorCode")}, indent=2))
        if saved.get("remoteId"):
            result = cli("bulk", "get", saved["remoteId"])
            print(result.stdout or result.stderr)
            return result.returncode
        return 0
    if action not in ("submit", "recover"):
        raise ValueError("Choose submit, status or recover.")
    attempts = ROOT / "attempts"
    attempts.mkdir(exist_ok=True)
    directory = Path(tempfile.mkdtemp(prefix="run-", dir=attempts))
    output = str(directory / "bulk-results.ndjson")
    if action == "submit":
        args = ["bulk", "run", "--source", plan["source"], "--input", str(ids),
                "--options", str(ROOT / "prepared/options.json"), "--run-id", plan["run_id"]]
    else:
        args = ["runs", "recover", plan["run_id"]]
    result = cli(*args, "--output", output, "--timeout", "30m")
    (directory / "receipt.json").write_text(result.stdout, encoding="utf-8")
    (directory / "error.json").write_text(result.stderr, encoding="utf-8")
    (directory / "exit-code.txt").write_text(str(result.returncode))
    print("Attempt:", directory.relative_to(ROOT))
    # bulk_item_failures still includes a complete result file with failed rows.
    code = json.loads(result.stderr).get("error", {}).get("code") if result.stderr.strip() else None
    if result.returncode and code != "bulk_item_failures":
        raise ValueError("Collection stopped. Inspect error.json; recover the same run.")
    saved = cli("runs", "show", plan["run_id"])
    (directory / "run.json").write_text(saved.stdout, encoding="utf-8")
    if saved.returncode or not Path(output).is_file():
        raise ValueError("Could not save the run record and results together.")
    record = json.loads(saved.stdout)
    data = record.get("data", {})
    if (not record.get("ok") or data.get("status") != "succeeded"
            or data.get("id") != plan["run_id"] or data.get("source") != plan["source"]
            or data.get("inputFileHash") != plan["input_sha256"]):
        raise ValueError("Inspect the run/input binding before exporting.")
    pointer = ROOT / "ready.next"
    pointer.write_text(directory.relative_to(ROOT).as_posix(), encoding="utf-8")
    pointer.replace(ROOT / "ready.txt")
    print("Results ready for export." if code is None else "Results ready; inspect failed video rows.")
    return 2 if code == "bulk_item_failures" else 0


if __name__ == "__main__":
    try:
        sys.exit(main(sys.argv[1]))
    except (IndexError, KeyError, OSError, ValueError) as error:
        print(str(error), file=sys.stderr)
        sys.exit(1)
```

#### Traiter le fichier préparé

```bash
python process.py submit
```


### Bash

#### bulk-enrichment/process.sh

```bash
#!/usr/bin/env bash
# Save as bulk-enrichment/process.sh. Requires the FlashData CLI on PATH.
set -euo pipefail
umask 077
cd -- "$(dirname -- "$0")"
case "$(uname -s)" in
  MINGW*|MSYS*|CYGWIN*) jq() { command jq --binary "$@"; } ;;
esac
action=${1:?Usage: bash process.sh submit|status|recover}
plan=prepared/plan.json
run_id=$(jq -er '.run_id' "$plan")
hash=$(openssl dgst -sha256 prepared/video-ids.txt | awk '{print $NF}')
jq -e --arg hash "$hash" '.source == "youtube_metadata" and .input_sha256 == $hash' "$plan" >/dev/null
# Keep the same default profile and state directory as auth login/status.
cli=(flashdata --json --non-interactive)
if [[ "$action" == status ]]; then
  saved=$("${cli[@]}" runs show "$run_id")
  printf '%s' "$saved" | jq '.data | {id,remoteId,status,stage,errorCode}'
  remote=$(printf '%s' "$saved" | jq -r '.data.remoteId // empty')
  [[ -z "$remote" ]] || "${cli[@]}" bulk get "$remote"
  exit 0
fi
case "$action" in
  submit) args=(bulk run --source youtube_metadata --input prepared/video-ids.txt
    --options prepared/options.json --run-id "$run_id") ;;
  recover) args=(runs recover "$run_id") ;;
  *) echo 'Choose submit, status or recover.' >&2; exit 2 ;;
esac
mkdir -p attempts
directory=$(mktemp -d attempts/run-XXXXXX)
exit_code=0
"${cli[@]}" "${args[@]}" --output "$directory/bulk-results.ndjson" --timeout 30m \
  > "$directory/receipt.json" 2> "$directory/error.json" || exit_code=$?
printf '%s' "$exit_code" > "$directory/exit-code.txt"
echo "Attempt: $directory"
code=$(jq -r '.error.code // empty' "$directory/error.json")
if [[ "$exit_code" != 0 && "$code" != bulk_item_failures ]]; then
  echo "Collection stopped. Inspect $directory/error.json; recover the same run." >&2
  exit 1
fi
"${cli[@]}" runs show "$run_id" > "$directory/run.json"
test -f "$directory/bulk-results.ndjson"
jq -e --arg run "$run_id" --arg hash "$hash" '
  .ok and .data.status == "succeeded" and .data.id == $run
  and .data.source == "youtube_metadata" and .data.inputFileHash == $hash
' "$directory/run.json" >/dev/null
printf '%s\n' "$directory" > ready.next
mv ready.next ready.txt
echo 'Results ready for export.'
[[ "$code" != bulk_item_failures ]] || { echo 'Inspect failed video rows.'; exit 2; }
```

#### Traiter le fichier préparé

```bash
bash process.sh submit
```



<a id="status"></a>

### Vérifier la progression depuis un autre terminal

Exécutez la commande depuis bulk-enrichment avec le même compte CLI. L’action status affiche l’exécution enregistrée et consulte sa tâche Bulk distante lorsqu’un identifiant est disponible. Elle ne crée ni ne reprend de traitement.

#### Python

##### Lire la progression actuelle

```bash
python process.py status
```


#### Bash

##### Lire la progression actuelle

```bash
bash process.sh status
```



<a id="output"></a>

## 3. Vérifier la correspondance et exporter

Enregistrez export.py ou export.sh à côté des autres scripts, puis exécutez-le. Il vérifie l’exécution enregistrée et l’empreinte du fichier d’entrée, puis associe chaque résultat à son index commençant à zéro et à son video_id. Les parties peuvent arriver dans le désordre. Toute ligne absente, en double ou incohérente bloque l’export.

L’export conserve l’objet de métadonnées complet, l’erreur et la consommation déclarée pour chaque ligne. Les vidéos en échec restent visibles avec metadata: null. Ce petit exemple charge les résultats en mémoire ; pour un grand jeu de données, utilisez l’audit en flux du guide de traitement de fichiers Bulk.

### Python

#### bulk-enrichment/export.py

```python
# Save as bulk-enrichment/export.py. Local files only; no API calls.
import csv
import hashlib
import json
import os
import re
import sys
from pathlib import Path

ROOT = Path(__file__).resolve().parent
try:
    os.umask(0o077)
    directory = (ROOT / "ready.txt").read_text(encoding="utf-8").strip()
    if not re.fullmatch(r"attempts/run-[A-Za-z0-9_-]+", directory):
        raise ValueError("Use the ready.txt written by process.py or process.sh.")
    directory = ROOT / directory
    def read_json(path):
        return json.loads(path.read_text(encoding="utf-8"))
    plan = read_json(ROOT / "prepared/plan.json")
    raw = (ROOT / "prepared/video-ids.txt").read_bytes()
    ids = raw.decode("utf-8").splitlines()
    saved = read_json(directory / "run.json")
    run = saved["data"]
    digest = hashlib.sha256(raw).hexdigest()
    if (not saved.get("ok") or run.get("status") != "succeeded" or run.get("kind") != "bulk:run"
            or run.get("id") != plan["run_id"] or run.get("source") != "youtube_metadata"
            or run.get("inputFileHash") != digest or plan["input_sha256"] != digest
            or plan["input_count"] != len(ids) or not run.get("remoteId")):
        raise ValueError("The saved run does not match this input file.")
    # This recipe loads a small file into memory to validate it before writing exports.
    records = {}
    with (directory / "bulk-results.ndjson").open(encoding="utf-8") as source:
        for line in source:
            row = json.loads(line)
            index = row.get("index")
            if (type(index) is not int or not 0 <= index < len(ids) or index in records
                    or row.get("video_id") != ids[index] or row.get("source") != "youtube_metadata"
                    or row.get("status") not in ("completed", "failed")):
                raise ValueError("Unknown, duplicate or mismatched result row.")
            metadata = None
            if row["status"] == "completed":
                results = row.get("results")
                if (not isinstance(results, list) or len(results) != 1
                        or not isinstance(results[0], dict) or results[0].get("videoId") != ids[index]):
                    raise ValueError("Completed metadata does not match its video.")
                metadata = results[0]
            records[index] = {
                "index": index, "video_id": ids[index], "status": row["status"],
                "metadata": metadata, "error": row.get("error"), "usage": row.get("usage"),
            }
    if len(records) != len(ids):
        raise ValueError("Missing result rows. Recover the same run before exporting.")
    videos = [records[index] for index in range(len(ids))]
    failed = [v["video_id"] for v in videos if v["status"] == "failed"]
    output = ROOT / "export"
    output.mkdir(mode=0o700)  # Never overwrite an earlier export.
    (output / "videos.json").write_text(json.dumps(videos, ensure_ascii=False, indent=2), encoding="utf-8")
    def cell(value):
        if value is None:
            return ""
        if not isinstance(value, str):
            value = json.dumps(value, ensure_ascii=False, separators=(",", ":"))
        # Keep remote text from being interpreted as a spreadsheet formula.
        return "'" + value if re.match(r"^[ \t\r\n]*[=+@-]|^[\t\r\n]", value) else value
    with (output / "videos.csv").open("x", encoding="utf-8", newline="") as target:
        writer = csv.writer(target)
        writer.writerow(["index", "video_id", "status", "title", "duration", "error"])
        for video in videos:
            metadata = video["metadata"] or {}
            writer.writerow([cell(v) for v in (video["index"], video["video_id"], video["status"],
                            metadata.get("title"), metadata.get("duration"), video["error"])])
    (output / "failed-video-ids.txt").write_bytes("".join(v + "\n" for v in failed).encode("utf-8"))
    summary = {"run_id": plan["run_id"], "bulk_id": run["remoteId"], "input_count": len(ids),
               "completed": len(ids) - len(failed), "failed": len(failed), "coverage_complete": True}
    (output / "summary.json").write_text(json.dumps(summary, indent=2), encoding="utf-8")
    print(json.dumps(summary, indent=2))
    print("Saved export/videos.json, videos.csv and failed-video-ids.txt")
    sys.exit(2 if failed else 0)
except (OSError, ValueError, KeyError, TypeError) as error:
    print(str(error), file=sys.stderr)
    sys.exit(1)
```

#### Exporter localement · aucun appel API

```bash
python export.py
```


### Bash

#### bulk-enrichment/export.sh

```bash
#!/usr/bin/env bash
# Save as bulk-enrichment/export.sh. Local files only; no API calls.
set -euo pipefail
trap 'exit 1' ERR
umask 077
cd -- "$(dirname -- "$0")"
case "$(uname -s)" in
  MINGW*|MSYS*|CYGWIN*) jq() { command jq --binary "$@"; } ;;
esac
directory=$(cat ready.txt)
[[ "$directory" =~ ^attempts/run-[A-Za-z0-9_-]+$ ]] || exit 1
hash=$(openssl dgst -sha256 prepared/video-ids.txt | awk '{print $NF}')
jq -e --slurpfile plan prepared/plan.json --arg hash "$hash" '
  .ok and .data.status == "succeeded" and .data.kind == "bulk:run"
  and .data.id == $plan[0].run_id and .data.source == "youtube_metadata"
  and .data.inputFileHash == $hash and $plan[0].input_sha256 == $hash
  and (.data.remoteId | type == "string" and length > 0)
' "$directory/run.json" >/dev/null
# Validate the complete small-sample result before creating export/.
videos=$(jq -sc --rawfile input prepared/video-ids.txt --slurpfile plan prepared/plan.json '
  ($input | split("\n") | .[:-1]) as $ids
  | if $plan[0].input_count != ($ids | length) or length != ($ids | length)
      or any(.[]; (.index | type != "number" or . != floor)
        or .source != "youtube_metadata" or (.status != "completed" and .status != "failed"))
    then error("Missing rows or unexpected source/status/index.")
    else sort_by(.index) end
  | if map(.index) != [range(0; $ids | length)]
      or any(.[]; .video_id != $ids[.index])
    then error("Unknown, duplicate or mismatched rows.")
    elif any(.[]; .status == "completed" and
      ((.results | type != "array" or length != 1) or .results[0].videoId != .video_id))
    then error("Completed metadata does not match its video.")
    else map({index, video_id, status,
      metadata:(if .status == "completed" then .results[0] else null end), error, usage}) end
' "$directory/bulk-results.ndjson")
mkdir export
printf '%s\n' "$videos" | jq . > export/videos.json
jq -r '
  def cell: if . == null then ""
    else (if type == "string" then . else tojson end)
      | if test("^[ \\t\\r\\n]*[=+@-]|^[\\t\\r\\n]") then "'"'"'" + . else . end end;
  (["index","video_id","status","title","duration","error"],
   (.[] | [.index,.video_id,.status,.metadata.title,.metadata.duration,.error] | map(cell)))
  | @csv
' export/videos.json > export/videos.csv
jq -r '.[] | select(.status == "failed") | .video_id' export/videos.json > export/failed-video-ids.txt
jq --slurpfile plan prepared/plan.json --slurpfile run "$directory/run.json" '
  {run_id:$plan[0].run_id, bulk_id:$run[0].data.remoteId, input_count:length,
   completed:([.[] | select(.status == "completed")] | length),
   failed:([.[] | select(.status == "failed")] | length), coverage_complete:true}
' export/videos.json > export/summary.json
cat export/summary.json
echo 'Saved export/videos.json, videos.csv and failed-video-ids.txt'
jq -e '.failed == 0' export/summary.json >/dev/null || exit 2
```

#### Exporter localement · aucun appel API

```bash
bash export.sh
```


- [Auditer un grand fichier avec une mémoire limitée](https://flashdata.dev/fr/docs/guides/bulk/reference.md#audit)

<a id="files"></a>

### Utiliser les fichiers exportés

En cas de succès, le script affiche le résumé et les noms des fichiers enregistrés. L’export renvoie 0 si toutes les vidéos ont réussi, 2 si certaines ont échoué, ou 1 si la validation ou l’écriture échoue. Un dossier export/ existant est conservé ; lisez-le localement au lieu de relancer la soumission.

| Fichier sous export/ | Utilisation |
| --- | --- |
| videos.json | Importez les données dans votre application ou le workflow de votre agent. Les lignes conservent l’ordre d’entrée, les métadonnées, les erreurs et la consommation. |
| videos.csv | Examinez les titres, durées et échecs dans un tableur. Une apostrophe est ajoutée devant les textes ressemblant à une formule ; le JSON conserve le texte d’origine. |
| summary.json | Vérifiez la couverture et les compteurs completed/failed, associés à l’identifiant d’exécution et à l’identifiant Bulk. |
| failed-video-ids.txt | Examinez uniquement les vidéos dont l’échec est confirmé avant de décider d’une nouvelle requête payante. Ce fichier est vide si toutes ont réussi. |

#### Python

##### Lire le résumé et les métadonnées enregistrés

```bash
python -m json.tool export/summary.json
python -m json.tool export/videos.json
```


#### Bash

##### Lire le résumé et les métadonnées enregistrés

```bash
jq . export/summary.json
jq . export/videos.json
```



<a id="expected"></a>

### Exemple de résultat avec une vidéo en échec

Extrait illustratif de videos.json. Une tâche Bulk terminée peut contenir des vidéos en échec. Ne traitez pas un échec comme un résultat réussi vide et ne retirez pas silencieusement la vidéo du jeu de données.

#### export/videos.json

```json
[
  {
    "index": 0,
    "video_id": "jNQXAC9IVRw",
    "status": "completed",
    "metadata": {
      "videoId": "jNQXAC9IVRw",
      "title": "Example video",
      "duration": 19
    },
    "error": null,
    "usage": null
  },
  {
    "index": 1,
    "video_id": "dQw4w9WgXcQ",
    "status": "failed",
    "metadata": null,
    "error": {
      "code": "example_video_unavailable"
    },
    "usage": null
  }
]
```


<a id="recover"></a>

## Reprendre la même tâche

Si l’attente s’est arrêtée ou si une partie des résultats n’a pas pu être lue, exécutez recover. Cette action collecte le résultat de la tâche existante dans un nouveau dossier de tentative et ne met à jour ready.txt qu’après récupération complète. Elle n’envoie aucun nouveau fichier et ne soumet pas de tâche de remplacement. Lancez ensuite l’export si export/ n’existe pas encore.

| État enregistré | Action suivante |
| --- | --- |
| bulk_item_failures | Exportez et examinez failed-video-ids.txt. Ne soumettez pas à nouveau toutes les vidéos réussies. |
| partial_result | Conservez le fichier partiel. Reprenez la même exécution pour récupérer toutes les parties avant l’export. |
| running / finalizing | Reprenez plus tard avec le même identifiant d’exécution, le même profil et le même dossier d’état. |
| paused | Lisez pauseReason dans l’état, corrigez la cause, puis reprenez explicitement cette tâche Bulk avec son identifiant, en suivant le guide des commandes de contrôle. |
| awaiting_upload / bulk_input_required | Inspectez le brouillon enregistré. Envoyez le fichier préparé d’origine et lancez la tâche Bulk existante ; la récupération ne rejoue pas ces actions. |
| Soumission incertaine ou identifiant distant absent | Conservez l’exécution et examinez l’erreur enregistrée ainsi que Bulk Jobs avant de réessayer. Un nouvel identifiant d’exécution peut créer une autre tâche. |
| Source incorrecte, lignes manquantes ou empreinte d’entrée différente | Aucun export n’est accepté. Vérifiez la copie d’entrée préparée, l’exécution enregistrée et le fichier de résultats ; n’inventez pas les métadonnées manquantes. |

### Python

#### Inspecter, puis récupérer le travail existant

```bash
python process.py status
python process.py recover
```


### Bash

#### Inspecter, puis récupérer le travail existant

```bash
bash process.sh status
bash process.sh recover
```


- [Commandes d’envoi, de pause et de reprise](https://flashdata.dev/fr/docs/guides/bulk/reference.md#controls)
- [Tâches Bulk](https://flashdata.dev/app/bulk-jobs)
- [Référence des endpoints Bulk](https://flashdata.dev/fr/docs/reference/bulk-processing/reference.md)

<a id="next"></a>

## Conserver cet instantané ou l’actualiser volontairement

Enregistrez les résultats terminés pendant leur fenêtre de conservation de 24 heures. Vos exports restent des fichiers locaux réutilisables. Pour actualiser les métadonnées plus tard, utilisez un nouveau dossier de travail et un nouvel identifiant d’exécution, après avoir vérifié le coût de la nouvelle requête.

- [Relier les métadonnées à vos propres enregistrements](https://flashdata.dev/fr/docs/guides/enrich-youtube-videos/reference.md)
- [Récupérer des sous-titres horodatés](https://flashdata.dev/fr/docs/guides/timestamped-captions-recipe/reference.md)
