Lewati ke isi
ID
Dapatkan kunci API
Jelajahi dokumentasi

Panduan

Buat pipeline pengiriman media

Unduh MP4 ke penyimpanan S3 pribadi, lanjutkan setelah restart dan berikan akses aplikasi ke berkas yang diverifikasi.

Di halaman ini

What you 'll build

Satu item tahan lama bergerak dari video ID ke sebuah peralatan-siap file. Menjaga setiap tahap di disk sehingga proses baru dapat melanjutkan dari hasil dikonfirmasi terakhir.

Baris pipa dan catatan tersimpan
item.json
  Diserahkan setelah memperoleh informasi yang telah disimpan ID
  Jangan khawatir, aku akan mencari pekerjaan. delivery.json
  Pastikan S3 bytes = media.mp4 + ready.json
  Authortifikasi pengguna aplikasi membakarnya langsung mengunduh URL

Sebelum Anda mulai

Pilih salah satu contoh jalan untuk semua enam langkah. Keduanya gunakan instalasi FlashData CLI dengan profil pemilik tersimpan dan youtube_download ijin, private S3 storage.json untuk upload, dan sebuah identitas AWS yang dapat membaca objek yang disampaikan.

Gunakan Python 3.10 + dalam lingkungan Python Anda. Naskah menyebut CLI untuk melestarikan jurnalnya, dan Boto3 untuk membaca S3 dan menandatangani link. Bash, jq, Node.js dan AWS CLI tidak diperlukan. Jalankan perintah di bawah ini dengan python3 atau jika itu adalah nama penerjemah Anda.

Pasang ketergantungan Python
python --version
flashdata --version
python -m pip install boto3

Simpan pengaturan waktu-jalan

Membuat folder butir privat di luar kendali sumber. Simpan pengaturan bagi path yang Anda pilih dan sunting path absolut dan nama profil. Setiap proses menggunakan akun yang disimpan dan menjalankan jurnal. Kredensial penyimpanan tetap dalam storage.json pribadi. Jalankan satu proses per item pada suatu waktu.

Simpan pipeline.json. Pada Windows, jalur garis miring seperti C: /private/flashdata-state bekerja di JSON.

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

1. Simpan satu butir tahan lama

Simpan item.json dalam folder itu. Ganti video dan tujuan S3; contoh ini meminta satu MP4 di hingga 720p. Simpan runId-nya untuk percobaan ulang. Keluaran berbeda yang direncanakan memerlukan runId baru dan prefiks objek.

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. Simpan skrip dan periksa akses

Membuat berkas di bawah ini sebelum menjalankan pemeriksaan. Ini memvalidasi tujuan S3 dan menyimpan tanda terima untuk setiap percobaan pengiriman.

Buat skrip pipeline

Buat pipeline.py dalam folder yang sama seperti pipeline.json dan item.json. Salin kode lengkap di bawah ini ke dalam berkas itu dan simpan. Anda akan menggunakannya kembali untuk pemeriksaan, penyerahan dan pemulihan di langkah 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)

Periksa akun Anda yang tersimpan

Jalankan pemeriksaan gratis dari folder butir setelah menyimpan skrip. Kehilangan akses pemilik atau izin youtube_download menghentikan pemeriksaan. Konfirmasikan rekening ID, keseimbangan, tingkat per- TB dan batas. Biaya akhir tergantung pada byte upload.

Periksa lingkungan dan akun
python pipeline.py check

Validate tanpa sebuah download

Setelah menyelamatkan pembantu, jalankan nya kering lari. Python cetak ok: true dan dryRun: true; Bash cetak true. Ini memvalidasi masukan dan akses tanpa mengirimkan pekerjaan media atau reserving kredit.

Uji coba bebas
python pipeline.py dry-run

3. Kirim dan pertahankan pekerjaan ID

Ini menyerahkan yang dibayar latar belakang download. Mengharapkan status: accepted dan jobId dalam run lokal. Simpan profil, direktori negara dan item.json untuk pemulihan. Media hanya siap setelah langkah 5.

Kirim sekali
python pipeline.py submit
Inspeksi keadaan lokal
python pipeline.py inspect

Jika jalankan sudah disimpan atau tidak pasti

Kondisi CLIAksi
accepted + jobIdRecover run ini dalam langkah 4. Pertahankan pekerjaan ID jika prosesnya berhenti.
succeededRecover/export respon yang tersimpan, kemudian periksa penyimpanan. Jangan mengirimkan item baru.
Hasil tidak diketahui / tidak ada konfirmasi pekerjaan IDTetap jalankan, penerimaan dan kesalahan. Inspeksi History atau kandidat IDs sebelum memutuskan pengajuan lain.

4. Merebut kembali catatan pengiriman

Jalankan dari folder butir di terminal baru manapun. Pemulihan menunggu pekerjaan aslinya dan mencetak sebuah direktori berisi delivery.json, run.json dan penerimaan. A 10-menit timeout berhenti menunggu lokal; recovery untuk melanjutkan pekerjaan yang sama.

Lanjutkan pekerjaan yang disimpan

Gunakan pipeline.py disimpan dalam langkah 2. Tak ada skrip tambahan yang diperlukan.

Mengembalikan pekerjaan yang telah ada
python pipeline.py recover

Inspeksi objek yang dikirim

Mengharapkan satu S3 objek URL, ukuran berkas positif dan sebuah MD5. Benda pribadi perlu Anda AWS membaca identitas. Python menyimpan direktori sukses dalam delivery-dir.txt untuk skrip selanjutnya. Bash menyimpan DELIVERY_DIR; dalam terminal baru, mengaturnya ke direktori yang dicetak.

