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

الأدلة

بناء خط أنابيب توصيل وسائط الإعلام

تحميل إم بي 4 إلى تخزين خاص S3، استئناف بعد إعادة تشغيل وإعطاء طلبك الوصول إلى الملف المتحقق منه.

في هذه الصفحة

ما ستبنيه

وينتقل أحد البنود الدائمة من شريط فيديو ID إلى ملف مختص بقراءة الطلبات. أبقي كل مرحلة على القرص حتى تستمر عملية جديدة من آخر نتيجة مؤكدة

Pipeline and Save records
item.json
  → إرسال مرة واحدة       → تنفيذ محفوظ + معرّف المهمة
  → استعادة المهمة       → delivery.json
  → التحقق من بايتات S3  → media.mp4 + ready.json
  → تفويض مستخدم التطبيق → رابط تنزيل قصير الصلاحية

قبل أن تبدأ

اختر طريقاً واحداً على سبيل المثال لكل الخطوات الست استخدما معاً تركيبة FlashData CLI مع ملف المالك المنقذ youtube_download إذن خاص S3 storage.json من أجل تحميلها، وهوية (أو دبليو إس) يمكنها قراءة الجسم المسلّم.

استخدم Python 3.10+ في بيئة Python لديك. تستدعي السكربتات CLI للاحتفاظ بسجل التنفيذ، وتستخدم Boto3 لقراءة S3 وتوقيع الروابط. لا تحتاج إلى Bash أو jq أو Node.js أو AWS CLI. شغّل الأوامر أدناه باستخدام python، أو python3 إذا كان ذلك اسم المفسّر لديك.

Install the Python dependency
python --version
flashdata --version
python -m pip install boto3

انقذوا أماكن العمل

إنشاء ملف خاص خارج نطاق السيطرة على المصدر انقذوا أماكنكم المختاره وحرروا المسارات المطلقه و اسم الملامح كل عملية تستخدم حساباً منقذاً و تعمل في المجلة أوراق اعتماد التخزين تبقى في القطاع الخاص storage.json. أجري عملية واحدة لكل بند في وقت واحد.

انقذوا pipeline.json. On Windows, forward-slash paths such as C:/private/flashdata-state work in JSON.

pipeline.json
{
  "stateDir": "/absolute/path/to/flashdata-state",
  "storageConfig": "/absolute/path/to/private/storage.json",
  "profile": "default"
}

1. وفر بنداً دائماً

انقذوا item.json في ذلك الملف يستعاض عن مقصد الفيديو وزكس كيزوك (S3)؛ ويطالب هذا المثال بواحدة من طراز MP4 تصل إلى 720p. احتفظ به runId من أجل المناقصات ويحتاج الناتج المخطط له إلى مكافئة جديدة من طراز runId وإلى معالجات أولية للجسم.

item.json
{
  "runId": "media:clip-001:720p:v1",
  "request": {
    "source": "youtube_download",
    "video_id": "jNQXAC9IVRw",
    "params": {
      "download_type": "audio_video",
      "video_quality": "<=720",
      "output_format": "mp4"
    }
  },
  "destination": {
    "bucket": "your-media-bucket",
    "region": "us-east-1",
    "prefix": "media/clip-001-v1"
  }
}

2. احفظ النص وتحقق من الدخول

اصنعي الملف بالأسفل قبل إجراء الشيكات وهو يصادق على وجهة S3 ويحتفظ باستلام لكل محاولة لتقديم الطلبات.

إنشاء خط الأنابيب

أنشئ pipeline.py في المجلد نفسه الذي يحتوي pipeline.json وitem.json. انسخ الكود الكامل أدناه إلى الملف واحفظه. ستعيد استخدامه للفحوص والإرسال والاستعادة في الخطوات 2–4.

pipeline.py
# pipeline.py — Python 3.10+ and the FlashData CLI on PATH.
import argparse
import json
import os
import subprocess
import sys
import tempfile
from pathlib import Path

