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

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

مرجع كانوني: https://flashdata.dev/ar/docs/guides/media-delivery-pipeline
Reviewed: 2026-11-05 by FlashData

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

## ما ستبنيه

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

### Pipeline and Save records

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

- [اختيار الصوت أو الفيديو أو مقطع](https://flashdata.dev/ar/docs/guides/youtube-download-guide/reference.md#formats)

<a id="requirements"></a>

### قبل أن تبدأ

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

#### Python

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

##### Install the Python dependency

```bash
python --version
flashdata --version
python -m pip install boto3
```


#### Bash / Node.js

Install Bash, jq, Node.js 22+ و AWS CLI v2. على Windowsاركض Bash القيادة في Git Bash. اثبتوا النواة S3 توقيع الطرود في الخطوة 6.


- [الحمولة الأولى](https://flashdata.dev/ar/docs/guides/download-video-recipe/reference.md)
- [مجهزة خاصة من طراز storage.json](https://flashdata.dev/ar/docs/guides/cli-automation/reference.md#storage)
- [نبذات منقذة](https://flashdata.dev/ar/docs/guides/cli-automation/reference.md#profiles)
- [بوتو 3 - وثائق تفويض الأسلحة النووية](https://docs.aws.amazon.com/boto3/latest/guide/credentials.html)

<a id="environment"></a>

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

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

#### Python

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

##### pipeline.json

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


#### Bash

##### pipeline.env

```bash
# pipeline.env — edit these paths for your existing installation.
export FLASHDATA_STATE_DIR='/absolute/path/to/flashdata-state'
export FLASHDATA_STORAGE_CONFIG='/absolute/path/to/private/storage.json'
export FLASHDATA_PROFILE='default'
# Use the saved profile for every process.
unset FLASHDATA_API_KEY
```



<a id="design"></a>

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

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

### item.json

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


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

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

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


<a id="request-script"></a>

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

#### Python

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

##### pipeline.py

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


#### Bash

أنشئ request-media.sh في المجلد نفسه الذي يحتوي pipeline.env وitem.json. انسخ الكود الكامل أدناه إلى الملف واحفظه.

##### request-media.sh

```bash
#!/usr/bin/env bash
set -euo pipefail
umask 077
cd -- "$(dirname -- "$0")"
. ./pipeline.env
: "${FLASHDATA_STATE_DIR:?Set your existing absolute CLI state directory}"
: "${FLASHDATA_STORAGE_CONFIG:?Set the absolute path to private storage.json}"
action=${1:-dry-run}
[[ "$action" == dry-run || "$action" == submit ]] || exit 2
run_id=$(jq -er '.runId | select(type == "string" and length > 0)' item.json)
request() {
  jq -en --slurpfile item item.json --slurpfile storage "$FLASHDATA_STORAGE_CONFIG" '
    $item[0] as $i | $storage[0] as $s
    | if $i.request.source != "youtube_download"
        or $s.storage_type != "s3" or $s.storage_url != $i.destination.bucket
        or $s.region != $i.destination.region
      then error("Check item.json and the S3 destination in storage.json")
      else $i.request | .params.storage = ($s + {object_prefix: $i.destination.prefix}) end'
}
args=(query --input - --mode async --run-id "$run_id"
  --profile "${FLASHDATA_PROFILE:-default}" --state-dir "$FLASHDATA_STATE_DIR"
  --json --non-interactive)
if [[ "$action" == dry-run ]]; then
  request | flashdata "${args[@]}" --dry-run
else
  mkdir -p attempts
  attempt=$(mktemp -d attempts/submit.XXXXXX)
  if ! request | flashdata "${args[@]}" --output "$attempt/submission.json" \
    > "$attempt/receipt.json" 2> "$attempt/error.json"; then
    cat "$attempt/error.json" >&2
    printf 'Keep %s; inspect the saved run before retrying.\n' "$attempt" >&2
    exit 1
  fi
  jq '{runId, cached, data}' "$attempt/receipt.json"
  printf 'Saved receipt: %s/submission.json\n' "$attempt"
fi
```



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

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

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

#### Python

##### التحقق من البيئة والحساب

```bash
python pipeline.py check
```


#### Bash

##### التحقق من البيئة والحساب

```bash
set -euo pipefail
. ./pipeline.env
: "${FLASHDATA_STATE_DIR:?Set your existing absolute CLI state directory}"
: "${FLASHDATA_STORAGE_CONFIG:?Set the absolute path to private storage.json}"
flashdata --version
jq --version
node --version
aws --version
flashdata auth status --profile "${FLASHDATA_PROFILE:-default}" \
  --state-dir "$FLASHDATA_STATE_DIR" --json --non-interactive |
  jq -e 'if .ok and .data.accessVerified
    and (.data.identity.identity.recurringAllowed == true)
    and (.data.identity.permittedSources | index("youtube_download") != null)
    then {accountId: .data.identity.identity.accountId,
          permittedSources: .data.identity.permittedSources}
    else error("Owner access with youtube_download is required.") end'
flashdata account balance --profile "${FLASHDATA_PROFILE:-default}" \
  --state-dir "$FLASHDATA_STATE_DIR" --json --non-interactive
flashdata account pricing --source youtube_download --request-count 1 \
  --profile "${FLASHDATA_PROFILE:-default}" --state-dir "$FLASHDATA_STATE_DIR" --json --non-interactive
flashdata account limits --profile "${FLASHDATA_PROFILE:-default}" \
  --state-dir "$FLASHDATA_STATE_DIR" --json --non-interactive
```


- [العودة إلى مصدر السيناريو](https://flashdata.dev/ar/docs/guides/media-delivery-pipeline/reference.md#request-script)

<a id="dry-run"></a>

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

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

#### Python

##### جافة مجانية

```bash
python pipeline.py dry-run
```


#### Bash

##### جافة مجانية

```bash
set -euo pipefail
bash request-media.sh dry-run | jq -e '.ok and .data.dryRun'
```



<a id="dispatch"></a>

## 3. Submit and retain the job ID

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

### Python

#### اذكر مرة

```bash
python pipeline.py submit
```

#### Inspect local state · no new query

```bash
python pipeline.py inspect
```


### Bash

#### اذكر مرة

```bash
bash request-media.sh submit
```

#### Inspect local state · no new query

```bash
set -euo pipefail
. ./pipeline.env
RUN_ID=$(jq -er '.runId' item.json)
flashdata runs show "$RUN_ID" --profile "${FLASHDATA_PROFILE:-default}" \
  --state-dir "$FLASHDATA_STATE_DIR" --json --non-interactive |
  jq '{runId, status: .data.status, jobId: .data.remoteId,
       errorCode: .data.errorCode, candidateJobIds: .data.candidateRemoteIds}'
```



<a id="job-state"></a>

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

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

- [التاريخ](https://flashdata.dev/app/jobs)
- [Recover uncertain submissions](https://flashdata.dev/ar/docs/guides/agent-recovery/reference.md)

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

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

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


<a id="recovery-script"></a>

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

#### Python

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

##### استرداد الوظيفة القائمة؛ عدم تقديم أي طلب جديد

```bash
python pipeline.py recover
```


#### Bash

أنشئ أولًا recover-media.sh بجانب item.json والصق الكود أدناه. احفظ الملف، ثم شغّل أمر الاستعادة الذي يليه.

##### recover-media.sh

```bash
#!/usr/bin/env bash
set -euo pipefail
umask 077
cd -- "$(dirname -- "$0")"
. ./pipeline.env
: "${FLASHDATA_STATE_DIR:?Set your existing absolute CLI state directory}"
RUN_ID=$(jq -er '.runId' item.json)
mkdir -p attempts
DELIVERY_DIR=$(mktemp -d attempts/recover.XXXXXX)
if ! flashdata runs recover "$RUN_ID" --timeout 10m \
  --profile "${FLASHDATA_PROFILE:-default}" --state-dir "$FLASHDATA_STATE_DIR" \
  --output "$DELIVERY_DIR/delivery.json" --json --non-interactive \
  > "$DELIVERY_DIR/receipt.json" 2> "$DELIVERY_DIR/error.json"; then
  cat "$DELIVERY_DIR/error.json" >&2
  printf 'Keep %s; recover the same run after resolving the error.\n' "$DELIVERY_DIR" >&2
  exit 1
fi
flashdata runs show "$RUN_ID" --profile "${FLASHDATA_PROFILE:-default}" \
  --state-dir "$FLASHDATA_STATE_DIR" --json --non-interactive > "$DELIVERY_DIR/run.json"
jq -e '.source == "youtube_download" and .status == "done"' \
  "$DELIVERY_DIR/delivery.json" >/dev/null
printf '%s\n' "$DELIVERY_DIR"
```

##### استرداد الوظيفة القائمة؛ عدم تقديم أي طلب جديد

```bash
set -euo pipefail
DELIVERY_DIR=$(bash recover-media.sh)
printf 'Delivery files: %s\n' "$DELIVERY_DIR"
```



<a id="delivery-record"></a>

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

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

#### Python

##### سجل التسليم

```bash
python pipeline.py delivery
```


#### Bash

##### سجل التسليم

```bash
jq '{status, file: .results[0], usage}' "$DELIVERY_DIR/delivery.json"
```



<a id="verify"></a>

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

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


<a id="verify-script"></a>

### حفظ نص التحقق

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

#### Python

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

##### verify-media.py

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


#### Node.js

أنشئ verify-media.mjs بجانب item.json وانسخ إليه الكود الكامل أدناه.

##### verify-media.mjs

```javascript
import { readFile, mkdir, writeFile } from 'node:fs/promises';
import { createReadStream } from 'node:fs';
import { createHash } from 'node:crypto';
import { execFileSync } from 'node:child_process';
import { resolve, join } from 'node:path';

try {
  const directory = process.argv[2];
  if (!directory) throw new Error('Pass the directory printed by the recovery step.');
  const readJson = async path => JSON.parse(await readFile(path, 'utf8'));
  const item = await readJson('item.json');
  const run = await readJson(join(directory, 'run.json'));
  const raw = await readFile(join(directory, 'delivery.json'));
  const delivery = JSON.parse(raw);
  if (!run.ok || run.data?.id !== item.runId || run.data?.status !== 'succeeded'
      || !run.data?.remoteId || delivery.source !== 'youtube_download'
      || delivery.status !== 'done' || delivery.results?.length !== 1) {
    throw new Error('Inspect the saved run and completed delivery before verifying.');
  }
  const file = delivery.results[0];
  const { bucket, region, prefix } = item.destination;
  const input = run.data.input;
  const storage = input?.params?.storage;
  if (input?.source !== 'youtube_download' || input.video_id !== item.request.video_id
      || ['download_type', 'video_quality', 'output_format'].some(
        key => input.params?.[key] !== item.request.params[key])
      || storage?.storage_url !== bucket || storage.region !== region
      || storage.object_prefix !== prefix) {
    throw new Error('item.json changed after submission. Inspect the original run.');
  }
  const url = new URL(file.file_url);
  const hosts = [bucket + '.s3.' + region + '.amazonaws.com', bucket + '.s3.amazonaws.com'];
  const objectKey = decodeURIComponent(url.pathname.slice(1));
  if (url.protocol !== 'https:' || !hosts.includes(url.host) || url.username
      || url.password || url.search || url.hash || !prefix
      || !objectKey.startsWith(prefix + '/')) {
    throw new Error('The delivery does not match the planned Amazon S3 destination.');
  }
  if (!Number.isSafeInteger(file.file_size) || file.file_size <= 0
      || !/^[a-f0-9]{32}$/i.test(file.md5 ?? '')) {
    throw new Error('A positive file_size and MD5 are required. Keep the manifest.');
  }
  const verification = join(directory, 'verified');
  await mkdir(verification, { mode: 0o700 }); // Existing attempt: stop without overwriting.
  const localFile = join(verification, 'media.mp4');
  let metadata;
  try {
    metadata = JSON.parse(execFileSync('aws', ['s3api', 'get-object',
      '--bucket', bucket, '--key', objectKey, '--region', region,
      '--output', 'json', '--no-cli-pager', '--no-cli-auto-prompt', localFile],
      { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }));
  } catch {
    throw new Error('S3 read failed. Keep this attempt and check the AWS read identity.');
  }
  let bytes = 0;
  const hash = createHash('md5');
  for await (const chunk of createReadStream(localFile)) {
    bytes += chunk.length;
    hash.update(chunk);
  }
  const md5 = hash.digest('hex');
  if (bytes !== file.file_size || md5 !== file.md5.toLowerCase()) {
    throw new Error('Byte count or MD5 mismatch. Keep the file; do not mark it ready.');
  }
  const ready = { runId: item.runId, jobId: run.data.remoteId,
    videoId: item.request.video_id, bucket, region, objectKey, storageVersionId: metadata.VersionId ?? null,
    bytes, md5, verifiedAt: new Date().toISOString(), localFile: resolve(localFile),
    deliverySha256: createHash('sha256').update(raw).digest('hex'), usage: delivery.usage };
  const readyFile = join(verification, 'ready.json');
  await writeFile(readyFile, JSON.stringify(ready, null, 2), { flag: 'wx', mode: 0o600 });
  console.log('Delivery verified:', readyFile);
} catch (error) {
  console.error(error instanceof Error ? error.message : 'Inspect the saved attempt.');
  process.exitCode = 1;
}
```


- [Boto3 GetObject](https://docs.aws.amazon.com/boto3/latest/reference/services/s3/client/get_object.html)
- ["أطلقوا النار"](https://docs.aws.amazon.com/cli/latest/reference/s3api/get-object.html)

<a id="verify-file"></a>

### إجراء التحقق

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

#### Python

##### تصحيح وقراءة سجل التسليم

```bash
python verify-media.py
```


#### Node.js + AWS CLI

##### تصحيح وقراءة سجل التسليم

```bash
set -euo pipefail
: "${DELIVERY_DIR:?Set the directory printed by recovery}"
node verify-media.mjs "$DELIVERY_DIR"
jq '{runId, jobId, bucket, region, objectKey, bytes, md5, storageVersionId}' \
  "$DELIVERY_DIR/verified/ready.json"
```



<a id="ready"></a>

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

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

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

- [الاحتفاظ بالرواتب وتخزين وسائط الإعلام](https://flashdata.dev/ar/docs/guides/save-results/reference.md#media)

<a id="serve"></a>

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

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


<a id="link-script"></a>

### احفظ نص الوصلات

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

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

#### Python

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

##### create-download-link.py

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


#### Node.js

وضع مجموعات التوقيع في ملف البند، ثم توفير المصدر أدناه كما يلي: create-download-link.mjs في ذلك الملف

##### تركيب موكّل توقيع S3

```bash
test -f package.json || npm init -y
npm install @aws-sdk/client-s3 @aws-sdk/s3-request-presigner
```

##### create-download-link.mjs

```javascript
// create-download-link.mjs — run in your backend with its AWS read identity.
import { readFile } from 'node:fs/promises';
import { GetObjectCommand, S3Client } from '@aws-sdk/client-s3';
import { getSignedUrl } from '@aws-sdk/s3-request-presigner';

try {
  const path = process.argv[2];
  if (!path) throw new Error('Pass the verified ready.json file.');
  const ready = JSON.parse(await readFile(path, 'utf8'));
  if (['bucket', 'region', 'objectKey', 'verifiedAt'].some(
    key => typeof ready[key] !== 'string' || !ready[key])) {
    throw new Error('Use the ready.json produced by the verification step.');
  }
  // Load this record from your own store after authorizing the requesting user.
  const version = ready.storageVersionId;
  const command = new GetObjectCommand({
    Bucket: ready.bucket, Key: ready.objectKey,
    ...(version && version !== 'null' ? { VersionId: version } : {}),
  });
  const client = new S3Client({ region: ready.region });
  const url = await getSignedUrl(client, command, { expiresIn: 300 });
  console.log(JSON.stringify({ url, expiresInSeconds: 300 }, null, 2));
} catch (error) {
  console.error(error instanceof Error ? error.message : 'Could not create a download link.');
  process.exitCode = 1;
}
```


- [Boto3 presigned URL example](https://docs.aws.amazon.com/boto3/latest/guide/s3-presigned-urls.html)
- [AWS JavaScript presigned URL example](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/javascript_s3_code_examples.html)
- [S3 access and URL expiry](https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-presigned-url.html)

<a id="download-link"></a>

### إعادة الرابط إلى المستعمل المأذون به

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

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

#### Python

##### إنشاء وصلة مدتها خمس دقائق

```bash
python create-download-link.py
```


#### Node.js

##### إنشاء وصلة مدتها خمس دقائق

```bash
(
set -euo pipefail
umask 077
: "${DELIVERY_DIR:?Set the directory printed by recovery}"
# Keep the signed link in a private file; do not log it or paste it into chat.
set -C
node create-download-link.mjs "$DELIVERY_DIR/verified/ready.json" \
  > "$DELIVERY_DIR/verified/access.json"
)
```



<a id="restart"></a>

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

| الحالة | الإجراء التالي: |
| --- | --- |
| الوظيفة المقبولة/الانتظار المحلي | تستعيد عمليات 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. لقد انقذ التفتيش العمل قبل إعادة النظر في الطلب |


<a id="scale"></a>

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

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

- [حدود الحساب](https://flashdata.dev/ar/docs/guides/usage-and-limits/reference.md)
- [وثائق تفويض الموظفين والحاويات](https://flashdata.dev/ar/docs/guides/production-deployment/reference.md)
- [الجدول الزمني للمهام المتكررة](https://flashdata.dev/ar/docs/guides/recurring-tasks/reference.md)
