Перейти до вмісту
UK
Отримати ключ API
Переглянути документацію

Посібники

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

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

На цій сторінці

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

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

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

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

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

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

Інструменти та безкоштовна перевірка доступу
flashdata --version
node --version
flashdata auth status --json
mkdir video-enrichment
cd video-enrichment

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

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

Безкоштовні читання облікового запису
flashdata account balance --json
flashdata account limits --json

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

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

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

Зберегти prepare.mjs

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

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

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

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

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

Підготуйте · немає API дзвінки
node prepare.mjs

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

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

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

Перегляд без подання
flashdata batch submit --input prepared/batch.json --dry-run --json
Подати відгук про оцінку
flashdata batch submit --input prepared/batch.json --run-id video-metadata-001 --output submission.json --json

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

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

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

Зберегти collect.mjs

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

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;

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

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

Збір або резюме
node collect.mjs

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

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

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

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

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);
Опитування вступних записів
node inspect.mjs

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

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

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