Перейти к содержимому
RU
Ключ API
Обзор документации

Руководства

Постройте трубопровод доставки медиа

Загрузите MP4 в частное хранилище S3, возобновите после перезагрузки и дайте вашему приложению доступ к проверенному файлу.

На этой странице

Что вы будете строить

Один прочный элемент перемещается из видео ID в готовый к применению файл. Держите каждый этап на диске, чтобы новый процесс мог продолжаться от последнего подтвержденного результата.

Трубопровод и сохраненные записи
item.json
  Отправить сообщение Once Save Run + Job ID
  Восстановление работы delivery.json
  Проверить байты S3 media.mp4 + ready.json
  Авторизовать пользователя приложения → Краткосрочная загрузка URL

Прежде чем начать

Выберите один пример пути для всех шести шагов. Оба используют установленный FlashData CLI с сохраненным профилем владельца и разрешением youtube_download, частный S3 storage.json для загрузок и идентификатор AWS, который может считывать доставленный объект.

Используйте Python 3.10+ в среде Python. Скрипты называют CLI, чтобы сохранить свой журнал, и Boto3, чтобы читать S3 и подписывать ссылки. Bash, jq, Node.js и AWS CLI не нужны. Запустите команды ниже с помощью python или python3, если это ваше имя переводчика.

Установите зависимость Python
python --version
flashdata --version
python -m pip install boto3

Сохранить настройки Runtime

Создайте папку с частными предметами вне контроля источника. Сохраните настройки для выбранного вами пути и отредактируйте абсолютные пути и имя профиля. Каждый процесс использует сохраненную учетную запись и запускает журнал. Личные данные хранятся в storage.json. Запускайте один процесс за единицу за раз.

Сохраните pipeline.json. На Windows такие траектории переднего слэша, как C:/private/flashdata-state, работают в JSON.

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

1. Сохранить прочный предмет

Сохраните item.json в этой папке. Замените видео и пункт назначения S3; в этом примере запрашивается один MP4 с разрешением до 720p. Храните runId для повторных попыток. Для другого запланированного вывода требуется новый префикс runId и объект.

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. Сохранить сценарий и проверить доступ

Создайте файл ниже, прежде чем запускать проверки. Он проверяет назначение S3 и сохраняет квитанцию для каждой попытки подачи.

Создайте сценарий трубопровода

Создайте pipeline.py в той же папке, что и pipeline.json и item.json. Скопируйте полный код ниже в этот файл и сохраните его. Вы будете повторно использовать его для проверки, отправки и восстановления в шагах 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)

Проверьте сохраненный аккаунт

Запустите эту бесплатную проверку в папке после сохранения сценария. Отсутствие доступа владельца или разрешения youtube_download останавливает проверку. Подтвердить счет ID, баланс, ставку по ТБ и лимиты. Окончательная зарядка зависит от загруженных байтов.

Проверьте окружающую среду и аккаунт
python pipeline.py check

Проверка без загрузки

После того, как спасли помощника, проведите его сухим пробегом. Python печатает ok: true и dryRun: true; Bash печатает true. Это подтверждает ввод и доступ без предоставления работы с медиа или резервирования кредитов.

Бесплатный сухой курс
python pipeline.py dry-run

3. Отправить и сохранить работу ID

Это предоставляет одну платную загрузку фона. Ожидайте status: accepted и jobId в локальном запуске. Держите профиль, каталог состояния и item.json для восстановления. Средства массовой информации готовы только после шага 5.

Подать один раз
python pipeline.py submit
Проверить местное государство - нет нового запроса
python pipeline.py inspect

Если бег уже сохранен или неопределенный

CLI государствоМеры
accepted + jobIdВосстановите этот запуск в шаге 4. Сохраняйте работу ID, если процесс останавливается.
succeededRecover/export - это сохраненный ответ, а затем проверка хранилища. Не подавайте новый пункт.
Неизвестный результат / нет подтвержденной работы IDДержите ход, квитанцию и ошибку. Проверить History или кандидата IDs, прежде чем принимать решение о другом представлении.

4. Восстановить запись доставки

Бег из папки товара в любом новом терминале. Восстановление ждет оригинальную работу и печатает каталог, содержащий delivery.json, run.json и квитанции. Минутный тайм-аут 10 останавливает локальное ожидание; повторное восстановление для возобновления той же работы.

Возобновить сэкономленную работу

Повторное использование pipeline.py сохранено на шаге 2. Дополнительный сценарий не нужен.

Восстановление существующей работы · без нового представления
python pipeline.py recover

Осмотрите доставленный объект

Ожидайте один объект S3 URL, положительный размер файла и MD5. Частные объекты нуждаются в вашей идентификации чтения AWS. Python сохраняет успешный каталог в delivery-dir.txt для более поздних сценариев. Bash сохраняет DELIVERY_DIR; в новом терминале установите его в печатный каталог.

