Überspringen zum Inhalt
DE
API-Schlüssel
Dokumentation durchsuchen

Anleitungen

Anreichern einer Liste von YouTube Videos

Fügen Sie Metadaten zu einer Wiedergabeliste, einer Leseliste oder einem Anwendungsdatensatz hinzu, während Sie Ihren ursprünglichen Datensatz IDs und jedes Ergebnis beibehalten.

Auf dieser Seite

Von Ihren Datensätzen zu einem angereicherten Datensatz

Beginnen Sie mit drei Aufzeichnungen, die sich auf zwei Videos beziehen. Abfragen Sie jedes einzelne Video einmal und verbinden Sie dann die Metadaten zu allen drei Datensätzen. Dieser Workflow verwendet eine kleine Batch-Anforderung und hält erfolglose Elemente sichtbar.

AusgabefelderZweck
record_id · inputIhre Originaldatensätze und -felder in der ursprünglichen Reihenfolge.
video_id · query_index · job_idVerfolgen Sie jeden Datensatz zu der Abfrage, die ihn erzeugt hat.
status · metadata · result_fileEin abgeschlossenes Ergebnis oder ein explizites pending/failed/read-error Ergebnis.

1. Überprüfen Sie Ihre Tools und Zugriff

Verwenden Sie FlashData CLI v1.2.1 auf PATH und Node.js 22+. Führen Sie einen neuen Ordner mit Ihrem vorhandenen Besitzernachweis und der Berechtigung youtube_metadata aus. Bash und PowerShell verwenden die gleichen Befehle unten.

Behalten sie das gleiche konto und profil im gesamten. Setzen Sie für ein benanntes Profil FLASHDATA_PROFILE in diesem Terminal, damit der Kollektor es auch verwendet. Agenten können FLASHDATA_API_KEY aus ihrem geheimen Speicher laden.

Tools und freie Zugangsprüfung
flashdata --version
node --version
flashdata auth status --json
mkdir video-enrichment
cd video-enrichment

Kontrollsaldo und Kapazität

Bestätigen Sie den Besitzerzugriff, die youtube_metadata-Berechtigung und den Platz für zwei Batch-Artikel und ausstehende Jobs. Wenn der temporäre Zugriff noch aktiv ist, fordern Sie ihn an oder verwenden Sie das Single-Video-Rezept. Überprüfen Sie die Trockenlaufschätzung in Schritt 3 vor dem Absenden.

Kostenloses Konto liest
flashdata account balance --json
flashdata account limits --json

2. Bereiten Sie Ihre Input Records vor

Speichern Sie dies als videos.json. Ersetzen Sie die Werte durch Ihren eigenen Datensatz IDs und 11-Charakter YouTube Video IDs. Zusätzliche Felder bleiben im lokalen Mapping und werden nicht an FlashData gesendet. Wiederholtes Video IDs ist erlaubt; record_id muss eindeutig sein.

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

Speichern Sie prepare.mjs

Erstellen Sie prepare.mjs neben videos.json im Ordner zur Videoanreicherung. Kopieren Sie den vollständigen Code unten und speichern Sie ihn.

Das Skript validiert jede Zeile vor dem Erstellen von prepared/. Es dedupliziert Video IDs für diese Metadatenanforderung, während Sie Ihre Originaldatensätze und Bestellung beibehalten.

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

Erstellen Sie die Abfrageliste lokal

Nachdem Sie prepare.mjs gespeichert haben, führen Sie es einmal aus. Erwarten Sie inputRecords: 3, uniqueQueries: 2 und reusedVideoIds: 1. Halten Sie prepared/batch.json und prepared/input-map.json für diesen Lauf unverändert. Wenn vorbereitet / bereits vorhanden, verwenden Sie es erneut, um es wieder aufzunehmen; Verwenden Sie einen neuen Ordner für einen anderen Datensatz.

Vorbereiten · keine API Anrufe
node prepare.mjs

3. Vorschau und Einreichen der einzigartigen Videos

Der Trockenlauf überprüft die tatsächliche Abfrageanzahl, aktuelle Preise und Kontolimits. Überprüfen Sie es, dann einmal einreichen. Das Sample hat zwei abrechenbare Abfragen, obwohl die Eingabe drei Datensätze hat.

