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

الأدلة

تجهيز ملفات Bulk

جهز ملفاً للفيديو IDs واسترجع كل جزء من النتائج وتحقق من التغطية قبل استيراد البيانات إلى تطبيقك

في هذه الصفحة

من ملف ID إلى مجموعة بيانات مدققة

استخدام هذا التدفق من العمل في كتالوج فيديو، أو جمع البحوث، أو الاستيعاب. ويستخدم ملف واحد مصدر واحد وخيارات واحدة لكل مركب من طراز ID. ابدأي مع عينة البيانات الفوقية ذات الفينديو ثم ابدئي ملفك الخاص

الملفات التي ينتجها هذا تدفق العمل
video-ids.txt → مهمة Bulk → bulk-results.ndjson
  → audit/completed.ndjson       نتائج تطبيقك
  → audit/failed-video-ids.txt   حالات الفشل المؤكدة للمراجعة
  → audit/missing.ndjson        مدخلات لم تُسترجع نتائجها
  → audit/summary.json          أعداد المدخلات والنتائج

قبل أن تبدأ

(ب) تركيب مقر CLI واستخدام ملف موجود أو FLASHDATA_API_KEY مع إذن من youtube_metadata. (د) تأكيد data.accessVerified: true واستعراض الرصيد المتاح، والتسعير لطلبين والحدود الحالية. من أجل ملفك الخاص، استخدمه ID عد عند التحقق من التسعير كل عملية مجهزة ID هو سؤال منفصل، وليس تهمة واحدة مسطحة للملف.

استخدم Bash مع jq أو PowerShell 7 للخطوات 1–3. يستخدم تدقيق الاستيراد الاختياري في الخطوة 4 لغة Python 3.10+ ومكتبتها القياسية. لا يتطلب CLI نفسه Node.js أو Python.

حرية الدخول والفحص الحسابي
flashdata auth status --json
flashdata account balance --json
flashdata account pricing --source youtube_metadata --request-count 2
flashdata account limits

1. Prepare the IDs

شغّل في مجلد عمل جديد. استخدم نص UTF-8 بمعرّف فيديو من 11 محرفًا في كل سطر، وليس رابط YouTube. الحد الأقصى للملف 2 GiB. احذف الأسطر الفارغة والتكرارات: يرفض CLI المدخلات غير السليمة، وتُعالَج المعرّفات المكررة منفصلة.

Bash
# Run in a new working directory.
(
  set -euC
  printf '%s\n' 'jNQXAC9IVRw' 'dQw4w9WgXcQ' > video-ids.txt
)
cat video-ids.txt

2. افحص الملف

ينشئ CLI مهمة، ويرفع الملف، ويبدأ المعالجة، ويحفظ جميع أجزاء النتائج في ملف NDJSON واحد. استخدم مسار إخراج جديدًا. يحتفظ معرّف التنفيذ المحلي bulk-first بإيصال المهمة البعيدة للاستعادة.

Bash
flashdata bulk run --source youtube_metadata \
  --input video-ids.txt --run-id bulk-first \
  --output bulk-results.ndjson --timeout 30m --json

3. فحص النتائج

افتح الباب bulk-results.ndjson. وكل خط هو سجل JSON مع الرقم القياسي، و video_id، والوضع. وتتضمن الصفوف الناجحة صفائف النتائج؛ وتحتوي الصفوف الفاشلة على خطأ. انضموا لسجلات الإدخال بالرقم القياسي الصفري، وليس طلب الملفات. تستخدم قيادة Bash jq.

صف واحد ناجح - مثال مختصر
{"index":0,"video_id":"jNQXAC9IVRw","source":"youtube_metadata","status":"completed","results":[{"videoId":"jNQXAC9IVRw","title":"Example video title"}]}
Bash
# Bash + jq: read each record without loading the whole file.
jq -c '{index, video_id, status, title: .results[0].title, error}' bulk-results.ndjson

4. تغطية التحقق قبل الاستيراد

انقذوا audit-bulk.py أسفل. تشغيله ضد ملف المدخلات دون تغيير وجميع أجزاء النتائج المستردة. وهو يفحص كل فهرس، والفيديو ID، والمصدر، ويرفض الصفوف المزدوجة للنتائج، ويفصل الإخفاقات المؤكدة عن النتائج المفقودة. For another source, add --source SOURCE_ID.

Expect inputRows: 2, completed: 2, failed: 0, missing: 0 and allSucceeded: true for the successful sample. فقط الصفوف المكتملة تنتمي إلى استيراد نتيجة الطلب إبقاء موجز مراجعة الحسابات ونتائجه غير الناجحة إلى جانبها.

