Aller au contenu
FR
Obtenir une clé API
Parcourir la documentation

Guides

Créer un pipeline de livraison de médias

Téléchargez un MP4 dans un stockage S3 privé, reprenez après un redémarrage et donnez à votre application accès au fichier vérifié.

Sur cette page

Ce que vous allez créer

Un élément conservé sur disque passe d’un identifiant vidéo à un fichier utilisable par l’application. Enregistrez chaque étape pour qu’un nouveau processus puisse reprendre au dernier résultat confirmé.

Pipeline et enregistrements conservés
item.json
  → soumettre une seule fois  → exécution et identifiant de tâche enregistrés
  → reprendre la tâche       → delivery.json
  → vérifier les octets S3   → media.mp4 + ready.json
  → autoriser l’utilisateur  → URL de téléchargement à durée limitée

Avant de commencer

Choisissez une seule variante pour les six étapes. Toutes deux utilisent la CLI FlashData installée avec un profil propriétaire enregistré et la permission youtube_download, un fichier storage.json privé pour les transferts vers S3, et une identité AWS autorisée à lire l’objet livré.

Utilisez Python 3.10+ dans votre environnement Python. Les scripts appellent la CLI pour conserver son journal d’exécution, et Boto3 pour lire S3 et signer les liens. Bash, jq, Node.js et AWS CLI ne sont pas nécessaires. Exécutez les commandes avec python, ou python3 si votre interpréteur porte ce nom.

Installer la dépendance Python
python --version
flashdata --version
python -m pip install boto3

Enregistrer les paramètres d’exécution

Créez un dossier privé pour cet élément, hors du dépôt de code. Enregistrez les paramètres de la variante choisie et adaptez les chemins absolus et le nom du profil. Chaque processus utilise le compte et le journal d’exécution enregistrés. Les identifiants de stockage restent dans le fichier privé storage.json. Exécutez un seul processus par élément à la fois.

Enregistrez pipeline.json. Sous Windows, les chemins avec des barres obliques, comme C:/private/flashdata-state, fonctionnent en JSON.

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

1. Enregistrer un élément à traiter

Enregistrez item.json dans ce dossier. Remplacez la vidéo et la destination S3 ; cet exemple demande un MP4 limité à 720p. Conservez son runId pour les nouvelles tentatives. Une sortie différente nécessite un nouveau runId et un nouveau préfixe d’objet.

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. Enregistrer le script et vérifier l’accès

Créez le fichier ci-dessous avant de lancer les vérifications. Il valide la destination S3 et conserve un reçu pour chaque tentative de soumission.

Créer le script du pipeline

Créez pipeline.py dans le même dossier que pipeline.json et item.json. Copiez-y le code complet ci-dessous et enregistrez-le. Vous le réutiliserez pour les vérifications, la soumission et la reprise aux étapes 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)

Vérifier le compte enregistré

Lancez cette vérification gratuite depuis le dossier de l’élément après avoir enregistré le script. L’absence d’accès propriétaire ou de permission youtube_download interrompt la vérification. Confirmez l’identifiant du compte, le solde, le tarif par téraoctet et les limites. Le coût final dépend des octets transférés vers le stockage.

Vérifier l’environnement et le compte
python pipeline.py check

Valider sans télécharger

Après avoir enregistré le script, lancez sa simulation. Python affiche ok: true et dryRun: true ; Bash affiche true. Cela valide les paramètres et l’accès sans soumettre de téléchargement ni réserver de crédits.

Simulation gratuite
python pipeline.py dry-run

3. Soumettre et conserver l’identifiant de tâche

Cette commande soumet un téléchargement payant en arrière-plan. L’exécution locale doit indiquer status: accepted et un jobId. Conservez le profil, le répertoire d’état et item.json pour la reprise. Le média n’est prêt qu’après l’étape 5.

Soumettre une seule fois
python pipeline.py submit
Examiner l’état local · aucune nouvelle requête
python pipeline.py inspect

Si l’exécution est déjà enregistrée ou incertaine

État CLIAction
accepted + jobIdReprenez cette exécution à l’étape 4. Conservez l’identifiant de tâche si le processus s’arrête.
succeededRécupérez ou exportez la réponse enregistrée, puis vérifiez le stockage. Ne soumettez pas de nouvel élément.
Résultat inconnu / aucun identifiant de tâche confirméConservez l’exécution, le reçu et l’erreur. Consultez History ou les identifiants possibles avant de décider d’une nouvelle soumission.

4. Récupérer le résultat de livraison

Lancez la commande depuis le dossier de l’élément dans un nouveau terminal. La reprise attend la tâche d’origine et affiche un répertoire contenant delivery.json, run.json et les reçus. Après 10 minutes, le délai d’attente local expire ; relancez la reprise pour suivre la même tâche.

Reprendre la tâche enregistrée

Réutilisez pipeline.py enregistré à l’étape 2. Aucun script supplémentaire n’est nécessaire.

Reprendre la tâche existante · aucune nouvelle soumission
python pipeline.py recover

Examiner l’objet livré

Le résultat attendu contient une URL d’objet S3, une taille positive et un MD5. Les objets privés nécessitent votre identité AWS autorisée en lecture. Python enregistre le répertoire du résultat réussi dans delivery-dir.txt pour les scripts suivants. Bash conserve DELIVERY_DIR ; dans un nouveau terminal, définissez cette variable avec le répertoire affiché.