Catatan pengiriman
python pipeline.py delivery

5. Verifikasi bytes sebelum menandai siap

Pemeriksaan verifikasi pada masukan asli, ember S3 dan awalan, arus objek pribadi ke disk, dan membandingkan byte terhitung dan MD5. Hanya berkas yang cocok yang menghasilkan verified/ready.json. Python membaca delivery-dir.txt; Node menggunakan DELIVERY_DIR. Baik menyerahkan permintaan FlashData.

Simpan skrip verifikasi

Verifier ini menangani standar Amazon S3 objek URLs. Untuk titik akhir kustom atau penyedia lain, gunakan objek terotentikasi yang dibaca dan pertahankan tujuan yang sama, dengan menghitung dan cek checksum.

Buat verify-media.py di samping pipeline.py dan salin kode lengkap di bawahnya. Simpan kedua berkas dalam folder butir.

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)

Jalankan verifikasi

Setelah menyimpan skrip, jalankan dari folder butir.

Verifikasi dan baca catatan handoff
python verify-media.py

Serahkan ready.json ke aplikasi Anda

Mengharapkan Pengiriman diverifikasi dan sebuah catatan berisi run/job IDs, ember, wilayah, kunci objek, ukuran yang diverifikasi dan MD5. Ini adalah catatan aplikasi Anda, dibuat oleh script. Arsipkan dengan delivery.json (Dan pohon pisang) yang juga dikenal dengan nama pohon muz (yang bersusun-susun) buahnya mulai dari bagian atas hingga bagian bawahnya. API jendela retensi hasil.

Untuk transkripsi, indeks atau pemrosesan lainnya, lulus diverifikasi localFile kepada pekerja Anda. Untuk sebuah unduhan hadapi, lanjutkan dengan langkah 6.

6. Berikan akses kendali aplikasi Anda

Dalam backend Anda, otorisasi pengguna dan mencari bahwa pengguna siap merekam di toko Anda sendiri. Lalu buatlah S3 yang singkat untuk diunduh URL. Gunakan tujuan yang disimpan; jangan terima sebuah ember atau kunci objek yang disediakan oleh peramban.

SDK menggunakan identitas pembacaan AWS di backend. Tidak. FlashData query is sent.

The URL names versi objek yang diverifikasi ketika S3 versioning menyediakan satu. Tanpa versi ID, jaga setiap kunci keluaran tak dapat diubah setelah verifikasi. Pembacaan identitas versi tertentu membutuhkan s3: GetObjectversion; pembacaan tanpa versi memerlukan s3: GetObject.

Buat create-download-link.py di samping pipeline.py dan salin kode lengkap di bawahnya. Menggunakan paket Boto3 yang dipasang di awal.

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)

Berharap access.json pribadi berisi url dan expiresInSeconds: 300. Backend Anda kembali hanya URL kepada pengguna yang berwenang. Siapapun yang memegangnya dapat mengunduh berkas hingga lima menit. Ini mungkin berakhir lebih awal dengan kredensial penandatanganan.

Buat taut baru dari catatan siap disimpan ketika pengguna selanjutnya meminta akses. Simpan kunci dan versi objek di basis data Anda, daripada menyimpan URL yang diekspor sebagai alamat aset. Contoh lokal ini berhenti jika access.json sudah ada.

Buat sebuah taut lima menit
python create-download-link.py

Mulai lagi dari tahap dikonfirmasi terakhir

SituasiAksi berikutnya
Menerima tugas / waktu tunggu lokal habisUlangi runs recover dengan sama runId ke direktori percobaan yang baru.
Akses S3 ditolak atau terganggu pembacaanPerbaiki AWS membaca identitas atau koneksi. Kembali ke direktori baru dan periksa lagi; simpan berkas parsial sebelumnya.
Jumlah byte / MD5 / tujuan tidak cocokBerhenti. Bandingkan manifest, versi objek dan tujuan yang direncanakan sebelum menggunakan media.
diverifikasi / sudah adaBaca ready.json-nya, atau periksa verifikasi-nya. Naskah tidak akan menimpanya.
Aplikasi download URL berakhirOtorisasi akses lagi dan tandatangani object/version. yang tersimpan Jangan kirim download FlashData lain.
run_id_input_conflictPermintaan berubah. Recover run asli; gunakan runId baru hanya untuk keluaran baru yang disengaja.
401 / 403 / 402 / 429Perbaiki akses, perizinan, atau keseimbangan; ikuti Retry-After. Inspeksi menyimpan pekerjaan sebelum mencoba kembali pengajuan.

Terapkan tahap yang sama ke antrian

  1. Mulailah dengan satu item in- penerbangan. Baca batas saat ini sebelum meningkatkan konkuensi aplikasi.
  2. Pertahankan satu runId yang dapat dipertahankan untuk setiap versi video/output, dengan awalan tujuan yang berbeda. Simpan akunnya, kerja ID dan hasil akhir dalam database aplikasi Anda.
  3. Persist direktori keadaan CLI melalui proses restart. Mesin-mesin terpisah perlu koordinasi aplikasi bersama; jurnal lokal tidak mendeduplikasi direktori negara independen.
  4. Gunakan ready.json sebagai handoff untuk pemrosesan hilir. Menyimpan item yang gagal secara individual pengiriman yang sukses digunakan kembali.