Save audit-bulk.py

Create audit-bulk.py beside video-ids.txt and bulk-results.ndjson in the working folder. عُلِمْ الرمز الكامل أسفل إليه ويُوفّرُه.

يقرأ السكربت الملفات سطرًا بسطر ويستخدم فهرس SQLite محليًا بدل تحميل مجموعة البيانات كاملة في الذاكرة. يتطلب ملف إدخال متحققًا منه لمعرّفات الفيديو. يستخدم كل تدقيق دليل إخراج جديدًا؛ وتظل الملفات الجزئية منفصلة حتى انتهاء التحليل.

audit-bulk.py
# audit-bulk.py — Python 3.10+, standard library only; no network requests.
import argparse
import json
import re
import sqlite3
import sys
from contextlib import ExitStack
from pathlib import Path

parser = argparse.ArgumentParser()
parser.add_argument('--input', required=True)
parser.add_argument('--results', required=True)
parser.add_argument('--out', required=True)
parser.add_argument('--source', default='youtube_metadata')
args = parser.parse_args()
out = Path(args.out)
try:
    out.mkdir()  # Keep any previous audit. Use a new directory for another attempt.
    with ExitStack() as stack:
        db = sqlite3.connect(out / 'index.sqlite')
        stack.callback(db.close)
        db.execute('CREATE TABLE inputs (idx INTEGER PRIMARY KEY, video_id TEXT, outcome TEXT)')
        count = 0
        with open(args.input, encoding='utf-8-sig') as inputs:
            for index, line in enumerate(inputs):
                video_id = line.strip()
                if not re.fullmatch(r'[A-Za-z0-9_-]{11}', video_id):
                    raise ValueError('Invalid ID on input line ' + str(index + 1))
                db.execute('INSERT INTO inputs VALUES (?, ?, NULL)', (index, video_id))
                count += 1
        if not count:
            raise ValueError('The input file is empty.')
        db.commit()
        files = {name: stack.enter_context(open(out / (name + '.part'), 'x', encoding='utf-8'))
                 for name in ['completed.ndjson', 'failed.ndjson', 'missing.ndjson', 'failed-video-ids.txt']}
        completed = failed = 0
        with open(args.results, encoding='utf-8-sig') as results:
            for line_number, line in enumerate(results, 1):
                if not line.strip():
                    continue
                row = json.loads(line)
                if not isinstance(row, dict) or type(row.get('index')) is not int:
                    raise ValueError('Invalid result index on line ' + str(line_number))
                expected = db.execute('SELECT video_id, outcome FROM inputs WHERE idx = ?',
                                      (row['index'],)).fetchone()
                if (not expected or row.get('video_id') != expected[0]
                        or row.get('source') != args.source or expected[1] is not None):
                    raise ValueError('Unknown, duplicate or mismatched result on line ' + str(line_number))
                status = row.get('status')
                if status not in ['completed', 'failed']:
                    raise ValueError('Unexpected item status on line ' + str(line_number))
                if status == 'completed':
                    if not isinstance(row.get('results'), list):
                        raise ValueError('Completed row is missing its results array.')
                    if args.source == 'youtube_metadata' and (len(row['results']) != 1
                            or not isinstance(row['results'][0], dict)
                            or row['results'][0].get('videoId') != expected[0]):
                        raise ValueError('Metadata does not belong to the requested video.')
                    completed += 1
                else:
                    failed += 1
                db.execute('UPDATE inputs SET outcome = ? WHERE idx = ?', (status, row['index']))
                files[status + '.ndjson'].write(json.dumps(row, ensure_ascii=False) + '\n')
        db.commit()
        missing = 0
        for index, video_id in db.execute('SELECT idx, video_id FROM inputs WHERE outcome IS NULL ORDER BY idx'):
            files['missing.ndjson'].write(json.dumps({'index': index, 'video_id': video_id,
                                                     'status': 'missing_result'}) + '\n')
            missing += 1
        for (video_id,) in db.execute("SELECT video_id FROM inputs WHERE outcome = 'failed' GROUP BY video_id ORDER BY MIN(idx)"):
            files['failed-video-ids.txt'].write(video_id + '\n')
        summary = {'source': args.source, 'inputRows': count, 'completed': completed,
                   'failed': failed, 'missing': missing, 'coverageComplete': missing == 0,
                   'allSucceeded': failed == 0 and missing == 0}
    for name in files:
        (out / (name + '.part')).rename(out / name)
    with open(out / 'summary.json', 'x', encoding='utf-8') as output:
        json.dump(summary, output, indent=2)
    print(json.dumps(summary, indent=2))
    sys.exit(0 if summary['allSucceeded'] else 2)