Halten Sie submission.json und das CLI-Zustandsverzeichnis. Verwenden Sie den gleichen Lauf ID und geben Sie ihn nach einer Unterbrechung ein. Ein neuer Lauf ID erstellt neue Arbeit; prüfen Sie eine unsichere Einreichung, bevor Sie erneut versuchen.

Preview ohne Vorlage
flashdata batch submit --input prepared/batch.json --dry-run --json
Einreichung nach Überprüfung der Schätzung
flashdata batch submit --input prepared/batch.json --run-id video-metadata-001 --output submission.json --json

4. Sammeln und Verbinden der Ergebnisse

Speichern Sie collect.mjs unten und führen Sie es aus. Der Sammler wartet bis zu zwei Minuten pro unvollendetem Auftrag, überprüft, ob die Ergebnisse zum angeforderten Video gehören, und fügt jedes Ergebnis den Originaldatensätzen hinzu. Führen Sie einen Sammler nach dem anderen.

Führen Sie es erneut aus, um den gleichen Job IDs wieder aufzunehmen. Es verwendet validierte lokale Ergebnisse wieder und sendet keine neuen Abfragen. Exit-Code 1 bedeutet, dass einige Ergebnisse noch Aufmerksamkeit brauchen; inspizieren Sie sie, anstatt die Liste erneut einzureichen.

Speichern Sie collect.mjs

Erstellen Sie collect.mjs in demselben Video-Anreicherungsordner neben submission.json und prepared/. Kopieren Sie den vollständigen Code unten und speichern Sie ihn.

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;

Führen oder Fortsetzen des Sammlers

Führen Sie von der Videoanreicherung aus, nachdem Sie collect.mjs gespeichert haben. Behalten Sie das ursprüngliche CLI-Profil und das Zustandsverzeichnis bei.

Sammeln oder Lebenslauf
node collect.mjs

Voraussichtliche Dateien

DateiVerwenden Sie es für
enriched.ndjsonEine Zeile pro Originaldatensatz, einschließlich Duplikaten und Fehlern. Importiert von record_id.
metadata.ndjsonEine Zeile pro eindeutiger Abfrage, mit Job ID, Ergebnisdatei und tatsächlichen Credits. Zählen Sie die Nutzung hier einmal.
results/*.jsonRohe erfolgreiche Antworten plus die gespeicherte input/receipt Bindung.
failed-videos.jsonfailed/cancelled-Jobs zur Überprüfung bestätigt. Ausstehende und Lesefehler-Jobs werden aus dieser Liste herausgehalten.

5. Verwenden Sie die angereicherten Datensätze in Ihrer Anwendung

Speichern Sie inspect.mjs in der Videoanreicherung neben enriched.ndjson und führen Sie es dann aus diesem Ordner aus. Erwarten Sie drei Originaldatensätze und zwei eindeutige Abfragen. Upsert abgeschlossene Zeilen von record_id, behält Ihre Eingabefelder bei und hält nicht abgeschlossene Zeilen in Ihrem Importbericht sichtbar. Lesen Sie Titel und Dauer aus Metadaten; verwenden Sie video_id für Links oder eine spätere Beschriftungsanforderung.

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);
Inspizieren Sie die verbundenen Aufzeichnungen
node inspect.mjs

Weiter von dem Punkt, der Aufmerksamkeit braucht

Speichern Sie die Ergebnisse innerhalb ihrer 24-Stunden-Aufbewahrungsdauer. Verwenden Sie für wiederkehrende Aktualisierungen einen neuen Snapshot-Ordner und führen Sie ID nur aus, wenn Sie für neue Daten bezahlen möchten; halten Sie record_id in Ihrer Anwendung stabil.

ErgebnisNächste Maßnahme
pending / processingFühren Sie den Sammler später noch einmal. Behalten Sie den gleichen Job IDs.
failed / cancelledÜberprüfen Sie failed-videos.json und den Jobfehler. Korrigieren Sie die Ursache, bevor Sie das Video absichtlich erneut anfordern.
read_errorFix access, input binding oder das gespeicherte Ergebnis. Bewahren Sie die Rohdatei zur Inspektion auf; ein Lesefehler bedeutet nicht, dass eine neue Abfrage erforderlich ist.
Ergebnis der Einreichung unbekanntÜberprüfen Sie den lokalen Lauf und History, bevor Sie erneut einreichen.
Prüfen Sie die gespeicherte Charge
flashdata runs show video-metadata-001 --json