Documentatie bekijken
Handleidingen
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.
| Uitvoervelden | Betreft |
|---|---|
| record_id · input | Uw originele record en velden, in de originele volgorde. |
| video_id · query_index · job_id | Traceer elke record op de query die het heeft geproduceerd. |
| status · metadata · result_file | Een 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.
flashdata --version
node --version
flashdata auth status --json
mkdir video-enrichment
cd video-enrichmentControle 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.
flashdata account balance --json
flashdata account limits --json2. 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.
[
{
"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 — 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.
node prepare.mjs3. 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.
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. 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 — 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.
node collect.mjsVerwachte bestanden
| Bestand | Gebruik het voor |
|---|---|
| enriched.ndjson | Eén rij per originele plaat, inclusief duplicaten en mislukkingen. Importeren door record_id. |
| metadata.ndjson | Eén rij per unieke query, met taak ID, resultaatbestand en werkelijke credits. Tel het gebruik hier eens. |
| results/*.json | Raw succesvolle antwoorden plus de opgeslagen input/receipt binding. |
| failed-videos.json | Bevestigde 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 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.mjsGa 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.
| Resultaat | Volgende actie |
|---|---|
| pending / processing | Laat de verzamelaar later nog eens zien. Hou dezelfde baan als IDs. |
| failed / cancelled | Beoordeel failed-videos.json en de taakfout. Corrigeer de oorzaak voordat je die video opnieuw vraagt. |
| read_error | Repareer toegang, invoerbinding of het opgeslagen resultaat. Houd het ruwe bestand voor inspectie; een leesfout betekent niet dat er een nieuwe zoekopdracht nodig is. |
| Inzendingsresultaat onbekend | Controleer de lokale run en History voordat u opnieuw instuurt. |
flashdata runs show video-metadata-001 --json