ROOT = Path(__file__).resolve().parent


def read_json(path):
    return json.loads(Path(path).read_text(encoding='utf-8-sig'))


def delivery_directory():
    # Recovery updates this pointer only after the delivery is saved successfully.
    return ROOT / (ROOT / 'delivery-dir.txt').read_text(encoding='utf-8').strip()


def main(action):
    os.umask(0o077)
    settings = read_json(ROOT / 'pipeline.json')
    for name in ['stateDir', 'storageConfig']:
        if not Path(settings[name]).is_absolute():
            raise ValueError('Set an absolute path for ' + name)
    item = read_json(ROOT / 'item.json')
    run_id = item['runId']
    env = dict(os.environ)
    env.pop('FLASHDATA_API_KEY', None)  # Reuse the saved owner profile.
    flags = ['--profile', settings['profile'], '--state-dir', settings['stateDir'],
             '--json', '--non-interactive']

    def cli(*args, payload=None, attempt=None):
        result = subprocess.run(['flashdata', *args, *flags], cwd=ROOT, env=env,
                                input=json.dumps(payload) if payload is not None else None,
                                capture_output=True, text=True, encoding='utf-8')
        if attempt:
            (attempt / 'receipt.json').write_text(result.stdout, encoding='utf-8')
            (attempt / 'error.json').write_text(result.stderr, encoding='utf-8')
        if result.returncode:
            if attempt:
                raise RuntimeError('Keep ' + str(attempt) + '; inspect its error and saved run.')
            raise RuntimeError(result.stderr.strip() or 'FlashData command failed.')
        response = json.loads(result.stdout)
        if not response.get('ok'):
            raise RuntimeError('Inspect the CLI response before continuing.')
        return response

    def new_attempt(stage):
        attempts = ROOT / 'attempts'
        attempts.mkdir(exist_ok=True)
        return Path(tempfile.mkdtemp(prefix=stage + '.', dir=attempts))

    if action == 'check':
        access = cli('auth', 'status')['data']
        identity = access['identity']
        if (not access.get('accessVerified')
                or identity['identity'].get('recurringAllowed') is not True
                or 'youtube_download' not in identity.get('permittedSources', [])):
            raise ValueError('Owner access with youtube_download is required.')
        print(json.dumps({'accountId': identity['identity']['accountId'],
                          'permittedSources': identity['permittedSources']}, indent=2))
        for args in [('account', 'balance'),
                     ('account', 'pricing', '--source', 'youtube_download', '--request-count', '1'),
                     ('account', 'limits')]:
            print(json.dumps(cli(*args)['data'], indent=2))
    elif action in ['dry-run', 'submit']:
        storage = read_json(settings['storageConfig'])
        destination = item['destination']
        if (item['request']['source'] != 'youtube_download'
                or storage.get('storage_type') != 's3'
                or storage.get('storage_url') != destination['bucket']
                or storage.get('region') != destination['region']):
            raise ValueError('Check item.json and the S3 destination in storage.json.')
        request = item['request']
        request['params']['storage'] = {**storage, 'object_prefix': destination['prefix']}
        args = ['query', '--input', '-', '--mode', 'async', '--run-id', run_id]
        if action == 'dry-run':
            response = cli(*args, '--dry-run', payload=request)
            if response['data'].get('dryRun') is not True:
                raise ValueError('Expected a dry-run result.')
            print(json.dumps({'ok': True, 'dryRun': True}))
        else:
            attempt = new_attempt('submit')
            response = cli(*args, '--output', str(attempt / 'submission.json'),
                           payload=request, attempt=attempt)
            print(json.dumps({'runId': run_id, 'cached': response.get('cached'),
                              'receipt': str(attempt / 'submission.json')}, indent=2))
    elif action == 'inspect':
        run = cli('runs', 'show', run_id)['data']
        print(json.dumps({'runId': run_id, 'status': run['status'], 'jobId': run.get('remoteId'),
                          'errorCode': run.get('errorCode'),
                          'candidateJobIds': run.get('candidateRemoteIds')}, indent=2))
    elif action == 'recover':
        attempt = new_attempt('recover')
        cli('runs', 'recover', run_id, '--timeout', '10m',
            '--output', str(attempt / 'delivery.json'), attempt=attempt)
        run = cli('runs', 'show', run_id)
        (attempt / 'run.json').write_text(json.dumps(run, indent=2), encoding='utf-8')
        delivery = read_json(attempt / 'delivery.json')
        if delivery.get('source') != 'youtube_download' or delivery.get('status') != 'done':
            raise ValueError('Inspect the saved delivery before verifying.')
        pointer = ROOT / 'delivery-dir.next'
        pointer.write_text(attempt.relative_to(ROOT).as_posix(), encoding='utf-8')
        pointer.replace(ROOT / 'delivery-dir.txt')
        print('Delivery files:', attempt)
    elif action == 'delivery':
        delivery = read_json(delivery_directory() / 'delivery.json')
        print(json.dumps({'status': delivery['status'], 'file': delivery['results'][0],
                          'usage': delivery.get('usage')}, indent=2))


