Saltar al contenido
ES
Obtener clave API
Explorar documentación

Guías

Enriquece una lista de vídeos de YouTube

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ónPropósito
record_id · inputSu registro original y sus campos, en el orden original.
video_id · query_index · job_idTrace cada registro a la consulta que lo produjo.
status · metadata · result_fileUn 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.

Herramientas y cheque de acceso gratuito
flashdata --version
node --version
flashdata auth status --json
mkdir video-enrichment
cd video-enrichment

Equilibrio 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.

Cuenta libre lee
flashdata account balance --json
flashdata account limits --json

2. 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.

videos.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"
  }
]

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
// 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.

Preparen no llamadas API
node prepare.mjs

3. 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.

Vista previa sin presentar
flashdata batch submit --input prepared/batch.json --dry-run --json
Presentarse después de examinar la estimación
flashdata batch submit --input prepared/batch.json --run-id video-metadata-001 --output submission.json --json

4. 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
// 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.

Recopilar o reanudar
node collect.mjs

Archivos previstos

ArchivoÚsalo para
enriched.ndjsonUna fila por registro original, incluyendo duplicados y fallas. Importación por record_id.
metadata.ndjsonUna fila por consulta única, con trabajo ID, archivo de resultados y créditos reales. Uso de cuenta aquí una vez.
results/*.jsonRespuestas de éxito crudas más la unión de entrada ahorrada/receipt.
failed-videos.jsonSe 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.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);
Inspeccione los registros unidos
node inspect.mjs

Continú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.

ResultadoSiguiente acción
pending / processingEjecute el coleccionista otra vez más tarde. IDs.
failed / cancelledRevisa failed-videos.json y el error de trabajo. Corregir la causa antes de solicitar intencionalmente ese vídeo de nuevo.
read_errorFijar 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ónInspeccione la carrera local e Historia antes de presentar de nuevo.
Inspeccione el lote salvado
flashdata runs show video-metadata-001 --json