except Exception as error:
    print(str(error), file=sys.stderr)
    print('Audit not complete. Preserve this directory and inspect the inputs/results.', file=sys.stderr)
    sys.exit(1)

إجراء مراجعة الاستيراد

اهربوا من الملف الذي يحتوي على النص والمدخلات الأصلية والنتائج التي تم تحميلها. وتقرأ مراجعة الحسابات الملفات المحلية فقط.

Bash
python3 audit-bulk.py --input video-ids.txt --results bulk-results.ndjson --out audit

إكمال عمليات الاستيراد وإبقاء مراجعة الحسابات

الشاحن/الإشارةإستعملْه بهذه الطريقة
completed.ndjsonاربط النتائج بالملف الأصلي حسب index. استخدم video_id كمفتاح للفهرس؛ واحتفظ بهوية المهمة أو اللقطة عند تخزين سجل التحديث.
failed.ndjson + failed-video-ids.txtإعادة النظر في الأخطاء قبل إعادة فحصها عمدا IDs. وتُستثنى الأصناف الناجحة والمفقودة من القائمة الفاشلة - ID.
missing.ndjsonاسترجاع جميع أجزاء النتائج من الوظيفة الحالية ثم مراجعة الملف المسترد في دليل جديد الناتج المفقود ليس سؤالاً مثبتاً
summary.jsoncoverageComplete تحقق من أن كل مدخل له نتيجة allSucceeded كما لا يتطلب أي فيديو فاشل. وتخرج مراجعة الحسابات من 2 إما بسبب الفشل أو في الصفوف المفقودة.
Exit 1 / no summary.jsonبيانات مُجهّزة أو مُضللة: فحص الملفات المُنقذة. لا تنشر المراجعة الجزئية كمجموعة بيانات كاملة.

إذا فشل بعض الفيديو

قد تحتوي مهمة Bulk مكتملة على فيديوهات فاشلة. يحفظ CLI هذه الصفوف أيضًا، ثم ينتهي بالقيمة bulk_item_failures. افحص أخطاءها قبل تقرير إعادة محاولة المعرّفات المعنية؛ لا تعِد إرسال الملف بالكامل تلقائيًا.

تظهر فقط سجلات غير ناجحة jq
jq -c 'select(.status != "completed") | {index, video_id, status, error}' bulk-results.ndjson

التقدم المحرز والقدرات

اقرأ المهمة المحفوظة أثناء عمل الأمر الأصلي. يغلّف CLI الحالة ضمن data؛ ويغلّفها HTTP المباشر ضمن job. افحص مع تأخير وتراجع تدريجي، واحترم Retry-After عند 429. انتهاء مهلة محلية أو إغلاق الطرفية لا يلغي العمل البعيد.

الميداناقرأه كما هو
input.scannedBytes / input.bytesإمسحوا التقدم، لم يستكملوا الاستفسارات أو وسائل الإعلام المحملة.
input.completeوقد قرأت جميع المدخلات؛ وقد لا تزال الاستفسارات وتعبئة النتائج جارية.
counts.accepted / completed / failedالمعرّفات المرسلة والفيديوهات الناجحة والفاشلة. المتبقي = المقبول − المكتمل − الفاشل.
counts.invalid / resultsInvalid input lines / records packaged so far. ويمكن أن تقبل شركة HTTP الملفات التي تحتوي على خطوط غير صحيحة؛ وتتحقق شركة CLI من المدخلات قبل تحميلها.
deliveryتقديم بيانات العملاء: uploadedParts, retryCount, storageType و customerStorage. مُختلفة عن كلّ مُشغّل إعلاميّ.
Bash
(
set -eu
BULK_ID=$(flashdata runs show bulk-first --json | jq -er '.data.remoteId')
flashdata bulk get "$BULK_ID" --json
)

معرفة متى الانتظار أو العمل

Bulk تقدم تدريجياً في حسابك maxPendingJobs القدرة، متقاسمة مع الوظائف الأخرى. ولا يكفي من الائتمانات أو الاشتراك الناشط يمكن أن يوقف العمل. تحقق pauseReason قبل الإستئناف

