Parcourir la documentation
Guides
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.
Sur cette page
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. |
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.
flashdata --version
node --version
flashdata auth status --json
mkdir video-enrichment
cd video-enrichmentVé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.
flashdata account balance --json
flashdata account limits --json2. 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.
[
{
"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"
}
]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 — 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));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.
node prepare.mjs3. 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.
flashdata batch submit --input prepared/batch.json --dry-run --jsonflashdata batch submit --input prepared/batch.json --run-id video-metadata-001 --output submission.json --json4. 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.
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 — 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;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.
node collect.mjsFichiers 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. |
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 — 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);node inspect.mjsReprendre à 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. |
flashdata runs show video-metadata-001 --json