# Enrichir une liste de vidéos YouTube

Ajoutez des métadonnées à une playlist, une liste de lecture ou un jeu de données applicatif en conservant les identifiants d’origine et tous les résultats.

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

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

## Passer de vos enregistrements à un jeu de données enrichi

Partez de trois enregistrements qui désignent deux vidéos. Interrogez chaque vidéo distincte une seule fois, puis associez les métadonnées aux trois enregistrements. Ce workflow utilise une petite requête Batch et conserve aussi les éléments sans résultat réussi.

| Champs de sortie | Rôle |
| --- | --- |
| record_id · input | Votre enregistrement et ses champs d’origine, dans l’ordre initial. |
| video_id · query_index · job_id | Relier chaque enregistrement à la requête qui l’a produit. |
| status · metadata · result_file | Un résultat terminé ou un état explicite : en attente, en échec ou en erreur de lecture. |

- [Traiter une seule vidéo](https://flashdata.dev/fr/docs/guides/video-metadata-recipe/reference.md)
- [Traiter un fichier plus volumineux](https://flashdata.dev/fr/docs/guides/bulk/reference.md)
- [Choisir entre Batch et Bulk](https://flashdata.dev/fr/docs/reference/batch-and-bulk/reference.md#choose)

<a id="authenticate"></a>

## 1. Vérifier les outils et l’accès

Utilisez la CLI FlashData v1.2.1 disponible dans PATH et Node.js 22+. Travaillez dans un nouveau dossier avec votre clé propriétaire existante et la permission youtube_metadata. Les commandes ci-dessous sont identiques dans Bash et PowerShell.

Conservez le même compte et le même profil à toutes les étapes. Pour un profil nommé, définissez FLASHDATA_PROFILE dans ce terminal afin que le collecteur l’utilise aussi. Les agents peuvent charger FLASHDATA_API_KEY depuis leur stockage de secrets.

### Outils et vérification gratuite de l’accès

```bash
flashdata --version
node --version
flashdata auth status --json
mkdir video-enrichment
cd video-enrichment
```

- [Installer la CLI](https://flashdata.dev/fr/docs/guides/flashdata-cli/reference.md#install)
- [Configurer une clé propriétaire](https://flashdata.dev/fr/docs/guides/cli-automation/reference.md#profiles)

<a id="access-check"></a>

### Vérifier le solde et la capacité

Confirmez l’accès propriétaire, la permission youtube_metadata et la capacité disponible pour deux éléments Batch et leurs tâches en attente. Si l’accès temporaire est encore actif, rattachez-le à votre compte ou utilisez la recette pour une seule vidéo. Vérifiez l’estimation de la simulation à l’étape 3 avant de soumettre.

#### Lectures gratuites du compte

```bash
flashdata account balance --json
flashdata account limits --json
```


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

## 2. Préparer les enregistrements d’entrée

Enregistrez ce contenu dans videos.json. Remplacez les valeurs par vos identifiants d’enregistrement et des identifiants vidéo YouTube de 11 caractères. Les champs supplémentaires restent dans la table de correspondance locale et ne sont pas envoyés à FlashData. Les identifiants vidéo peuvent se répéter ; record_id doit être unique.

### videos.json

```json
[
  {
    "record_id": "lesson-intro",
    "video_id": "jNQXAC9IVRw",
    "collection": "Course"
  },
  {
    "record_id": "playlist-song",
    "video_id": "dQw4w9WgXcQ",
    "collection": "Playlist"
  },
  {
    "record_id": "saved-intro",
    "video_id": "jNQXAC9IVRw",
    "collection": "Reading list"
  }
]
```


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

### Enregistrer prepare.mjs

Créez prepare.mjs à côté de videos.json dans le dossier video-enrichment. Copiez-y le code complet ci-dessous et enregistrez-le.

Le script valide chaque ligne avant de créer prepared/. Il déduplique les identifiants vidéo pour cette requête de métadonnées tout en conservant les enregistrements et leur ordre d’origine.

#### prepare.mjs

```javascript
// prepare.mjs — local preparation; sends no API requests.
import { mkdir, readFile, writeFile } from 'node:fs/promises';

const rows = JSON.parse((await readFile('videos.json', 'utf8')).replace(/^\uFEFF/, ''));
if (!Array.isArray(rows) || rows.length === 0) throw new Error('Supply a nonempty array of records.');
const recordIds = new Set(), videoIndexes = new Map(), queries = [];
const mapping = rows.map((input, index) => {
  if (!input || typeof input !== 'object' || Array.isArray(input)
      || typeof input.record_id !== 'string' || !input.record_id.trim()
      || recordIds.has(input.record_id) || typeof input.video_id !== 'string'
      || !/^[A-Za-z0-9_-]{11}$/.test(input.video_id)) {
    throw new Error('Invalid or duplicate record_id, or invalid video_id at row ' + (index + 1));
  }
  recordIds.add(input.record_id);
  if (!videoIndexes.has(input.video_id)) {
    videoIndexes.set(input.video_id, queries.length);
    queries.push({ source: 'youtube_metadata', video_id: input.video_id,
      params: { include_formats: false } });
  }
  return { input, query_index: videoIndexes.get(input.video_id) };
});
// Existing preparation is kept intact. Use it to resume, or choose a new folder.
await mkdir('prepared');
await writeFile('prepared/batch.json', JSON.stringify(queries, null, 2), { flag: 'wx' });
await writeFile('prepared/input-map.json', JSON.stringify(mapping, null, 2), { flag: 'wx' });
console.log(JSON.stringify({ inputRecords: rows.length, uniqueQueries: queries.length,
  reusedVideoIds: rows.length - queries.length }, null, 2));
```


<a id="prepared"></a>

### Construire la liste de requêtes localement

Après avoir enregistré prepare.mjs, exécutez-le une fois. Le résultat attendu est inputRecords: 3, uniqueQueries: 2 et reusedVideoIds: 1. Conservez prepared/batch.json et prepared/input-map.json sans modification pour cette exécution. Si prepared/ existe déjà, réutilisez-le pour reprendre ; choisissez un nouveau dossier pour un autre jeu de données.

#### Préparer · aucun appel API

```bash
node prepare.mjs
```


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

## 3. Vérifier puis soumettre les vidéos distinctes

La simulation vérifie le nombre réel de requêtes, les tarifs actuels et les limites du compte. Examinez-la, puis soumettez une seule fois. L’exemple comporte deux requêtes facturables, même si l’entrée contient trois enregistrements.

Conservez submission.json et le répertoire d’état CLI. Après une interruption, réutilisez le même identifiant d’exécution et les mêmes paramètres. Un nouvel identifiant crée de nouvelles opérations ; examinez toute soumission incertaine avant de la retenter.

### Simuler sans soumettre

```bash
flashdata batch submit --input prepared/batch.json --dry-run --json
```

### Soumettre après avoir vérifié l’estimation

```bash
flashdata batch submit --input prepared/batch.json --run-id video-metadata-001 --output submission.json --json
```

- [Spécification des requêtes Batch](https://flashdata.dev/fr/docs/reference/batch-and-bulk/reference.md#batch)

<a id="finish"></a>

## 4. Collecter et associer les résultats

Enregistrez collect.mjs ci-dessous, puis exécutez-le. Le collecteur attend au maximum deux minutes par tâche inachevée, vérifie que les résultats correspondent à la vidéo demandée et associe chaque résultat aux enregistrements d’origine. Exécutez un seul collecteur à la fois.

Relancez-le pour reprendre les mêmes identifiants de tâche. Il réutilise les résultats locaux validés sans envoyer de nouvelles requêtes. Le code de sortie 1 indique que certains résultats demandent encore une intervention ; examinez-les au lieu de soumettre à nouveau toute la liste.


<a id="collector"></a>

### Enregistrer collect.mjs

Créez collect.mjs dans le même dossier video-enrichment, à côté de submission.json et de prepared/. Copiez-y le code complet ci-dessous et enregistrez-le.

#### collect.mjs

```javascript
// collect.mjs — reads saved jobs; never submits another query.
import { execFileSync } from 'node:child_process';
import { mkdir, readFile, writeFile, rename } from 'node:fs/promises';

const readJSON = async file => JSON.parse((await readFile(file, 'utf8')).replace(/^\uFEFF/, ''));
const cli = (...args) => JSON.parse(execFileSync('flashdata', [
  ...args, '--json', '--non-interactive', '--timeout', '2m',
], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 16 * 1024 * 1024 }));
const inputs = await readJSON('prepared/batch.json');
const mapping = await readJSON('prepared/input-map.json');
const saved = await readJSON('submission.json');
const receipts = (saved.submission ?? saved).queries;
if (!Array.isArray(inputs) || !inputs.length || !Array.isArray(receipts)
    || receipts.length !== inputs.length || new Set(receipts.map(r => r.id)).size !== receipts.length
    || inputs.some(q => q.source !== 'youtube_metadata') || !Array.isArray(mapping) || !mapping.length
    || mapping.some(row => !Number.isInteger(row.query_index)
      || inputs[row.query_index]?.video_id !== row.input?.video_id)) {
  throw new Error('Input/receipt mismatch. Keep the original prepared files and receipt.');
}
await mkdir('results', { recursive: true });
const binding = JSON.stringify({ inputs, mapping, receipts });
try { await writeFile('results/input-receipts.json', binding, { flag: 'wx' }); }
catch (error) {
  if (error.code !== 'EEXIST') throw error;
  if (await readFile('results/input-receipts.json', 'utf8') !== binding) {
    throw new Error('Inputs or receipts changed. Restore the original files.');
  }
}
const rows = inputs.map((input, query_index) => ({ query_index,
  video_id: input.video_id, job_id: receipts[query_index].id, status: 'unread' }));
const saveRows = async (path, values) => {
  await writeFile(path + '.next', values.map(row => JSON.stringify(row)).join('\n') + '\n');
  await rename(path + '.next', path);
};
for (const row of rows) {
  try {
    if (!/^[a-zA-Z0-9_-]+$/.test(row.job_id ?? '')) throw new Error('Invalid job ID.');
    const file = 'results/' + row.job_id + '.json';
    let result;
    try { result = await readJSON(file); }
    catch (error) { if (error.code !== 'ENOENT') throw error; }
    if (!result) {
      let job;
      try { job = cli('jobs', 'wait', row.job_id).data; }
      catch { job = cli('jobs', 'get', row.job_id).data; }
      if (job.videoId !== row.video_id || job.source !== 'youtube_metadata') {
        throw new Error('Job/input mismatch. Inspect the saved input and receipt.');
      }
      row.status = job.status;
      row.error = job.error ?? null;
      if (job.status === 'completed') {
        cli('jobs', 'result', row.job_id, '--output', file);
        result = await readJSON(file);
      }
    }
    if (result) {
      if (result.status !== 'done' || result.source !== 'youtube_metadata'
          || result.results?.length !== 1 || result.results[0].videoId !== row.video_id) {
        throw new Error('Result/video mismatch. Inspect the saved JSON before continuing.');
      }
      Object.assign(row, { status: 'completed', metadata: result.results[0], error: null,
        credits: result.usage?.credits ?? null, result_file: file });
    }
  } catch (error) {
    row.status = 'read_error';
    row.error = error.stderr?.toString().trim() || error.message;
  }
  await saveRows('metadata.ndjson', rows); // One outcome and charge per unique query.
  await saveRows('enriched.ndjson', mapping.map(({ input, query_index }) => {
    const { credits, ...outcome } = rows[query_index]; // Do not duplicate a charge across input records.
    return { record_id: input.record_id, input, ...outcome };
  }));
}
const failed = rows.filter(row => ['failed', 'cancelled'].includes(row.status));
await writeFile('failed-videos.json', JSON.stringify(failed, null, 2));
console.table(rows.map(({ video_id, job_id, status }) => ({ video_id, job_id, status })));
console.log('Saved enriched.ndjson, metadata.ndjson and results/*.json.');
if (rows.some(row => row.status !== 'completed')) process.exitCode = 1;
```


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

### Exécuter ou reprendre le collecteur

Lancez la commande depuis video-enrichment après avoir enregistré collect.mjs. Conservez le profil CLI et le répertoire d’état d’origine.

#### Collecter ou reprendre

```bash
node collect.mjs
```


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

### Fichiers attendus

| Fichier | Utilisation |
| --- | --- |
| enriched.ndjson | Une ligne par enregistrement d’origine, doublons et échecs compris. Importez selon record_id. |
| metadata.ndjson | Une ligne par requête distincte, avec l’identifiant de tâche, le fichier de résultat et les crédits réellement consommés. Comptabilisez la consommation une seule fois à partir de ce fichier. |
| results/*.json | Les réponses brutes réussies et la correspondance enregistrée entre paramètres et reçu. |
| failed-videos.json | Les tâches confirmées en échec ou annulées à examiner. Les tâches en attente et les erreurs de lecture sont exclues de cette liste. |


<a id="use-dataset"></a>

## 5. Utiliser les enregistrements enrichis dans votre application

Enregistrez inspect.mjs dans video-enrichment, à côté de enriched.ndjson, puis exécutez-le depuis ce dossier. Le résultat attendu contient trois enregistrements d’origine et deux requêtes distinctes. Insérez ou mettez à jour les lignes terminées selon record_id, conservez les champs d’entrée et gardez les lignes non terminées dans le rapport d’importation. Lisez title et duration dans metadata ; utilisez video_id pour les liens ou une demande ultérieure de sous-titres.

### inspect.mjs

```javascript
// inspect.mjs — inspect your dataset without another API call.
import { readFile } from 'node:fs/promises';
const rows = (await readFile('enriched.ndjson', 'utf8')).trim().split('\n').map(JSON.parse);
console.table(rows.map(row => ({ record_id: row.record_id, video_id: row.video_id,
  collection: row.input.collection, status: row.status, title: row.metadata?.title ?? null })));
console.log('Original records:', rows.length);
console.log('Unique queries:', new Set(rows.map(row => row.query_index)).size);
```

### Examiner les enregistrements enrichis

```bash
node inspect.mjs
```

- [Choisir les sous-titres d’une vidéo](https://flashdata.dev/fr/docs/guides/youtube-data-guide/reference.md#captions)

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

## Reprendre à l’élément qui demande une intervention

Enregistrez les résultats pendant leur période de conservation de 24 heures. Pour des mises à jour récurrentes, créez un nouveau dossier d’instantané et un nouvel identifiant d’exécution uniquement si vous souhaitez payer pour des données actualisées. Conservez le même record_id dans votre application.

| Résultat | Action suivante |
| --- | --- |
| pending / processing | Relancez le collecteur plus tard, en conservant les mêmes identifiants de tâche. |
| failed / cancelled | Examinez failed-videos.json et l’erreur de la tâche. Corrigez la cause avant de demander volontairement cette vidéo à nouveau. |
| read_error | Corrigez l’accès, la correspondance avec les paramètres ou le résultat enregistré. Conservez le fichier brut pour l’examiner ; une erreur de lecture n’implique pas qu’une nouvelle requête soit nécessaire. |
| Résultat de soumission inconnu | Examinez l’exécution locale et History avant de soumettre à nouveau. |

### Examiner le lot enregistré

```bash
flashdata runs show video-metadata-001 --json
```

- [Reprendre une opération incertaine](https://flashdata.dev/fr/docs/guides/agent-recovery/reference.md)
- [Traiter un fichier plus volumineux avec Bulk](https://flashdata.dev/fr/docs/guides/bulk/reference.md)
- [Enregistrer et réutiliser les résultats](https://flashdata.dev/fr/docs/guides/save-results/reference.md)