الدولةالإجراء التالي:
awaiting_uploadقم بتحميل الملف ثم ابدأ العمل الحالي
running / finalizingانتظر. ويمكن أن يشمل وضع الصيغة النهائية الاستفسارات غير المنجزة، والتغليف، والتخزين.
pausedResolve pauseReason and resume the same job.
completedتحميل جميع أجزاء النتائج وتفقد الصفوف الفاشلة
failed / cancelledInspect job.error و الإيصال المنقذ الأعمال المقبولة قد لا تزال finish; No completed manifest is published.

Resume an interrupted work flow

بعد انتهاء مهلة محلية أو انقطاع تنزيل النتائج، استعد bulk-first. يقرأ ذلك المهمة البعيدة الموجودة ولا يعيد إرسال مجموعة البيانات. استخدم اسم ملف إخراج جديدًا. قد يترك خطأ partial_result ملفًا محليًا جزئيًا؛ أبقه منفصلًا عن النتيجة المستعادة.

استخدم نفس ملف CLI ودليل الولاية في كل مكان. من أجل ملف مسمّى، إضافة --profile نيم إلى كل أمر

الحالةFix
awaiting_uploadruns recover لا يعيد تشغيل تحميل أو بداية. تحقق من الإنقاذ ID- حالة تحميل وملف أصلي قبل أن يستمر بشكل صريح.
pausedResolve the reported cause, then use bulk resume with the Save ID. ولا يستأنف الاسترداد العمل المدفوع تلقائيا.
401 / 403(ج) إعادة الوصول إلى الحساب والمصدر المقدمين. إعادة استخدام نفس الوظيفة بعد التوثيق
409 / 410409: النتائج ليست جاهزة. 410: إنتهت النتائج المخزنة؛ استخدام نسختك المحفوظة.
الشحنات المعجلة URLتأكدي من أن العمل القديم لم يبدأ قبل أن يخلق وظيفة جديدة والرسالة غير المؤكدة هي سبب لقراءة ما انقذته من الـ ID أولاً.
إسترجعْ الركضَ المنقذَ
flashdata runs show bulk-first --json
flashdata runs recover bulk-first --output recovered-results.ndjson --timeout 30m --json

وقف أو استئناف العمل

استبدل BULK_ID بالمعرّف من runs show bulk-first. يوقف الإيقاف المؤقت الإرسالات الجديدة وتجميع النتائج؛ وتستمر الاستعلامات المقبولة. عالج pauseReason قبل الاستئناف. لتغيير الخيارات أو بيانات اعتماد التخزين، حدّث المهمة الموجودة عبر Bulk API.

وقف
flashdata bulk pause BULK_ID --json
الاسترجاع بعد إصلاح القضية
flashdata bulk resume BULK_ID --json

الغى بشكل دائم

فقط ألغي الموعد عندما تنوي التخلي عن العمل والإلغاء لا يلغي الاستفسارات المقبولة أو يسترد العمل المنجز. لا تزال الكونتات تتغير، ولا تنشر أي بيان مكتمل. -الوقف قابل للعكس

إلغاء الوظيفة المختاره
flashdata bulk cancel BULK_ID --json

استرجاع كل جزء من النتائج

وبالنسبة لوظيفة مكتملة قائمة، تتبع شركة CLI بيانها وتحتفظ بكل جزء من النتائج في ملف واحد من طراز NDJSON. (ب) استخدام مسار جديد للنواتج وإدارة مراجعة الواردات في الملف المشترك. وتصف نتائج التحميل وسائط الإعلام التي تم تسليمها؛ فهي ليست من نوع إم بي 4 أو منافذ صوتية.

جلب جميع الأجزاء من وظيفة قائمة
flashdata bulk results BULK_ID --output saved-results.ndjson --timeout 30m --json

سلموا إلى مخزنكم

احفظوا أوراق اعتمادكم كمقدمة storage.json في ملف العمل قبل إدارة هذه القيادة استخدام حقول مقدمي الخدمات المرتبطة أدناه؛ الاحتفاظ بالملف الخاص. The CLI' --storage-config يقرأ هذا JSON الملفات والاختيارات result_storage من أجل البيانات أو التخزين لوسائط الإعلام. --options أيضاً يَأْخذُ طريقَ ملفِ، لَيسَ خطّ JSON.

تشغيل مع تركيبة التخزين المنقذة

إضافة تخزين إلى تدفق عمل البيانات الفوقية
flashdata bulk run --source youtube_metadata --input video-ids.txt --storage-config storage.json --run-id bulk-with-storage --output stored-results.ndjson --timeout 30m --json