if __name__ == '__main__':
    sys.stdout.reconfigure(encoding='utf-8')
    sys.stderr.reconfigure(encoding='utf-8')
    parser = argparse.ArgumentParser()
    parser.add_argument('action', choices=['check', 'dry-run', 'submit', 'inspect', 'recover', 'delivery'])
    try:
        main(parser.parse_args().action)
    except (OSError, ValueError, KeyError, RuntimeError) as error:
        print(str(error), file=sys.stderr)
        sys.exit(1)

تحقق من حسابك المنقذ

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

التحقق من البيئة والحساب
python pipeline.py check

تم التحقق بدون تحميل

بعد انقاذ المساعده اركضوا Pythonprints ok: true and dryRun: true; Bashprints true. ويصدق هذا على المدخلات والوصول دون تقديم أعمال إعلامية أو الاحتفاظ بأرصدة.

جافة مجانية
python pipeline.py dry-run

3. Submit and retain the job ID

يرسل هذا تنزيلًا مدفوعًا واحدًا في الخلفية. توقّع status: accepted وjobId في التنفيذ المحلي. احتفظ بالملف الشخصي ودليل الحالة وitem.json للاستعادة. لا تصبح الوسائط جاهزة إلا بعد الخطوة 5.

اذكر مرة
python pipeline.py submit
Inspect local state · no new query
python pipeline.py inspect

إذا تم إنقاذ الهارب بالفعل أو عدم اليقين

CLI stateالإجراء
accepted + jobIdإسترجع هذه الركضة في الخطوة 4. حافظ على العمل ID إذا توقفت العملية.
succeededRecover/export إستجابته المنقذة، ثم التحقق من التخزين. لا تقدمي بندا جديدا.
نتيجة غير معروفة/لم تتأكد وظيفة IDاحتفظ بالتنفيذ والإيصال والخطأ. افحص History أو المعرّفات المحتملة قبل تقرير إرسال آخر.

4. استرداد سجل التسليم

اهرب من ملف البند في أي محطة طرفية جديدة وينتظر الاسترداد الوظيفة الأصلية ويطبع دليلاً يحتوي على delivery.json و run.json و الإيصالات. وتتوقف فترة زمنية محددة من طراز 10 عن الانتظار على الصعيد المحلي؛ وتكرار التعافي لاستئناف نفس الوظيفة.

إستعادة الوظيفة المنقذة

Reuse pipeline.py Save in step 2. ولا حاجة إلى نص إضافي.

استرداد الوظيفة القائمة؛ عدم تقديم أي طلب جديد
python pipeline.py recover

فحص الجسم المسلّم

