Przejdź do treści
PL
Uzyskaj klucz API
Przeglądaj dokumentację

Poradniki

Zbuduj rurociąg do dostarczania mediów

Pobierz MP4 do prywatnej pamięci S3, wznowić po ponownym uruchomieniu i dać aplikacji dostęp do zweryfikowanego pliku.

Na tej stronie

Co zbudujesz

Jeden trwały element przenosi się z wideo ID do pliku applation- ready. Zachować każdy etap na dysku, aby nowy proces mógł być kontynuowany od ostatniego potwierdzonego wyniku.

Pipeline i zapisanych rekordów
item.json
  → złożyć raz → zapisane uruchomić + zadanie ID
  → odzyskać pracę → delivery.json
  → weryfikuj bajty S3 → media.mp4 + ready.json
  → autoryzuj użytkownika aplikacji → short- live download URL

Zanim zaczniesz

Wybierz jedną ścieżkę przykładową dla wszystkich sześciu kroków. Oba używać zainstalowany FlashData CLI z zapisanym profilem właściciela i zezwolenia youtube_download, prywatny S3 storage.json do wysyłania i AWS tożsamości, które mogą odczytać dostarczony obiekt.

Użyj Python 3.10 + w środowisku Python. Skrypty wzywają CLI do zachowania dziennika pracy, a Boto3 do odczytu S3 i podpisania linków. Bash, jq, Node.js i AWS CLI nie są potrzebne. Uruchom poniższe polecenia pythonem lub python3, jeśli jest to nazwa tłumacza.

Zainstaluj zależność Python
python --version
flashdata --version
python -m pip install boto3

Zapisz ustawienia runtime

Utwórz prywatny folder elementów poza kontrolą źródła. Zapisz ustawienia dla wybranej ścieżki i edytuj ścieżki bezwzględne i nazwę profilu. Każdy proces używa zapisanego konta i uruchamia dziennik. Zapisy pamięci w prywatnych storage.json. Uruchom jeden proces na element na raz.

Zapisz pipeline.json. Na Windows, forward- slash ścieżki takie jak C: /private/flashdata-state pracy w JSON.

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

1. Zapisz jeden trwały element

Zapisz item.json w tym folderze. Zastąp wideo i cel S3; ten przykład wymaga jednego MP4 do 720p. Zachowaj runId na powtórki. Inne planowane wyjście wymaga nowego prefiksu runId i obiektu.

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. Zapisz skrypt i sprawdź dostęp

Utwórz plik poniżej przed uruchomieniem kontroli. Potwierdza on cel S3 i zachowuje paragon dla każdej próby złożenia.

Utwórz skrypt rurociągu

Utwórz pipeline.py w tym samym folderze co pipeline.json i item.json. Skopiuj cały kod poniżej do tego pliku i zapisz go. Użyjesz go do kontroli, składania i odzyskiwania w etapach 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)

Sprawdź zapisane konto

Uruchom ten bezpłatny czek z folderu elementu po zapisaniu skryptu. Zaginiony dostęp właściciela lub pozwolenie youtube_download zatrzymuje czek. Potwierdź konto ID, saldo, wskaźnik przerobu TB i limity. Ostateczna opłata zależy od wczytanych bajtów.

Sprawdź środowisko i konto
python pipeline.py check

Sprawdzić bez pobierania

Po uratowaniu pomocnika, uruchom jego suchy bieg. Python drukuje ok: true i dryRun: true; Bash drukuje true. Potwierdza to wejście i dostęp bez składania pracy mediów lub rezerwowania kredytów.

Bezpłatny bieg suchy
python pipeline.py dry-run

3. Prześlij i zachowaj zadanie ID

To przedstawia jeden płatny pobór tła. Oczekuj status: accepted i jobId w lokalnym biegu. Zachowaj profil, katalog stanu i item.json do odzyskania. Media są gotowe dopiero po kroku 5.

Prześlij raz
python pipeline.py submit
Sprawdź stan lokalny · nie ma nowego zapytania
python pipeline.py inspect

Jeśli bieg jest już zapisany lub niepewny

Stan CLIDziałanie
accepted + jobIdOdzyskać ten bieg w kroku 4. Zatrzymaj zadanie ID, jeśli proces się zatrzyma.
succeededRecover/export jego zapisaną odpowiedź, a następnie zweryfikować przechowywanie. Nie należy składać nowego elementu.
Nieznany wynik / brak potwierdzonej pracy IDUtrzymuj bieg, odbiór i błąd. Przed podjęciem decyzji o innym złożeniu należy sprawdzić History lub kandydata IDs.

4. Odzyskiwanie zapisów dostawy

Uruchom z folderu elementów w dowolnym nowym terminalu. Odzysk czeka na oryginalne zadanie i drukuje katalog zawierający delivery.json, run.json i paragony. 10- minute timeout zatrzymuje lokalne oczekiwanie; powtórne odzyskanie, aby wznowić to samo zadanie.

Wznowienie uratowanej pracy

Ponowne użycie pipeline.py zapisanego w kroku 2. Nie jest potrzebny dodatkowy skrypt.

Odzyskiwanie istniejącej pracy · brak nowego złożenia
python pipeline.py recover

Sprawdź dostarczony obiekt

Oczekuj jednego obiektu S3 URL, dodatniego rozmiaru pliku i MD5. Prywatne obiekty potrzebują twojej tożsamości AWS. Python zapisuje udany katalog w delivery-dir.txt dla późniejszych skryptów. Bash zachowuje DELIVERY_DIR; w nowym terminalu ustaw go na drukowany katalog.

