# Erstellen Sie eine Media Delivery Pipeline

Laden Sie eine MP4 auf den privaten S3-Speicher herunter, nehmen Sie nach einem Neustart wieder auf und geben Sie Ihrer Anwendung Zugriff auf die verifizierte Datei.

Kanonische Referenz: https://flashdata.dev/de/docs/guides/media-delivery-pipeline
Test: 2026-11-05 von FlashData

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

## Was du bauen wirst

Ein langlebiges Element bewegt sich von einem Video ID zu einer anwendungsbereiten Datei. Behalten Sie jede Phase auf der Festplatte, damit ein neuer Prozess ab dem letzten bestätigten Ergebnis fortgesetzt werden kann.

### Pipeline und gespeicherte Aufzeichnungen

```text
item.json
  → einmal einreichen → gespeicherter Lauf + Job ID
  → Job wiederherstellen → delivery.json
  → S3 Bytes überprüfen → media.mp4 + ready.json
  → App-Benutzer autorisieren → Kurzlebiger Download URL
```

- [Wählen Sie Audio, Video oder einen Clip](https://flashdata.dev/de/docs/guides/youtube-download-guide/reference.md#formats)

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

### Bevor Sie anfangen

Wählen Sie einen Beispielpfad für alle sechs Schritte. Beide verwenden ein installiertes FlashData CLI mit einem gespeicherten Besitzerprofil und einer youtube_download-Berechtigung, ein privates S3 storage.json für Uploads und eine AWS-Identität, die das gelieferte Objekt lesen kann.

#### Python

Verwenden Sie Python 3.10+ in Ihrer Python-Umgebung. Die Skripte rufen das CLI auf, um sein laufendes Journal zu bewahren, und Boto3, um S3 zu lesen und Links zu signieren. Bash, jq, Node.js und AWS CLI werden nicht benötigt. Führen Sie die Befehle unten mit Python oder Python3 aus, wenn dies Ihr Interpretername ist.

##### Installieren Sie die Python Abhängigkeit

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


#### Bash / Node.js

Installieren Sie Bash, jq, Node.js 22+ und AWS CLI v2. Führen Sie auf Windows Bash Befehle in Git Bash aus. Installieren Sie die Node S3 Signierungspakete in Schritt 6.


- [Erster Download](https://flashdata.dev/de/docs/guides/download-video-recipe/reference.md)
- [Privates storage.json Setup](https://flashdata.dev/de/docs/guides/cli-automation/reference.md#storage)
- [Gespeicherte Profile](https://flashdata.dev/de/docs/guides/cli-automation/reference.md#profiles)
- [Boto3 AWS-Zugangsdaten](https://docs.aws.amazon.com/boto3/latest/guide/credentials.html)

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

### Speichern Sie die Runtime-Einstellungen

Erstellen Sie einen privaten Artikelordner außerhalb des Quellsteuerelements. Speichern Sie die Einstellungen für den gewählten Pfad und bearbeiten Sie die absoluten Pfade und den Profilnamen. Jeder Prozess verwendet dieses gespeicherte Konto und führt Journal aus. Speicheranmeldeinformationen bleiben im privaten storage.json. Führen Sie einen Prozess pro Element auf einmal aus.

#### Python

Speichern Sie pipeline.json. Auf Windows funktionieren Vorwärts-Slash-Pfade wie C:/private/flashdata-state 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. Speichern Sie einen langlebigen Artikel

Speichern Sie item.json in diesem Ordner. Ersetzen Sie das Video und S3 Ziel; dieses Beispiel fordert eine MP4 bei bis zu 720p. Behalten Sie seine runId für Wiederholungen. Eine andere geplante Ausgabe benötigt ein neues runId und ein Objektpräfix.

### 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. Speichern Sie das Skript und überprüfen Sie den Zugriff

Erstellen Sie die unten stehende Datei, bevor Sie die Prüfungen ausführen. Es validiert das S3-Ziel und behält eine Quittung für jeden Einreichungsversuch.


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

### Erstellen Sie das Pipeline-Skript

#### Python

Erstellen Sie pipeline.py im gleichen Ordner wie pipeline.json und item.json. Kopieren Sie den vollständigen Code unten in diese Datei und speichern Sie ihn. Sie werden es für Überprüfungen, Einreichung und Wiederherstellung in den Schritten 2–4 wiederverwenden.

##### 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

Erstellen Sie request-media.sh im gleichen Ordner wie pipeline.env und item.json. Kopieren Sie den vollständigen Code unten in diese Datei und speichern Sie ihn.

##### 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>

### Überprüfen Sie Ihr gespeichertes Konto

Führen Sie diesen kostenlosen Check aus dem Artikelordner aus, nachdem Sie das Skript gespeichert haben. Fehlender Besitzerzugriff oder youtube_download-Berechtigung stoppt die Überprüfung. Bestätigen Sie das Konto ID, Saldo, TB-Rate und Limits. Die endgültige Gebühr hängt von den hochgeladenen Bytes ab.

#### Python

##### Überprüfen Sie die Umgebung und das Konto

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


#### Bash

##### Überprüfen Sie die Umgebung und das Konto

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


- [Zurück zur Skriptquelle](https://flashdata.dev/de/docs/guides/media-delivery-pipeline/reference.md#request-script)

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

### Validieren ohne Download

Nachdem Sie den Helfer gerettet haben, führen Sie seinen Trockenlauf durch. Python druckt ok: true und dryRun: true; Bash druckt true. Dies validiert Eingabe und Zugriff, ohne Medienarbeit einzureichen oder Credits zu reservieren.

#### Python

##### Freier Trockenlauf

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


#### Bash

##### Freier Trockenlauf

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



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

## 3. Senden und behalten Sie den Job ID

Dies sendet einen kostenpflichtigen Hintergrund-Download. Erwarten Sie status: accepted und ein jobId im lokalen Lauf. Behalten Sie das Profil, das Zustandsverzeichnis und item.json für die Wiederherstellung. Das Medium ist erst nach Schritt 5 bereit.

### Python

#### Einmal einreichen

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

#### Lokalstaat inspizieren · keine neue Abfrage

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


### Bash

#### Einmal einreichen

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

#### Lokalstaat inspizieren · keine neue Abfrage

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

### Wenn der Lauf bereits gespeichert oder unsicher ist

| CLI Zustand | Aktion |
| --- | --- |
| accepted + jobId | Stellen Sie diesen Lauf in Schritt 4 wieder her. Behalten Sie den Job ID, wenn der Prozess beendet wird. |
| succeeded | Recover/export seine gespeicherte Antwort, dann überprüfen Speicher. Geben Sie keinen neuen Artikel ein. |
| Unbekanntes Ergebnis / kein bestätigter Job ID | Behalten Sie den Lauf, den Empfang und den Fehler. Überprüfen Sie History oder den Kandidaten IDs, bevor Sie sich für eine andere Einreichung entscheiden. |

- [Anfrageverlauf](https://flashdata.dev/app/jobs)
- [Wiedereinziehung unsicherer Eingaben](https://flashdata.dev/de/docs/guides/agent-recovery/reference.md)

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

## 4. Wiederherstellung des Lieferprotokolls

Führen Sie aus dem Elementordner in einem neuen Terminal aus. Die Wiederherstellung wartet auf den ursprünglichen Auftrag und druckt ein Verzeichnis mit delivery.json, run.json und Quittungen. Ein 10-Minuten-Timeout stoppt das lokale Warten; Wiederholen Sie die Wiederherstellung, um den gleichen Job wieder aufzunehmen.


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

### Den gespeicherten Job wieder aufnehmen

#### Python

Wiederverwenden von pipeline.py gespeichert in Schritt 2. Es wird kein zusätzliches Skript benötigt.

##### Wiederherstellen des bestehenden Arbeitsplatzes · keine neue Einreichung

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


#### Bash

Erstellen Sie zunächst recover-media.sh neben item.json und fügen Sie den Code unten ein. Speichern Sie die Datei und führen Sie dann den Wiederherstellungsbefehl darunter aus.

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

##### Wiederherstellen des bestehenden Arbeitsplatzes · keine neue Einreichung

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



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

### Überprüfen Sie das gelieferte Objekt

Erwarten Sie ein S3-Objekt URL, eine positive Dateigröße und ein MD5. Private Objekte benötigen Ihre AWS-Identität. Python speichert das erfolgreiche Verzeichnis in delivery-dir.txt für spätere Skripte. Bash behält DELIVERY_DIR; in einem neuen Terminal, legen Sie es auf das gedruckte Verzeichnis.

#### Python

##### Lieferprotokoll

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


#### Bash

##### Lieferprotokoll

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



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

## 5. Bytes überprüfen, bevor Sie markieren bereit

Der Verifier überprüft die ursprüngliche Eingabe, S3 Bucket und Präfix, streamt das private Objekt auf die Festplatte und vergleicht seine Bytezahl und MD5. Nur passende Dateien produzieren verified/ready.json. Python liest delivery-dir.txt; Node verwendet DELIVERY_DIR. Keine der beiden sendet eine FlashData-Abfrage.


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

### Speichern Sie das Verifizierungsskript

Dieser Verifier verarbeitet das Standard-Amazon S3-Objekt URLs. Verwenden Sie für benutzerdefinierte Endpunkte oder einen anderen Anbieter das authentifizierte Objekt read und behalten Sie die gleichen Ziel-, Byte-Count- und Checksum-Checks bei.

#### Python

Erstellen Sie verify-media.py neben pipeline.py und kopieren Sie den kompletten Code unten hinein. Speichern Sie beide Dateien im Elementordner.

##### 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

Erstellen Sie verify-media.mjs neben item.json und kopieren Sie den kompletten Code unten hinein.

##### 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)
- [AWS GetObject Befehl](https://docs.aws.amazon.com/cli/latest/reference/s3api/get-object.html)

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

### Durchführung der Überprüfung

Nachdem Sie das Skript gespeichert haben, führen Sie es aus dem Elementordner aus.

#### Python

##### Überprüfen und lesen Sie den Handoff Record

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


#### Node.js + AWS CLI

##### Überprüfen und lesen Sie den Handoff Record

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

### Geben Sie ready.json an Ihre Anwendung weiter

Erwarten Sie die verifizierte Lieferung und einen Datensatz mit run/job IDs, Bucket, Region, Objektschlüssel, verifizierter Größe und MD5. Dies ist der datensatz ihrer anwendung, der durch das skript erstellt wurde. Archivieren Sie es mit delivery.json und dem Originalelement; es überlebt das Aufbewahrungsfenster des API-Ergebnisses.

Für die Transkription, Indexierung oder andere Verarbeitung übergeben Sie das verifizierte localFile an Ihren Mitarbeiter. Für einen benutzerseitigen Download fahren Sie mit Schritt 6 fort.

- [Ergebnisspeicherung und Medienspeicherung](https://flashdata.dev/de/docs/guides/save-results/reference.md#media)

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

## 6. Geben Sie Ihrer Anwendung kontrollierten Zugriff

Autorisieren Sie in Ihrem Backend den Benutzer und schauen Sie sich die fertigen Datensätze dieses Benutzers in Ihrem eigenen Shop an. Erstellen Sie dann einen kurzlebigen S3-Download URL. Verwenden Sie das gespeicherte Ziel; akzeptieren Sie keinen Bucket- oder Objektschlüssel, der vom Browser geliefert wird.


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

### Speichern Sie das Download-Link-Script

Das SDK verwendet die AWS-Leseidentität des Backends. Es wird keine FlashData-Abfrage gesendet.

Die URL benennt die verifizierte Objektversion, wenn die S3-Versionierung eine enthält. Ohne eine Version ID, halten Sie jeden Ausgabeschlüssel nach der Verifizierung unveränderlich. Eine Identität, die eine bestimmte Version liest, benötigt s3:GetObjectVersion; ein nicht versioniertes Lesen benötigt s3:GetObject.

#### Python

Erstellen Sie create-download-link.py neben pipeline.py und kopieren Sie den kompletten Code unten hinein. Es verwendet das Boto3-Paket, das zu Beginn installiert wurde.

##### 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

Installieren Sie die Signaturpakete im Ordner Element, dann speichern Sie die Quelle unten als create-download-link.mjs in diesem Ordner.

##### Installieren Sie den S3-Signierungsclient

```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 präsigniertes URL Beispiel](https://docs.aws.amazon.com/boto3/latest/guide/s3-presigned-urls.html)
- [AWS JavaScript präsigniertes URL-Beispiel](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/javascript_s3_code_examples.html)
- [S3 Zugang und URL Ablauf](https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-presigned-url.html)

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

### Geben Sie den Link an den autorisierten Benutzer zurück

Erwarten Sie ein privates access.json mit URL und expiresInSeconds: 300. Ihr Backend gibt nur das URL an den autorisierten Benutzer zurück. Jeder, der es hält, kann die Datei für bis zu fünf Minuten herunterladen; es kann früher mit den Signatur-Anmeldeinformationen ablaufen.

Erstellen Sie einen neuen Link aus dem gespeicherten Ready Record, wenn der Benutzer den nächsten Zugriff anfordert. Behalten Sie den Objektschlüssel und die Version in Ihrer Datenbank, anstatt das auslaufende URL als Asset-Adresse zu speichern. Dieses lokale Beispiel stoppt, wenn access.json bereits vorhanden ist.

#### Python

##### Erstellen Sie einen Fünf-Minuten-Link

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


#### Node.js

##### Erstellen Sie einen Fünf-Minuten-Link

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

## Neustart von der letzten bestätigten Phase

| Lage | Nächste Maßnahme |
| --- | --- |
| Akzeptierter Job / lokale Wartezeit zeitversetzt | Wiederholen Sie runs recover mit dem gleichen runId in ein neues Versuchsverzeichnis. |
| S3 Zugriff verweigert oder unterbrochen Lesen | Beheben Sie die AWS-Leseidentität oder -Verbindung. Wiederherstellen Sie in ein neues Verzeichnis und überprüfen Sie es erneut; bewahren Sie die vorherige Teildatei auf. |
| Byte Anzahl / MD5 / Ziel-Inkongruenz | Stoppen. Vergleichen Sie das Manifest, die Objektversion und das geplante Ziel, bevor Sie die Medien verwenden. |
| verifiziert/besteht bereits | Lesen Sie seine ready.json, oder überprüfen Sie seine unvollständige Verifizierung. Das Drehbuch wird es nicht überschreiben. |
| App-Download URL abgelaufen | Autorisieren Sie den Zugriff erneut und signieren Sie den gespeicherten object/version. Senden Sie keinen weiteren FlashData-Download. |
| run_id_input_conflict | Der Antrag hat sich geändert. Wiederherstellen des ursprünglichen Laufs; Verwenden Sie einen neuen runId nur für eine absichtliche neue Ausgabe. |
| 401 / 403 / 402 / 429 | Fix Zugriff, Berechtigungen oder Balance; Folgen Sie Retry-After. Überprüfen Sie gespeicherte Arbeit, bevor Sie eine Einreichung erneut versuchen. |


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

## Die gleichen Stufen auf eine Warteschlange anwenden

1. Beginnen Sie mit einem Gegenstand während des Fluges. Lesen Sie die aktuellen Grenzwerte, bevor Sie die Anwendungskonkurrenz erhöhen.
2. Bewahren Sie für jede video/output-Version ein dauerhaftes runId mit einem eindeutigen Zielpräfix auf. Speichern Sie das Konto, den Job ID und das Endergebnis in Ihrer Anwendungsdatenbank.
3. Bestehen Sie auf dem CLI-Zustandsverzeichnis für Prozessneustarts. Separate Maschinen benötigen eine gemeinsame Anwendungskoordination; ein lokales Journal dedupliziert keine unabhängigen staatlichen Verzeichnisse.
4. Verwenden Sie ready.json als Übergabe an die nachgelagerte Verarbeitung. Bewahren Sie ausgefallene Artikel einzeln auf, so dass erfolgreiche Lieferungen wiederverwendet werden.

- [Kontolimits](https://flashdata.dev/de/docs/guides/usage-and-limits/reference.md)
- [Server- und Containerberechtigungen](https://flashdata.dev/de/docs/guides/production-deployment/reference.md)
- [Wiederkehrende Aufgabenplanung](https://flashdata.dev/de/docs/guides/recurring-tasks/reference.md)
