# Sebesar daftar video YouTube

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

Referensi kanonikal: https://flashdata.dev/id/docs/guides/enrich-youtube-videos
Diulang: 2026-11-05 oleh FlashData

<a id="prepare"></a>

## 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 keluaran | Tujuan |
| --- | --- |
| record_id · input | Catatan asli dan bidang, dalam urutan asli. |
| video_id · query_index · job_id | Lacak setiap rekaman ke query yang diproduksi itu. |
| status · metadata · result_file | Hasil yang selesai, atau hasil pending/failed/read-error. |

- [Hanya satu video](https://flashdata.dev/id/docs/guides/video-metadata-recipe/reference.md)
- [Proses berkas yang lebih besar](https://flashdata.dev/id/docs/guides/bulk/reference.md)
- [Batch versus Bulk](https://flashdata.dev/id/docs/reference/batch-and-bulk/reference.md#choose)

<a id="authenticate"></a>

## 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

```bash
flashdata --version
node --version
flashdata auth status --json
mkdir video-enrichment
cd video-enrichment
```

- [Pasang CLI](https://flashdata.dev/id/docs/guides/flashdata-cli/reference.md#install)
- [Konfigurasikan suatu kunci pemilik](https://flashdata.dev/id/docs/guides/cli-automation/reference.md#profiles)

<a id="access-check"></a>

### 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

```bash
flashdata account balance --json
flashdata account limits --json
```


<a id="input"></a>

## 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

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


<a id="prepare-script"></a>

### 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

```javascript
// 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));
```


<a id="prepared"></a>

### 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

```bash
node prepare.mjs
```


<a id="submit"></a>

## 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

```bash
flashdata batch submit --input prepared/batch.json --dry-run --json
```

### Kirim setelah meninjau estimasi

```bash
flashdata batch submit --input prepared/batch.json --run-id video-metadata-001 --output submission.json --json
```

- [Batch kontrak permintaan](https://flashdata.dev/id/docs/reference/batch-and-bulk/reference.md#batch)

<a id="finish"></a>

## 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.


<a id="collector"></a>

### 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

```javascript
// 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;
```


<a id="run-collector"></a>

### Jalankan atau melanjutkan kolektor

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

#### Mengumpulkan atau melanjutkan

```bash
node collect.mjs
```


<a id="output"></a>

### Diduga berkas

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


<a id="use-dataset"></a>

## 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

```javascript
// 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

```bash
node inspect.mjs
```

- [Pilih judul untuk sebuah video](https://flashdata.dev/id/docs/guides/youtube-data-guide/reference.md#captions)

<a id="recover"></a>

## 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.

| Outcome | Aksi berikutnya |
| --- | --- |
| pending / processing | Jalankan kolektor lagi nanti. Menjaga pekerjaan yang sama IDs. |
| failed / cancelled | Ulasan failed-videos.json dan kesalahan pekerjaan. Benar penyebab sebelum sengaja meminta video itu lagi. |
| read_error | Perbaiki akses, masukan pengikatan atau hasil yang disimpan. Simpan file mentah untuk pemeriksaan; kesalahan baca tidak berarti permintaan baru diperlukan. |
| Hasil submission tidak diketahui | Inspeksi lokal run dan History sebelum mengirimkan lagi. |

### Inspeksi batch yang disimpan

```bash
flashdata runs show video-metadata-001 --json
```

- [Pekerjaan recover tidak pasti](https://flashdata.dev/id/docs/guides/agent-recovery/reference.md)
- [Proses berkas yang lebih besar dengan Bulk](https://flashdata.dev/id/docs/guides/bulk/reference.md)
- [Simpan dan gunakan ulang hasil](https://flashdata.dev/id/docs/guides/save-results/reference.md)