Рекорд доставки
python pipeline.py delivery

5. Проверяйте байты, прежде чем маркировать готовые

Проверяющий проверяет исходный вход, ведро S3 и префикс, передает частный объект на диск и сравнивает его количество байтов и MD5. Файлы, соответствующие только verified/ready.json. Python читается как delivery-dir.txt; Узел использует DELIVERY_DIR. Также не нужно отправлять запрос FlashData.

Сохранить скрипт проверки

Этот верификатор обрабатывает стандартный Amazon S3 объект URLs. Для пользовательских конечных точек или другого поставщика используйте его аутентифицированный объект для чтения и сохраняйте тот же пункт назначения, байт-счет и контрольную сумму.

Создайте verify-media.py рядом с pipeline.py и скопируйте в него полный код ниже. Сохраните оба файла в папке элемента.

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)

Проверка проводится

После сохранения сценария запустите его из папки элемента.

Проверить и прочитать запись передачи
python verify-media.py

Откройте ready.json для вашего приложения

Ожидайте, что доставка будет проверена, и запись, содержащая run/job IDs, ведро, область, ключ объекта, проверенный размер и MD5. Это запись вашего приложения, созданная по сценарию. Архивируйте его с помощью delivery.json и оригинального элемента; он выживает в окне сохранения результата API.

Для транскрипции, индексации или другой обработки передайте верифицированный localFile своему работнику. Для загрузки, ориентированной на пользователя, продолжайте шаг 6.

6. Предоставьте вашему приложению контролируемый доступ

В вашем бэкэнде авторизуйте пользователя и посмотрите готовую запись этого пользователя в своем собственном магазине. Затем создайте короткоживущий S3 скачать URL. Используйте сохраненный пункт назначения; не принимайте ведро или ключ объекта, предоставленный браузером.

SDK использует идентификатор чтения бэкэнда AWS. Запрос FlashData не отправляется.

URL именует верифицированную объектную версию, когда она предоставляется в версии S3. Без версии ID, сохраняйте каждый выходной ключ неизменным после проверки. Идентификационное чтение конкретной версии требует s3:GetObjectVersion; неверсированное чтение требует s3:GetObject.

Создайте create-download-link.py рядом с pipeline.py и скопируйте в него полный код ниже. Он использует пакет Boto3, установленный в начале.

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)

Ожидайте частный access.json, содержащий URL и expiresInSeconds: 300. Ваш бэкэнд возвращает только URL авторизованному пользователю. Любой, кто держит его, может загрузить файл на срок до пяти минут; он может истечь раньше с подписью.

Создайте новую ссылку из сохраненной готовой записи, когда пользователь запрашивает доступ. Храните ключ объекта и версию в своей базе данных, а не сохраняйте истекающий URL в качестве адреса актива. Этот локальный пример останавливается, если access.json уже существует.

Создайте пятиминутную ссылку
python create-download-link.py

Перезапуск с последнего подтвержденного этапа

ПоложениеСледующее действие
Принятая работа / местное ожидание отложеноПовторите runs recover с тем же runId в новый каталог попыток.
S3 доступ запрещен или прерванИсправьте идентификатор или соединение считывания AWS. Восстановите новый каталог и проверьте снова; сохраните предыдущий частичный файл.
Количество байтов / MD5 / несоответствие назначенияСтой. Сравните манифест, объектную версию и запланированный пункт назначения перед использованием СМИ.
Проверено/ Уже существуетПрочитайте его ready.json или проверьте его неполную проверку. Сценарий не будет переписывать его.
Загрузка приложения URL истеклаАвторизовать доступ и подписать сохраненный object/version. Не отправляйте другую загрузку FlashData.
run_id_input_conflictЗапрос изменился. Восстановите исходный запуск; используйте новый runId только для преднамеренного нового вывода.
401 / 403 / 402 / 429Исправьте доступ, разрешения или баланс; следуйте Retry-After. Проверить сохраненную работу, прежде чем повторно подавать заявку.

Применять одни и те же этапы к очереди

  1. Начните с одного элемента в полете. Прочитайте текущие ограничения перед увеличением параллелизма приложений.
  2. Держите один прочный runId для каждой версии video/output с отдельным префиксом назначения. Храните учетную запись, работу ID и конечный результат в базе данных приложений.
  3. Сохраняйте каталог состояния CLI при перезапуске процесса. Отдельные машины нуждаются в совместной координации приложений; местный журнал не дублирует независимые государственные каталоги.
  4. Используйте ready.json в качестве передачи для последующей обработки. Сохраняйте неисправные предметы по отдельности, поэтому успешные поставки используются повторно.