Ga naar de inhoud
NL
API-sleutel ophalen
Documentatie bekijken

Handleidingen

Verrijk een lijst met YouTube video's

Voeg metadata toe aan een afspeellijst, leeslijst of toepassingsdataset terwijl u uw originele record IDs en elk resultaat bewaart.

Op deze pagina

Van uw records tot een verrijkte dataset

Begin met drie records die verwijzen naar twee video's. Zoek elke afzonderlijke video één keer op en voeg de metadata terug naar alle drie de records. Deze workflow maakt gebruik van een kleine Batch-verzoek en houdt mislukte items zichtbaar.

UitvoerveldenBetreft
record_id · inputUw originele record en velden, in de originele volgorde.
video_id · query_index · job_idTraceer elke record op de query die het heeft geproduceerd.
status · metadata · result_fileEen voltooid resultaat, of een expliciete pending/failed/read-error uitkomst.

1. Controleer uw tools en toegang

Gebruik FlashData CLI v1.2.1 op PATH en Node.js 22+. Voer in een nieuwe map met uw bestaande eigenaar credential en youtube_metadata toestemming. Bash en PowerShell gebruiken onderstaande commando's.

Hou hetzelfde account en profiel gedurende. Voor een genoemd profiel, stel FLASHDATA_PROFILE in deze terminal zodat de collector het ook gebruikt. Agenten kunnen FLASHDATA_API_KEY laden vanuit hun geheime winkel.

Hulpmiddelen en controle op vrije toegang
flashdata --version
node --version
flashdata auth status --json
mkdir video-enrichment
cd video-enrichment

Controle van de balans en capaciteit

Bevestig de eigenaar toegang, youtube_metadata toestemming en ruimte voor twee batch items en hangende taken. Als tijdelijke toegang nog actief is, claim het of gebruik het single-video recept. Bekijk de schatting van de droogstand in stap 3 alvorens in te dienen.

Gratis account leest
flashdata account balance --json
flashdata account limits --json

2. Maak uw invoer records

Sla dit op als videos.json. Vervang de waarden door je eigen record IDs en 11-karakter YouTube video IDs. Extra velden blijven in de lokale mapping en worden niet verzonden naar FlashData. Herhaalde video IDs zijn toegestaan; record_id moet uniek zijn.

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

prepare.mjs opslaan

Maak prepare.mjs naast videos.json in de video-verrijkingsmap. Kopieer de volledige code hieronder in het en sla het op.

Het script valideert elke rij voordat u prepared/. aanmaakt Het dedupliceert video IDs voor deze metadata verzoek met behoud van uw originele records en bestelling.

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

De zoeklijst lokaal bouwen

Na het opslaan van prepare.mjs, voer het één keer uit. Verwacht inputRecords: 3, uniqueQueries: 2 en reusedVideoIds: 1. Houd prepared/batch.json en prepared/input-map.json ongewijzigd voor deze run. Indien voorbereid/reeds bestaat, hergebruikt u deze om te hervatten; gebruik een nieuwe map voor een andere dataset.

Bereid · geen API-gesprekken voor
node prepare.mjs

3. Preview en verzend de unieke video's

De droge run controleert het werkelijke aantal query's, actuele prijzen en rekeninglimieten. Bekijk het en dien het één keer in. De steekproef heeft twee factureerbare vragen, hoewel de input drie records heeft.

Houd submission.json en de CLI state directory. Hergebruik dezelfde run ID en invoer na een onderbreking. Een nieuwe run ID creëert nieuw werk; inspecteer een onzekere inzending voordat u het opnieuw probeert.

Voorbeeld zonder indienen
flashdata batch submit --input prepared/batch.json --dry-run --json
Na herziening van de raming indienen
flashdata batch submit --input prepared/batch.json --run-id video-metadata-001 --output submission.json --json

4. Verzamelen en aansluiten bij de resultaten

Sla collect.mjs hieronder op en voer het uit. De verzamelaar wacht tot twee minuten per onvoltooide klus, controleert of de resultaten behoren tot de gevraagde video, en voegt zich bij elke uitkomst bij de originele records. Eén verzamelaar tegelijk.

Voer het opnieuw uit om dezelfde baan IDs te hervatten. Het hergebruikt gevalideerde lokale resultaten en stuurt geen nieuwe vragen. Exit code 1 betekent dat sommige uitkomsten nog steeds aandacht nodig hebben; inspecteer ze in plaats van de lijst opnieuw in te dienen.

collect.mjs opslaan

Maak collect.mjs in dezelfde video-verrijkingsmap, naast submission.json en prepared/. Kopieer de volledige code hieronder in het en sla het op.

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;

Uitvoeren of hervatten van de collector

Uitvoeren van video-verrijking na het opslaan van collect.mjs. Houd het oorspronkelijke CLI profiel en de status directory.

Verzamelen of hervatten
node collect.mjs

Verwachte bestanden

BestandGebruik het voor
enriched.ndjsonEén rij per originele plaat, inclusief duplicaten en mislukkingen. Importeren door record_id.
metadata.ndjsonEén rij per unieke query, met taak ID, resultaatbestand en werkelijke credits. Tel het gebruik hier eens.
results/*.jsonRaw succesvolle antwoorden plus de opgeslagen input/receipt binding.
failed-videos.jsonBevestigde failed/cancelled jobs voor beoordeling. In afwachting van en lees-fouttaken worden buiten deze lijst gehouden.

5. Gebruik de verrijkte records in uw toepassing

Bewaar inspect.mjs in video-verrijking, naast enriched.ndjson, en voer het vervolgens uit vanuit die map. Verwacht drie originele platen en twee unieke vragen. Voltooide rijen upsert door record_id, uw invoervelden behouden en niet-voltooide rijen zichtbaar houden in uw importrapport. Lees titel en duur van metadata; gebruik video_id voor links of een latere bijschriften verzoek.

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);
Controleer de samengevoegde records
node inspect.mjs

Ga verder met het punt dat aandacht nodig heeft

Bespaar resultaten binnen hun 24-uur retentieperiode. Gebruik voor terugkerende verfrisseningen een nieuwe snapshotmap en voer ID alleen uit wanneer u van plan bent te betalen voor verse gegevens; houd record_id stabiel in uw toepassing.

ResultaatVolgende actie
pending / processingLaat de verzamelaar later nog eens zien. Hou dezelfde baan als IDs.
failed / cancelledBeoordeel failed-videos.json en de taakfout. Corrigeer de oorzaak voordat je die video opnieuw vraagt.
read_errorRepareer toegang, invoerbinding of het opgeslagen resultaat. Houd het ruwe bestand voor inspectie; een leesfout betekent niet dat er een nieuwe zoekopdracht nodig is.
Inzendingsresultaat onbekendControleer de lokale run en History voordat u opnieuw instuurt.
Controleer de opgeslagen batch
flashdata runs show video-metadata-001 --json