توقّع رابط كائن S3 واحدًا وحجم ملف موجبًا وبصمة MD5. تحتاج الكائنات الخاصة إلى هوية AWS لديك بصلاحية القراءة. يحفظ Python دليل النجاح في delivery-dir.txt للسكربتات التالية. يحتفظ Bash بالمتغير DELIVERY_DIR؛ وفي طرفية جديدة، اضبطه على الدليل المطبوع.

سجل التسليم
python pipeline.py delivery

5. تحقق من قبل قبل وضع علامات جاهزة

المتحقق يفحص المدخلات الأصلية S3 دلو و ما قبل الفرز يتدفق الجسم الخاص إلى القرص و يقارن عده و حسب MD5. فقط ملفات مطابقة تنتج verified/ready.json. Python reads delivery-dir.txt; استخدامات العقيدة DELIVERY_DIR. ولم يقدم أي منهما FlashData سؤال.

حفظ نص التحقق

ويعالج هذا التحقق المعياري Amazon S3 الجسم URLs. وفيما يتعلق بالنقاط النهائية المعتادة أو بمقدم آخر، يستخدم جسمه الموثَّق عليه ليقرأ ويحتفظ بذات الوجهة، والحسابات الثانوية، وفحص المواد.

أنشئ verify-media.py بجانب pipeline.py وانسخ الكود الكامل أدناه إليه. احفظ الملفين في مجلد العنصر.

verify-media.py
# verify-media.py — uses Boto3's configured AWS read identity.
import hashlib
import json
import os
import re
import sys
from contextlib import closing
from datetime import datetime, timezone
from urllib.parse import unquote, urlsplit

import boto3
from pipeline import ROOT, delivery_directory, read_json


def main():
    os.umask(0o077)
    directory = delivery_directory()
    item = read_json(ROOT / 'item.json')
    saved = read_json(directory / 'run.json')
    raw = (directory / 'delivery.json').read_bytes()
    delivery = json.loads(raw)
    run = saved.get('data', {})
    if (not saved.get('ok') or run.get('id') != item['runId']
            or run.get('status') != 'succeeded' or not run.get('remoteId')
            or delivery.get('source') != 'youtube_download' or delivery.get('status') != 'done'
            or not isinstance(delivery.get('results'), list) or len(delivery['results']) != 1):
        raise ValueError('Inspect the saved run and completed delivery before verifying.')
    file = delivery['results'][0]
    bucket, region, prefix = (item['destination'][key] for key in ['bucket', 'region', 'prefix'])
    original = run.get('input', {})
    storage = original.get('params', {}).get('storage', {})
    if (original.get('source') != 'youtube_download' or original.get('video_id') != item['request']['video_id']
            or any(original.get('params', {}).get(key) != item['request']['params'][key]
                   for key in ['download_type', 'video_quality', 'output_format'])
            or storage.get('storage_url') != bucket or storage.get('region') != region
            or storage.get('object_prefix') != prefix):
        raise ValueError('item.json changed after submission. Inspect the original run.')
    url = urlsplit(file['file_url'])
    hosts = [bucket + '.s3.' + region + '.amazonaws.com', bucket + '.s3.amazonaws.com']
    key = unquote(url.path[1:], errors='strict')
    if (url.scheme != 'https' or url.netloc not in hosts or url.query or url.fragment
            or not prefix or not key.startswith(prefix + '/')):
        raise ValueError('The delivery does not match the planned Amazon S3 destination.')
    if (type(file.get('file_size')) is not int or file['file_size'] <= 0
            or not re.fullmatch(r'[a-fA-F0-9]{32}', file.get('md5', ''))):
        raise ValueError('A positive file_size and MD5 are required. Keep the manifest.')
    verification = directory / 'verified'
    verification.mkdir(mode=0o700)  # Stop if an earlier verification already exists.
    local_file = verification / 'media.mp4'
    s3 = boto3.client('s3', region_name=region)
    response = s3.get_object(Bucket=bucket, Key=key)
    size, digest = 0, hashlib.md5(usedforsecurity=False)
    with closing(response['Body']) as stream, local_file.open('xb') as output:
        while chunk := stream.read(1024 * 1024):
            output.write(chunk)
            size += len(chunk)
            digest.update(chunk)
    md5 = digest.hexdigest()
    if size != file['file_size'] or md5 != file['md5'].lower():
        raise ValueError('Byte count or MD5 mismatch. Keep the file; do not mark it ready.')
    ready = {'runId': item['runId'], 'jobId': run['remoteId'], 'videoId': item['request']['video_id'],
             'bucket': bucket, 'region': region, 'objectKey': key,
             'storageVersionId': response.get('VersionId'), 'bytes': size, 'md5': md5,
             'verifiedAt': datetime.now(timezone.utc).isoformat(), 'localFile': str(local_file.resolve()),
             'deliverySha256': hashlib.sha256(raw).hexdigest(), 'usage': delivery.get('usage')}
    with (verification / 'ready.json').open('x', encoding='utf-8') as output:
        json.dump(ready, output, indent=2)
    print('Delivery verified:', verification / 'ready.json')
    print(json.dumps(ready, indent=2))


