Lewati ke isi
ID
Dapatkan kunci API
Jelajahi dokumentasi

Panduan

Sebesar daftar video YouTube

Tambahkan metadata ke daftar main, membaca daftar, atau data aplikasi sambil menyimpan catatan asli Anda IDs dan setiap hasil.

Di halaman ini

Dari catatan Anda ke dataset diperkaya

Mulailah dengan tiga rekaman mengacu pada dua video. Kueri setiap video yang berbeda sekali, kemudian bergabung kembali ke semua tiga catatan. Aliran kerja ini menggunakan permintaan Batch kecil dan menjaga item yang tidak sukses tetap terlihat.

Ruas keluaranTujuan
record_id · inputCatatan asli dan bidang, dalam urutan asli.
video_id · query_index · job_idLacak setiap rekaman ke query yang diproduksi itu.
status · metadata · result_fileHasil yang selesai, atau hasil pending/failed/read-error.

1. Periksa alat dan akses Anda

Gunakan FlashData CLI v1.2.1 nyala PATH dan Node.js 22+. Jalankan dalam folder baru dengan izin pemilik kredensial yang ada dan youtube_metadata. Bash dan PowerShell menggunakan perintah yang sama di bawah ini.

Simpan rekening dan profil yang sama di seluruh. Untuk profil bernama, set FLASHDATA_PROFILE di terminal ini sehingga kolektor juga menggunakannya. Agen dapat memuat FLASHDATA_API_KEY dari toko rahasia mereka.

Perkakas dan pemeriksaan akses bebas
flashdata --version
node --version
flashdata auth status --json
mkdir video-enrichment
cd video-enrichment

Periksa keseimbangan dan kapasitas

Konfirmasi akses pemilik, youtube_metadata izin dan ruang untuk dua item batch dan pekerjaan yang tertunda. Jika akses sementara masih aktif, klaim atau menggunakan resep tunggal-video. Tinjau perkiraan kering dalam langkah 3 sebelum mengirimkan.

Rekening bebas dibaca
flashdata account balance --json
flashdata account limits --json

2. Siapkan catatan masukan Anda

Simpan ini sebagai videos.json. Ganti nilai dengan catatan Anda sendiri IDs dan 11-character YouTube video IDs. Ruas tambahan tetap pada pemetaan lokal dan tidak dikirim ke FlashData. Video berulang IDs diperbolehkan; record_id harus unik.

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

Simpan prepare.mjs

Buat prepare.mjs di samping videos.json dalam folder pengayaan video. Salin kode lengkap di bawah ini dan simpan.

Skrip memvalidasi setiap baris sebelum membuat prepared/. Video deduplikasi IDs untuk permintaan metadata ini saat menyimpan catatan asli dan ketertiban Anda.

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

Bangun daftar permintaan secara lokal

Setelah menyelamatkan prepare.mjs, jalankan sekali. Mengharapkan inputRecords: 3, uniqueQueries: 2 dan reusedVideoIds: 1. Jauhkan prepared/batch.json dan prepared/input-map.json tidak berubah untuk menjalankan ini. Jika sudah ada, gunakan ulang untuk melanjutkan; gunakan folder baru untuk suatu dataset berbeda.

Siapkan panggilan API
node prepare.mjs

3. Pratilik dan kirimkan video unik

Uji coba kering menghitung kueri aktual, harga sekarang dan batas rekening. Tinjau itu, kemudian menyerahlah sekali. Sampel ini memiliki dua kueri yang bisa ditagih, meskipun input memiliki tiga catatan.

Simpan submission.json dan CLI direktori keadaan. Gunakan lagi ID yang sama dan masukan setelah gangguan. Sebuah run baru ID menciptakan pekerjaan baru; memeriksa sebuah pengajuan yang tidak pasti sebelum mencoba kembali.

Pratilik tanpa mengirimkan
flashdata batch submit --input prepared/batch.json --dry-run --json
Kirim setelah meninjau estimasi
flashdata batch submit --input prepared/batch.json --run-id video-metadata-001 --output submission.json --json

4. Mengumpulkan dan bergabung dengan hasil

Simpan collect.mjs di bawah ini, kemudian jalankan. Kolektor menunggu sampai dua menit per pekerjaan yang belum selesai, memastikan bahwa hasil milik video yang diminta, dan bergabung setiap hasil ke catatan asli. Jalankan satu kolektor pada suatu waktu.

Jalankan lagi untuk melanjutkan pekerjaan yang sama IDs. Ini mengembalikan hasil lokal yang sah dan tidak mengirimkan kueri baru. Kode keluar 1 berarti beberapa hasil masih membutuhkan perhatian; memeriksa mereka daripada mengirimkan kembali daftar.

Simpan collect.mjs

Buat collect.mjs dalam video yang sama dengan folder pengayaan submission.json dan prepared/. Salin kode lengkap di bawah ini dan simpan.

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;

Jalankan atau melanjutkan kolektor

Jalankan dari video-pengayaan setelah menyelamatkan collect.mjs. Simpan profil asli CLI dan direktori state.

Mengumpulkan atau melanjutkan
node collect.mjs

Diduga berkas

BerkasGunakan untuk
enriched.ndjsonSatu baris per catatan asli, termasuk duplikat dan kegagalan. Diimpor oleh record_id.
metadata.ndjsonSatu baris per query unik, dengan pekerjaan ID, hasil file dan kredit aktual. Hitung penggunaan di sini sekali.
results/*.jsonRespon sukses mentah ditambah pengikatan input/receipt yang disimpan.
failed-videos.jsonDikonfirmasi failed/cancelled pekerjaan untuk ditinjau. Tugas tunggu dan baca-galat disimpan di luar daftar ini.

5. Gunakan catatan diperkaya dalam aplikasi Anda

Simpan inspect.mjs dalam video-pengayaan, di samping enriched.ndjson, kemudian jalankan dari folder itu. Mengharapkan tiga catatan asli dan dua pertanyaan unik. Upsert menyelesaikan baris oleh record_id, pertahankan ruas masukan Anda, dan jaga baris-baris tidak lengkap yang terlihat dalam laporan impor Anda. Baca judul dan durasi dari metadata; gunakan video_id untuk links atau permintaan terjemahan nanti.

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);
Inspeksi catatan yang bergabung
node inspect.mjs

Lanjutkan dari butir yang membutuhkan perhatian

Simpan hasil dalam periode penahanan 24- jam mereka. Untuk menyegarkan ulang, gunakan folder snapshot baru dan jalankan ID hanya bila Anda berniat untuk membayar data segar; jaga agar record_id stabil dalam aplikasi Anda.

OutcomeAksi berikutnya
pending / processingJalankan kolektor lagi nanti. Menjaga pekerjaan yang sama IDs.
failed / cancelledUlasan failed-videos.json dan kesalahan pekerjaan. Benar penyebab sebelum sengaja meminta video itu lagi.
read_errorPerbaiki akses, masukan pengikatan atau hasil yang disimpan. Simpan file mentah untuk pemeriksaan; kesalahan baca tidak berarti permintaan baru diperlukan.
Hasil submission tidak diketahuiInspeksi lokal run dan History sebelum mengirimkan lagi.
Inspeksi batch yang disimpan
flashdata runs show video-metadata-001 --json