Résultat de livraison
python pipeline.py delivery

5. Vérifier les octets avant de déclarer le fichier prêt

Le script vérifie les paramètres d’origine, le bucket et le préfixe S3, écrit progressivement l’objet privé sur disque, puis compare sa taille en octets et son MD5. Seuls les fichiers conformes produisent verified/ready.json. Python lit delivery-dir.txt ; Node utilise DELIVERY_DIR. Aucun des deux ne soumet de requête FlashData.

Enregistrer le script de vérification

Ce script traite les URL d’objets Amazon S3 standard. Pour un endpoint personnalisé ou un autre fournisseur, utilisez sa lecture authentifiée d’objets en conservant les vérifications de destination, de taille et de somme de contrôle.

Créez verify-media.py à côté de pipeline.py et copiez-y le code complet ci-dessous. Enregistrez les deux fichiers dans le dossier de l’élément.

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)

Lancer la vérification

Après avoir enregistré le script, exécutez-le depuis le dossier de l’élément.

Vérifier et lire le fichier de transmission
python verify-media.py

Transmettre ready.json à votre application

Le résultat attendu est Delivery verified et un enregistrement contenant les identifiants d’exécution et de tâche, le bucket, la région, la clé de l’objet, la taille vérifiée et le MD5. Le script crée cet enregistrement pour votre application. Archivez-le avec delivery.json et l’élément d’origine ; il reste disponible au-delà de la période de conservation du résultat API.

Pour la transcription, l’indexation ou un autre traitement, transmettez le localFile vérifié à votre processus de traitement. Pour proposer un téléchargement à l’utilisateur, passez à l’étape 6.

6. Donner un accès contrôlé depuis votre application

Dans votre backend, vérifiez l’autorisation de l’utilisateur et retrouvez son enregistrement ready dans votre propre stockage. Créez ensuite une URL S3 de téléchargement à durée limitée. Utilisez la destination enregistrée ; n’acceptez pas de bucket ni de clé d’objet fournis par le navigateur.

Le SDK utilise l’identité AWS du backend autorisée en lecture. Aucune requête FlashData n’est envoyée.

L’URL désigne la version vérifiée de l’objet lorsque le versionnement S3 en fournit une. Sans identifiant de version, conservez chaque objet à sa clé sans le modifier après vérification. La lecture d’une version précise nécessite s3:GetObjectVersion ; une lecture sans version nécessite s3:GetObject.

Créez create-download-link.py à côté de pipeline.py et copiez-y le code complet ci-dessous. Il utilise le paquet Boto3 installé au début.

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)

Le résultat attendu est un fichier privé access.json contenant url et expiresInSeconds: 300. Votre backend renvoie uniquement l’URL à l’utilisateur autorisé. Toute personne qui la détient peut télécharger le fichier pendant cinq minutes au maximum ; elle peut expirer plus tôt avec les identifiants de signature.

Créez un nouveau lien à partir de l’enregistrement ready sauvegardé lors de la prochaine demande d’accès. Conservez la clé et la version de l’objet dans votre base de données, plutôt que l’URL temporaire comme adresse du média. Cet exemple local s’arrête si access.json existe déjà.

Créer un lien valable cinq minutes
python create-download-link.py

Reprendre à la dernière étape confirmée

SituationAction suivante
Tâche acceptée / délai d’attente local dépasséRelancez runs recover avec le même runId dans un nouveau répertoire de tentative.
Accès S3 refusé ou lecture interrompueCorrigez l’identité AWS de lecture ou la connexion. Reprenez dans un nouveau répertoire et vérifiez à nouveau ; conservez le fichier partiel précédent.
Taille, MD5 ou destination non conformesArrêtez le traitement. Comparez le manifeste, la version de l’objet et la destination prévue avant d’utiliser le média.
verified/ existe déjàLisez son ready.json ou examinez sa vérification incomplète. Le script ne l’écrasera pas.
Le lien de téléchargement de l’application a expiréVérifiez à nouveau l’autorisation et signez l’objet ou la version enregistrés. Ne soumettez pas un autre téléchargement FlashData.
run_id_input_conflictLa requête a changé. Reprenez l’exécution d’origine ; utilisez un nouveau runId uniquement pour une nouvelle sortie voulue.
401 / 403 / 402 / 429Corrigez l’accès, les permissions ou le solde ; respectez Retry-After. Examinez les opérations enregistrées avant de retenter une soumission.

Appliquer les mêmes étapes à une file d’attente

  1. Commencez par un seul élément en cours de traitement. Consultez les limites actuelles avant d’augmenter le nombre de traitements simultanés dans votre application.
  2. Conservez un runId durable pour chaque version de vidéo ou de sortie, avec un préfixe de destination distinct. Enregistrez le compte, l’identifiant de tâche et le résultat final dans la base de données de votre application.
  3. Conservez le répertoire d’état CLI entre les redémarrages des processus. Des machines distinctes nécessitent une coordination partagée dans l’application ; un journal local ne déduplique pas les opérations de répertoires d’état indépendants.
  4. Utilisez ready.json pour transmettre le résultat aux traitements suivants. Conservez les éléments en échec séparément afin de réutiliser les livraisons réussies.