if __name__ == '__main__':
    sys.stdout.reconfigure(encoding='utf-8')
    sys.stderr.reconfigure(encoding='utf-8')
    try:
        main()
    except Exception as error:
        print(str(error), file=sys.stderr)
        sys.exit(1)

إجراء التحقق

بعد انقاذ النص اديره من ملف البند

تصحيح وقراءة سجل التسليم
python verify-media.py

سلّمْ ready.json إلى طلبِكَ

تم التحقق من التوصيل المتوقع وسجل يحتوي على الرقم run/job IDs، ودلو، والمنطقة، ومفتاح الجسم، وحجم التحقق، و MD5. هذا هو سجل طلبكم، الذي أنشأه النص. )أ( محفوظة مع delivery.json والبند الأصلي؛ وهي على قيد الحياة نافذة الاحتفاظ بنتيجة API.

بالنسبة للتصنيف أو الفهرسة أو غير ذلك من التجهيزات، تمرر عملية التحقق localFile لعمالك بالنسبة لتحميل مستعملين، استمر بالخطوة 6.

6. أعطِ تطبيقَكَ يُسيطرُ

وتأذن للمستعمل في مساندتكم وتنظرون إلى سجل المستعمل الجاهز في مخزنكم الخاص. ثمّ يَجْعلُ a قصير الأمد S3 تحميل URL. استخدم المقصد المنقذ؛ ولا تقبل دلو أو مفتاح الجسم الذي يوفره المصفح.

وتستخدم شركة SDK بطاقة الهوية الجاهزة لجهاز الإنذار المبكر. لم يتم إرسال أي استفسار من شركة FlashData.

يشير URL إلى نسخة الكائن المتحقق منها عندما يوفر S3 معرّف نسخة. دون معرّف نسخة، لا تغيّر مفتاح الإخراج بعد التحقق. تحتاج هوية قراءة نسخة محددة إلى s3:GetObjectVersion؛ وتحتاج القراءة دون نسخة إلى s3:GetObject.

أنشئ create-download-link.py بجانب pipeline.py وانسخ الكود الكامل أدناه إليه. يستخدم حزمة Boto3 المثبتة في البداية.

create-download-link.py
# create-download-link.py — run in your backend after authorizing the user.
import json
import os
import sys

import boto3
from botocore.config import Config
from pipeline import delivery_directory, read_json


def main():
    os.umask(0o077)
    # In an app, load this user's verified ready record from your own store.
    directory = delivery_directory() / 'verified'
    ready = read_json(directory / 'ready.json')
    if any(not isinstance(ready.get(key), str) or not ready[key]
           for key in ['bucket', 'region', 'objectKey', 'verifiedAt']):
        raise ValueError('Use the ready.json produced by the verification step.')
    destination = directory / 'access.json'
    if destination.exists():
        raise FileExistsError('Keep the existing access.json or choose a new output filename.')
    params = {'Bucket': ready['bucket'], 'Key': ready['objectKey']}
    version = ready.get('storageVersionId')
    if version and version != 'null':
        params['VersionId'] = version
    s3 = boto3.client('s3', region_name=ready['region'], config=Config(signature_version='s3v4'))
    url = s3.generate_presigned_url('get_object', Params=params, ExpiresIn=300, HttpMethod='GET')
    with destination.open('x', encoding='utf-8') as output:
        json.dump({'url': url, 'expiresInSeconds': 300}, output, indent=2)
    # Do not log the signed URL; return it only to the authorized user.
    print('Access record saved:', destination)


if __name__ == '__main__':
    sys.stdout.reconfigure(encoding='utf-8')
    sys.stderr.reconfigure(encoding='utf-8')
    try:
        main()
    except Exception as error:
        print(str(error), file=sys.stderr)
        sys.exit(1)

Expect a private access.json containing url and expiresInSeconds: 300. ظهرك يعود فقط URL للمستخدم المرخص ويمكن لأي شخص يحمله أن يحمّل الملف لمدة تصل إلى خمس دقائق؛ ويجوز أن ينتهي قبل ذلك بوثائق التفويض بالتوقيع.

إنشاء صلة جديدة من السجل الجاهز المنقذ عندما يطلب المستخدم القادم الدخول أبقِ مفتاح الجسمَ ونسخةَ في قاعدةِ بياناتِكَ، بدلاً مِنْ تَخْزّزُ الصاروخِ URL كa عنوانِ الأصولِ. ويتوقف هذا المثال المحلي إذا كان يوجد بالفعل access.json.

إنشاء وصلة مدتها خمس دقائق
python create-download-link.py

إستئناف من آخر مرحلة مؤكدة

الحالةالإجراء التالي:
الوظيفة المقبولة/الانتظار المحليتستعيد عمليات runs recover المتكررة العمل باستخدام runId نفسه في دليل محاولة جديد.
S3 access denied or interrupted readأصلح هوية القراءة في AWS أو الاتصال. استعد إلى دليل جديد وتحقق مجددًا؛ واحتفظ بالملف الجزئي السابق.
/ MD5/ destination mismatchتوقف. قارن manifest ونسخة الكائن والوجهة المخطط لها قبل استخدام الوسائط.
تم التحقق منها بالفعلاقرأها ready.jsonأو يفتش التحقق غير المكتمل النص لن يكتبه
تنزيل الطلب URLالإذن بالدخول مرة أخرى وتوقيع الـ object/version. لا تتقدموا بآخرين FlashData تحميل.
run_id_input_conflictتغيّر الطلب. استعد التنفيذ الأصلي؛ واستخدم runId جديدًا فقط لمخرج جديد مقصود.
401 / 403 / 402 / 429(ج) تحديد الوصول أو التصاريح أو التوازن؛ اتباع نظام Retry-After. لقد انقذ التفتيش العمل قبل إعادة النظر في الطلب

تطبيق نفس المراحل على الاستفسار

  1. ابدأ ببند واحد في الرحلة اقرأ الحدود الحالية قبل زيادة تطابق الطلبات.
  2. أبقوا واحدًا ثابتًا runId عن كل واحد video/output نسخة، مع وجهة مُحددة. تخزين الحساب، والعمل ID والنتيجة النهائية في قاعدة بيانات التطبيقات الخاصة بك.
  3. الفارس CLI دليل الولاية عبر عملية إعادة صياغة. وتحتاج الأجهزة المنفصلة إلى تنسيق تطبيقات مشتركة؛ ولا تقوم مجلة محلية بتجديد أدلة حكومية مستقلة.
  4. الاستخدام ready.json كعملية تسليم إلى عملية تجهيز المجرى الاحتفاظ بأشياء فاشلة منفردة حتى يتم إعادة استخدام عمليات التسليم الناجحة.