Salta al contenuto
IT
Ottieni la chiave API
Sfoglia la documentazione

Guide

Arricchire un elenco di video YouTube

Aggiungi i metadati a una playlist, un elenco di lettura o un set di dati dell'applicazione, mantenendo il tuo record originale IDs e ogni risultato.

In questa pagina

Dai tuoi record a un set di dati arricchito

Inizia con tre record che si riferiscono a due video. Accosta ogni video distinta una volta, quindi unisciti ai metadati a tutti e tre i record. Questo flusso di lavoro utilizza una piccola richiesta Batch e mantiene gli elementi non riusciti visibili.

Campi di uscitaOggetto
record_id · inputIl tuo record originale e i campi, nell'ordine originale.
video_id · query_index · job_idTraccia ogni record alla query che l'ha prodotto.
status · metadata · result_fileUn risultato completato, o un risultato esplicito pending/failed/read-error.

1. Controlla i tuoi strumenti e l'accesso

Utilizzare FlashData CLI v1.2.1 su PATH e Node.js 22+. Eseguire in una nuova cartella con le credenziali del proprietario esistenti e il permesso youtube_metadata. Bash e PowerShell utilizzano gli stessi comandi qui sotto.

Tenere lo stesso account e profilo in tutto. Per un profilo chiamato, impostare FLASHDATA_PROFILE in questo terminale in modo che il collettore lo utilizza anche. Gli agenti possono caricare FLASHDATA_API_KEY dal loro negozio segreto.

Strumenti e controllo di accesso gratuito
flashdata --version
node --version
flashdata auth status --json
mkdir video-enrichment
cd video-enrichment

Bilancio di controllo e capacità

Confermare l'accesso del proprietario, il permesso youtube_metadata e la stanza per due elementi batch e lavori in sospeso. Se l'accesso temporaneo è ancora attivo, rivendicarlo o utilizzare la ricetta single-video. Verificare la stima a secco nel passo 3 prima di presentare.

Leggi di account gratuito
flashdata account balance --json
flashdata account limits --json

2. Preparare i record di input

Salva questo come videos.json. Sostituire i valori con il proprio record IDs e 11-character YouTube video IDs. Ulteriori campi rimangono nella mappatura locale e non vengono inviati a FlashData. Sono ammessi i video ripetuti IDs; record_id deve essere unico.

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

Salvare prepare.mjs

Creare prepare.mjs accanto a videos.json nella cartella di arricchimento video. Copia il codice completo qui sotto e salvalo.

Lo script convalida ogni riga prima di creare prepared/. Deduplica il video IDs per questa richiesta di metadati pur mantenendo i record e l'ordine originali.

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));

Costruire l'elenco delle query localmente

Dopo aver salvato prepare.mjs, eseguirlo una volta. inputRecords: 3, uniqueQueries: 2 e reusedVideoIds: 1. Mantenere prepared/batch.json e prepared/input-map.json invariati per questa corsa. Se è già pronto/esistente, riutilizzarlo per riprendere; utilizzare una nuova cartella per un diverso set di dati.

Preparare senza chiamate API
node prepare.mjs

3. Anteprima e invia i video unici

La corsa a secco controlla il conteggio delle query, i limiti attuali dei prezzi e degli account. Esaminalo, poi invia una volta. Il campione ha due query fatturabili, anche se l'ingresso ha tre record.

Tenere submission.json e la directory di stato CLI. Riutilizzare lo stesso eseguire ID e l'ingresso dopo un'interruzione. Una nuova esecuzione ID crea un nuovo lavoro; ispezionare una presentazione incerta prima di riprovare.

Anteprima senza presentazione
flashdata batch submit --input prepared/batch.json --dry-run --json
Inviare dopo aver esaminato la stima
flashdata batch submit --input prepared/batch.json --run-id video-metadata-001 --output submission.json --json

4. Raccogliere e raggiungere i risultati

Salva collect.mjs qui sotto, quindi eseguilo. Il collezionista aspetta fino a due minuti per lavoro incompiuto, verifica che i risultati appartengono al video richiesto, e si unisce a ogni risultato ai record originali. Esegui un collettore alla volta.

Eseguilo di nuovo per riprendere lo stesso lavoro IDs. Riutilizza i risultati locali convalidati e non invia nuove domande. Il codice di uscita 1 significa che alcuni risultati hanno ancora bisogno di attenzione; ispezionare loro invece di risottomettere l'elenco.

Salvare collect.mjs

Crea collect.mjs nella stessa cartella di arricchimento video, accanto a submission.json e prepared/. Copia il codice completo qui sotto e salvalo.

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;

Correre o riprendere il collettore

Eseguite da arricchimento video dopo aver salvato collect.mjs. Mantenere il profilo e la directory di stato CLI originale.

Raccogliere o riprendere
node collect.mjs

File previsti

FileUsalo per
enriched.ndjsonUna riga per record originale, inclusi duplicati e guasti. Importazione da record_id.
metadata.ndjsonUna riga per query unica, con lavoro ID, file di risultato e crediti effettivi. Conta l'uso qui una volta.
results/*.jsonRisposte di successo raw più il binding input/receipt salvato.
failed-videos.jsonConfermato failed/cancelled lavori per la revisione. I posti di lavoro in attesa e di lettura sono tenuti fuori da questa lista.

5. Utilizzare i record arricchiti nella vostra applicazione

Salvare inspect.mjs in arricchimento video, accanto a enriched.ndjson, quindi eseguirlo da quella cartella. Aspettatevi tre record originali e due domande uniche. Aggiornare le righe completate da record_id, mantenere i campi di input e mantenere le righe non complete visibili nel rapporto di importazione. Leggere il titolo e la durata dei metadati; utilizzare video_id per i collegamenti o una richiesta didascalia successiva.

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);
Ispezionare i record uniti
node inspect.mjs

Proseguire dall'oggetto che ha bisogno di attenzione

Salva i risultati nel loro periodo di conservazione 24-ora. Per i rinfreschi ricorrenti, utilizzare una nuova cartella snapshot ed eseguire ID solo quando si desidera pagare per i dati freschi; mantenere record_id stabile nella vostra applicazione.

RisultatoProssima azione
pending / processingRispondete al collezionista più tardi. Mantenere lo stesso lavoro IDs.
failed / cancelledRecensione failed-videos.json e l'errore di lavoro. Correggere la causa prima di chiedere di nuovo quel video.
read_errorFissare l'accesso, il legame di input o il risultato salvato. Mantenere il file grezzo per l'ispezione; un errore di lettura non significa che una nuova query è necessaria.
Esito di sottomissione sconosciutoIspezionare la corsa locale e History prima di inviare di nuovo.
Ispezionare il lotto salvato
flashdata runs show video-metadata-001 --json