تخطَّ إلى المحتوى
AR
الحصول على مفتاح API
تصفح الوثائق

الأدلة

Enrich a list of YouTube videos

أضف البيانات الفوقية إلى قائمة مسرحية، وقائمة القراءة أو مجموعة بيانات التطبيق، مع الاحتفاظ بسجلك الأصلي 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 on 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، وغرفة لقطعتين دفع ووظيفتين في انتظار العمل. وإذا كان الوصول المؤقت لا يزال نشطا، يرجى المطالبة به أو استخدام وصفة الفرد الواحد. Review the dry-run estimate in step 3 before submitting.

الحساب الحر يقرأ
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"
  }
]

Save prepare.mjs

Create prepare.mjs beside videos.json in the video-enrichment folder. عُلِمْ الرمز الكامل أسفل إليه ويُوفّرُه.

يُثبت النص كل صف قبل إنشاء 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اركضي مرة Expect inputRecords: 3, uniqueQueries: 2 and reusedVideoIds: 1. أبقِ prepared/batch.json و prepared/input-map.json بدون تغيير على هذا الركض. وإذا تم إعدادها/وجودها بالفعل، أعيد استخدامها لاستئنافها؛ واستخدام ملف جديد لمجموعة بيانات مختلفة.

الجاهزة؛ لا API المكالمات
node prepare.mjs

3. استعراض وتقديم أشرطة الفيديو الفريدة

ويتحقق الجري الجاف من عدد الاستفسارات الفعلية، والحدود الحالية للتسعير والمحاسبة. قم بفحصه ثم تقدم مرة واحدة ولدى العينة استفساران قابلان للتعديل، على الرغم من أن للمدخل ثلاثة سجلات.

احتفظ بـ submission.json ودليل حالة CLI. أعد استخدام معرّف التنفيذ والمدخلات نفسها بعد الانقطاع. ينشئ المعرّف الجديد عملًا جديدًا؛ افحص الإرسال غير المؤكد قبل إعادة المحاولة.

استعراض أولي دون تقديم
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 أسفل، ثم تشغيله. وينتظر المجمع مدة تصل إلى دقيقتين لكل وظيفة غير مكتملة، ويتحقق من أن النتائج تعود إلى الفيديو المطلوب، وينضم إلى كل نتيجة في السجلات الأصلية. أدير جامعاً واحداً في كل مرة

شغّله مجددًا لاستئناف معرّفات المهام نفسها. يعيد استخدام النتائج المحلية المتحقق منها ولا يرسل استعلامات جديدة. يعني رمز الخروج 1 أن بعض النتائج لا تزال تحتاج انتباهًا؛ افحصها بدل إعادة إرسال القائمة.

Save collect.mjs

Create collect.mjs in that same video-enrichment folder, beside submission.json and 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

الملفات المتوقعة

Fileإستخدمه
enriched.ndjsonصف واحد لكل سجل أصلي، بما في ذلك الازدواج والفشل. استيراد من قبل record_id.
metadata.ndjsonصف لكل استعلام فريد، مع معرّف المهمة وملف النتيجة والرصيد الفعلي. احسب الاستخدام هنا مرة واحدة.
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 / cancelledReview failed-videos.json and the job error. تصحيح القضية قبل طلب ذلك الفيديو عمدا مرة أخرى.
read_errorاثبتي الدخول أو المدخلات الملزمة أو النتيجة المنقذة إبقاء الملف الخام للتفتيش؛ ولا يعني الخطأ القراء أن هناك حاجة إلى استفسار جديد.
النتيجة غير المعروفةافحص التشغيل المحلي وHistory قبل الإرسال مجددًا.
تحقق من الدفعة المنقذة
flashdata runs show video-metadata-001 --json