# Збагатити список відео YouTube

Додайте метадані до списку відтворення, список читання або дані програми, зберігаючи ваш оригінальний запис IDs та кожного результату.

Канонічне посилання: https://flashdata.dev/uk/docs/guides/enrich-youtube-videos
Переглянуто: 2026-11-05 від FlashData

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

## Від ваших записів до збагачених даних

Старт з трьома записами, що відносяться до двох відео. Виконайте різні відео один раз, а потім приєднайте метадані до всіх трьох записів. Цей робочий процес використовує невеликий запит Batch і зберігає неуспішні елементи, видимі.

| Вихідні поля | Мета |
| --- | --- |
| record_id · input | Ваш оригінальний запис і поля, в оригінальному порядку. |
| video_id · query_index · job_id | Зайдіть кожен запис до запиту, що його виготовили. |
| status · metadata · result_file | Закінчений результат, або явного результату pending/failed/read-error. |

- [Відео тільки](https://flashdata.dev/uk/docs/guides/video-metadata-recipe/reference.md)
- [Процес більшого файлу](https://flashdata.dev/uk/docs/guides/bulk/reference.md)
- [Batch проти Bulk](https://flashdata.dev/uk/docs/reference/batch-and-bulk/reference.md#choose)

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

## 1. Перевірити інструменти та доступ

Використовуйте FlashData CLI v1.2.1 на PATH і Node.js 22+. Запуск у новій папці з наявним обліковим записом власника та дозволом youtube_metadata. Bash і PowerShell використовують однакові команди нижче.

Зберігати цей самий обліковий запис і профіль по всій території. Для названого профілю встановлюється FLASHDATA_PROFILE в цьому терміналі, тому він також використовує його. Агенти можуть навантажувати FLASHDATA_API_KEY з свого секретного магазину.

### Інструменти та безкоштовна перевірка доступу

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

- [Встановити CLI](https://flashdata.dev/uk/docs/guides/flashdata-cli/reference.md#install)
- [Налаштування ключа власника](https://flashdata.dev/uk/docs/guides/cli-automation/reference.md#profiles)

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

### Перевірити баланс і ємність

Підтвердити доступ власника, дозвіл youtube_metadata і номер для двох партійних предметів і закінчуючи роботами. Якщо тимчасовий доступ є ще активним, застосуйте його або використовуйте один-відео рецепт. Оцініть сухий кошторис на сходинку 3 перед подачею.

#### Безкоштовні читання облікового запису

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


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

## 2. Підготовка записів введення

Збережіть це як videos.json. Заміна значень з власним записом IDs і 11-character YouTube відео IDs. Додаткові поля, що залишаються в локальній картопуванні, і не надсилаються на FlashData. Допускається повторне відео IDs; record_id повинна бути унікальною.

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

### Зберегти prepare.mjs

Створіть prepare.mjs beside videos.json у папці відеознімку. Скопіюйте загальний код нижче в ньому і заощаджуйте його.

Скрипт перевіряє кожен рядок перед створенням prepared/. Увімкнено відео IDs для цього запиту метаданих при збереженні ваших оригінальних записів та замовлення.

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

### Створіть список запитів локально

Після збереження prepare.mjs, запустіть його один раз. Випробувано inputRecords: 3, uniqueQueries: 2 і reusedVideoIds: 1. Зареєструватися prepared/batch.json і prepared/input-map.json безперешкодно для цього запуску. Якщо готовий/ вже існує, повторно його змусити відновити; використовуйте нову папку для різних даних.

#### Підготуйте · немає API дзвінки

```bash
node prepare.mjs
```


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

## 3. Перегляд та подання унікальних відео

Сухий курс перевіряє фактичний обсяг запитів, діючі ліміти цін та рахунків. Рекомендувати його, потім подати один раз. Випробування має два вексельні запити, хоча введення має три записи.

Зареєструватися submission.json і CLI Державний каталог. Запобігти тому ж запуску ID і введення після переривання. Новий запуск ID створює нову роботу; перевірте неоднозначну подачу перед спрацьовуванням.

### Перегляд без подання

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

### Подати відгук про оцінку

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

- [Batch договір запиту](https://flashdata.dev/uk/docs/reference/batch-and-bulk/reference.md#batch)

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

## 4. Збір і вступ до результатів

Заощаджуйте collect.mjs нижче, потім запустіть його. Збірник очікує до двох хвилин на незакінчену роботу, виявляє, що результати належать до запитуваного відео, і приєднується до кожного результату до оригінальних записів. Запуск одного колектора в часі.

Запустіть його знову, щоб відновити цю ж роботу IDs. Відповідає чинні результати та надішлемо нові запити. Код ЄДРПОУ 1 означає, що деякі результати все ще потребують уваги; перевірте їх замість перепідпису списку.


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

### Зберегти collect.mjs

Створюйте collect.mjs в тому ж папці відеознімків, біля submission.json і prepared/. Скопіюйте загальний код нижче в ньому і заощаджуйте його.

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

### Запустити або відновити колектор

Запуск відеознімку після збереження collect.mjs. Зберігайте оригінальний профіль CLI та каталог стану.

#### Збір або резюме

```bash
node collect.mjs
```


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

### Очікувані файли

| Головна | Використовуйте його для |
| --- | --- |
| enriched.ndjson | Один ряд за оригінальний запис, включаючи дублікати і збої. Імпорт від record_id. |
| metadata.ndjson | Один ряд за унікальну запит, з роботою ID, результат файл і фактичні кредити. Використовуйте, користуючись послугами. |
| results/*.json | Сирі успішні відповіді плюс збережені зв'язки input/receipt. |
| failed-videos.json | Підтверджено роботу failed/cancelled для огляду. З цього переліку зберігаються роботи з поточними та читацькими організаціями. |


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

## 5. Використовуйте збагачені записи в додатку

Заощаджуйте inspect.mjs у відео-знімку, знайдіть enriched.ndjson, потім запустіть його з цієї папки. Визначте три оригінальні записи і два унікальні запити. Вставте завершені ряди record_id, зберігайте поля введення, і зберігайте неповторні ряди, видимі у звіті про імпорт. Читання назви та тривалості з метаданих; використання video_id для посилань або запиту пізнішого підпису.

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

### Опитування вступних записів

```bash
node inspect.mjs
```

- [Виберіть підписки для відео](https://flashdata.dev/uk/docs/guides/youtube-data-guide/reference.md#captions)

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

## Продовжити з пункту, який потребує уваги

Заощаджуйте результати в період затримки 24-години. Для відновлення оновлень використовуйте нову папку знімків і запустіть ID тільки тоді, коли ви плануєте платити за свіжі дані; зберігайте record_id стабільний у вашій заявці.

| Про нас | Попередня дія |
| --- | --- |
| pending / processing | Запуск колектора знову пізніше. Займіть ті ж самі роботи IDs. |
| failed / cancelled | Огляд failed-videos.json і помилка роботи. Виправте причину перед навмисно запитуючи, що відео знову. |
| read_error | Фіксувати доступ, вводити обов'язковий або збережений результат. Зберігайте сирий файл для перевірки; похибка прочитання не означає, що новий запит буде потрібно. |
| Невідома інформація | Оглянути місцевий хід і History перед подачею знову. |

### Перевірка збереженої партії

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

- [Відновити невизначену роботу](https://flashdata.dev/uk/docs/guides/agent-recovery/reference.md)
- [Процес більшого файлу з Bulk](https://flashdata.dev/uk/docs/guides/bulk/reference.md)
- [Заощаджувати та повторно використовувати результати](https://flashdata.dev/uk/docs/guides/save-results/reference.md)
