Explorar documentación
Guías
Añade metadatos a una lista de reproducción, lista de lectura o conjunto de datos de tu aplicación, conservando los identificadores originales y todos los resultados.
En esta página
De tus registros a un conjunto de datos enriquecido
Comience con tres registros que se refieren a dos vídeos. Consulta cada vídeo distinto una vez, luego únase a los metadatos de nuevo a los tres registros. Este flujo de trabajo utiliza una pequeña solicitud Batch y mantiene los artículos no exitosos visibles.
| Campos de producción | Propósito |
|---|---|
| record_id · input | Su registro original y sus campos, en el orden original. |
| video_id · query_index · job_id | Trace cada registro a la consulta que lo produjo. |
| status · metadata · result_file | Un resultado completado, o un resultado pendiente explícito de /failed/read-error. |
1. Compruebe sus herramientas y acceso
Utilice FlashData CLI v1.2.1 en PATH y Node.js 22+. Ejecute en una nueva carpeta con el permiso del propietario existente credencial y youtube_metadata. Bash y PowerShell usan los mismos comandos a continuación.
Mantenga la misma cuenta y perfil en todas partes. Para un perfil llamado, establezca FLASHDATA_PROFILE en esta terminal para que el coleccionista también lo use. Los agentes pueden cargar FLASHDATA_API_KEY desde su tienda secreta.
flashdata --version
node --version
flashdata auth status --json
mkdir video-enrichment
cd video-enrichmentEquilibrio de comprobación y capacidad
Confirme el acceso del propietario, el permiso youtube_metadata y la habitación para dos artículos de lote y trabajos pendientes. Si el acceso temporal sigue activo, avíselo o utilice la receta de un solo vídeo. Revise la estimación de funcionamiento seco en el paso 3 antes de enviar.
flashdata account balance --json
flashdata account limits --json2. Prepara tus registros de entrada
Guardar esto como videos.json. Reemplazar los valores con su propio registro IDs y 11-character YouTube video IDs. Campos adicionales permanecen en el mapeo local y no se envían a FlashData. Se permite el vídeo repetido IDs; record_id debe ser único.
[
{
"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"
}
]Guardar prepare.mjs
Cree prepare.mjs junto a videos.json en la carpeta de video-enriquecimiento. Copia el código completo a continuación y guárdalo.
El script valida cada fila antes de crear preparado/. Deduplica el vídeo IDs para esta solicitud de metadatos al tiempo que conserva sus registros y pedidos originales.
// 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));Construir la lista de consultas localmente
Guarda prepare.mjs y ejecútalo una vez. Debes obtener inputRecords: 3, uniqueQueries: 2 y reusedVideoIds: 1. No modifiques prepared/batch.json ni prepared/input-map.json durante esta ejecución. Si prepared/ ya existe, reutilízalo para reanudar; usa otra carpeta para un conjunto de datos diferente.
node prepare.mjs3. Previsualizar y enviar los vídeos únicos
La carrera seca comprueba el recuento real de consultas, los precios actuales y los límites de cuenta. Revise, luego envíe una vez. La muestra tiene dos consultas facturables, aunque la entrada tiene tres registros.
Mantenga submission.json y el directorio de estado CLI. Reutilizar el mismo ID y la entrada después de una interrupción. Una nueva ejecución ID crea nuevo trabajo; inspeccionar una presentación incierta antes de reiniciar.
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. Recoger y unirse a los resultados
Guardar collect.mjs a continuación, ejecutarlo. El coleccionista espera hasta dos minutos por trabajo inacabado, verifica que los resultados pertenecen al vídeo solicitado, y se une a cada resultado a los registros originales. Ejecutar un coleccionista a la vez.
Ejecutar de nuevo para reanudar el mismo trabajo IDs. Reutiliza los resultados locales validados y no envía nuevas consultas. Código de salida 1 significa que algunos resultados todavía necesitan atención; inspeccionarlos en lugar de volver a presentar la lista.
Guardar collect.mjs
Cree collect.mjs en esa misma carpeta de video-enriquecimiento, junto a submission.json y prepare/. Copia el código completo a continuación y guárdalo.
// 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;Ejecutar o reanudar el colector
Ejecutar desde el video-enriquecimiento después de guardar collect.mjs. Mantenga el perfil original CLI y directorio estatal.
node collect.mjsArchivos previstos
| Archivo | Úsalo para |
|---|---|
| enriched.ndjson | Una fila por registro original, incluyendo duplicados y fallas. Importación por record_id. |
| metadata.ndjson | Una fila por consulta única, con trabajo ID, archivo de resultados y créditos reales. Uso de cuenta aquí una vez. |
| results/*.json | Respuestas de éxito crudas más la unión de entrada ahorrada/receipt. |
| failed-videos.json | Se confirman los empleos fallidos de /cancelled para su revisión. Los trabajos pendientes y de terror se mantienen fuera de esta lista. |
5. Utilice los registros enriquecidos en su aplicación
Guardar inspect.mjs en video-enriquecimiento, junto a enriched.ndjson, y luego ejecutarlo desde esa carpeta. Espera tres registros originales y dos consultas únicas. Subir filas completadas por record_id, conservar sus campos de entrada, y mantener filas no completas visibles en su informe de importación. Leer título y duración de metadatos; utilizar video_id para enlaces o una posterior capciones.
// 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.mjsContinúe con el tema que necesita atención
Guardar resultados dentro de su período de retención de 24. Para refrescos recurrentes, utilice una nueva carpeta de instantáneas y ejecute ID solo cuando tenga la intención de pagar datos frescos; mantenga estable record_id en su aplicación.
| Resultado | Siguiente acción |
|---|---|
| pending / processing | Ejecute el coleccionista otra vez más tarde. IDs. |
| failed / cancelled | Revisa failed-videos.json y el error de trabajo. Corregir la causa antes de solicitar intencionalmente ese vídeo de nuevo. |
| read_error | Fijar el acceso, la unión de entrada o el resultado guardado. Mantener el archivo crudo para la inspección; un error de lectura no significa que se necesite una nueva consulta. |
| Resultado desconocido de la presentación | Inspeccione la carrera local e Historia antes de presentar de nuevo. |
flashdata runs show video-metadata-001 --json