Rejestr dostawy
python pipeline.py delivery

5. Weryfikacja bajtów przed oznakowaniem gotowym

Weryfikator sprawdza oryginalne wejście, wiadro S3 i przedrostek, strumieniuje obiekt prywatny na dysk i porównuje jego liczbę bajtów i MD5. Tylko pasujące pliki produkują verified/ready.json. Python czyta delivery-dir.txt; Węzeł wykorzystuje DELIVERY_DIR. Ani nie składa zapytania FlashData.

Zapisz skrypt weryfikacji

Ten weryfikator obsługuje standardowy obiekt Amazon S3 URLs. W przypadku niestandardowych punktów końcowych lub innego dostawcy, użyj jego uwierzytelnionego obiektu przeczytaj i zachowaj to samo miejsce docelowe, licznik bajkowy i kontrole sumy kontrolnej.

Utwórz verify-media.py obok pipeline.py i skopiuj do niego cały kod poniżej. Zapisz oba pliki w folderze elementów.

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)

Uruchom weryfikację

Po zapisaniu skryptu, uruchom go z folderu elementu.

Zweryfikuj i przeczytaj zapis przekazania
python verify-media.py

Rozdaj ready.json do aplikacji

Oczekiwanie Dostawa zweryfikowany i rekord zawierający run/job IDs, wiadro, region, klucz obiektu, zweryfikowany rozmiar i MD5. To jest rekord twojej aplikacji, stworzony przez skrypt. Archiwizuj go za pomocą delivery.json i oryginalnego elementu; przetrwa okno retencyjne wyniku API.

Do transkrypcji, indeksowania lub innego przetwarzania, przekazać zweryfikowany localFile do pracownika. Dla użytkownika do pobrania, kontynuuj krok 6.

6. Daj dostęp kontrolowany aplikacji

W swoim tle, autoryzuj użytkownika i sprawdź, że użytkownik jest gotowy rekord w swoim sklepie. Następnie utworzyć krótko żywą S3 pobierz URL. Użyj zapisanego miejsca docelowego; nie akceptuj kubełka lub klucza obiektu dostarczonego przez przeglądarkę.

SDK używa odczytu AWS. Nie wysyła się zapytania FlashData.

URL określa zweryfikowaną wersję obiektu, kiedy jest to wersja z wersją S3. Bez wersji ID, po weryfikacji zachować każdy klucz wyjściowy niezmienny. Tożsamość odczytująca konkretną wersję wymaga s3: GetObjectVersion; niemodyfikowane potrzeby odczytu s3: GetObject.

Utwórz create-download-link.py obok pipeline.py i skopiuj do niego cały kod poniżej. Wykorzystuje pakiet Boto3 zainstalowany na początku.

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)

Oczekuj prywatnego access.json zawierającego url i expiresInSeconds: 300. Twój backend zwraca tylko URL do autoryzowanego użytkownika. Każdy, kto go posiada, może pobrać plik na okres do pięciu minut; może on wygasnąć wcześniej wraz z podpisem.

Utwórz nowy link z zapisanego, gotowego rekordu, gdy użytkownik następny żąda dostępu. Zatrzymaj klucz obiektu i jego wersję w bazie danych, zamiast przechowywać wygasające URL jako adres aktywów. Ten lokalny przykład zatrzymuje się, jeśli access.json już istnieje.

Utwórz link 5 minut
python create-download-link.py

Wznawiaj z ostatniego potwierdzonego etapu

SytuacjaNastępna akcja
Zaakceptowana praca / lokalne oczekiwanie w czasiePowtórzyć runs recover z tym samym runId do nowego katalogu prób.
Odmowa lub przerwanie dostępu do S3Napraw AWS odczytuje tożsamość lub połączenie. Odzyskiwanie do nowego katalogu i weryfikacja ponownie; zachować poprzedni plik częściowy.
Liczba bajtów / MD5 / niedopasowanie miejsca przeznaczeniaPrzestań. Porównaj manifest, wersję obiektu i planowany cel przed użyciem mediów.
zweryfikowane / już istniejePrzeczytaj ready.json lub sprawdź jego niekompletną weryfikację. Skrypt nie nadpisze tego.
Pobieranie aplikacji URL wygasłoAutoryzacja dostępu ponownie i podpisać zapisane object/version. Nie należy wysyłać kolejnego pobrania FlashData.
run_id_input_conflictWniosek się zmienił. Odzyskiwanie oryginalnego przebiegu; użycie nowego runId tylko dla zamierzonego nowego wyjścia.
401 / 403 / 402 / 429Popraw dostęp, uprawnienia lub równowagę; postępuj zgodnie z Retry-After. Sprawdzić zapisane pracy przed ponownym próbami złożenia.

Zastosuj te same etapy do kolejki

  1. Zacznij od jednej pozycji w locie. Przeczytaj aktualne limity przed zwiększeniem współzależności aplikacji.
  2. Dla każdej wersji video/output należy zachować jeden trwały prefiks runId, z odrębnym przedrostkiem docelowym. Zapisz konto, zadanie ID i wynik końcowy w bazie danych aplikacji.
  3. Persist katalog stanu CLI w całym procesie restartuje. Oddzielne maszyny wymagają wspólnej koordynacji aplikacji; lokalny dziennik nie dedukuje niezależnych katalogów państwowych.
  4. Używać ready.json jako przekazania do dalszego przetwarzania. Utrzymanie nieudanych elementów indywidualnie, tak aby udane dostawy były ponownie wykorzystywane.