Salta al contenuto
IT
Ottieni la chiave API
Sfoglia la documentazione

Esempi

Scarica un video per il tuo storage

Consegnare un MP4 al secchio Amazon S3, quindi recuperare e verificare il file con Python o Bash.

In questa pagina

Prima di iniziare

Utilizzare l'accesso del proprietario con il permesso youtube_download e i crediti disponibili. Il download non è incluso nell'accesso di prova temporaneo. Hai bisogno di un secchio Amazon S3 esistente e di un video che sei autorizzato a scaricare.

Scegliere Python 3.10+ con richieste e boto3, o Bash con cURL, jq, OpenSSL e AWS CLI v2. Su Windows, utilizzare Git Bash per la versione Bash.

CredenzialiUsato per
FLASHDATA_API_KEYInviare il lavoro e recuperare il suo stato e record di consegna.
FLASHDATA_STORAGE_ACCESS_KEY / FLASHDATA_STORAGE_SECRET_KEYUn'identità di upload S3 inviata a FlashData per la scrittura al secchio e prefisso scelto.
Il tuo profilo o ruolo AWS localeLeggi l'oggetto privato con boto3 o AWS CLI nella fase 4. Ha bisogno di s3:GetObject accesso.

1. Scegli il video e la destinazione

Creare una cartella di download-video privata al di fuori del repository. Salvare request.json e aprire un terminale in quella cartella. Sostituire storage_url con il nome e la regione del secchio con la sua regione AWS; utilizzare un video 11-character ID.

Questa ricetta offre video con audio come MP4, fino a 720p, sotto recipes/clip-001/. Tenere il secchio privato. Utilizzare un prefisso fresco per un download separato in modo che un altro lavoro non possa sovrascrivere il percorso di questo oggetto.

download-video/request.json
{
  "source": "youtube_download",
  "video_id": "jNQXAC9IVRw",
  "params": {
    "download_type": "audio_video",
    "video_quality": "<=720",
    "output_format": "mp4",
    "storage": {
      "storage_type": "s3",
      "storage_url": "your-media-bucket",
      "region": "us-east-1",
      "object_prefix": "recipes/clip-001"
    }
  }
}

2. Inserisci un lavoro di download

Scegliere una versione e salvare il suo script accanto a request.json prima di eseguirlo. Lo script legge le tre variabili di ambiente sopra o chiede loro a richieste nascoste. Gli agenti dovrebbero fornirli dal loro negozio segreto. Non mettere le chiavi in request.json.

Una nuova cartella job-001 invia una richiesta asinconica. Salva la richiesta senza credenziali di upload, un timestamp, la risposta HTTP e il lavoro ID. Riutilizzare quella cartella smette di sottoporre; non crea un secondo lavoro.

Installare nel tuo ambiente Python
python -m pip install requests boto3
download-video/submit.py
# Save as download-video/submit.py.
import getpass
import json
import os
import re
import sys
from datetime import datetime, timezone
from pathlib import Path

import requests

ROOT = Path(__file__).resolve().parent


def read_json(path):
    return json.loads(path.read_text(encoding="utf-8-sig"))


def secret(name):
    value = os.environ.get(name) or getpass.getpass(name + ": ")
    if not value.strip():
        raise ValueError("Missing " + name)
    return value


def main():
    os.umask(0o077)
    folder = sys.argv[1]
    if not re.fullmatch(r"[A-Za-z0-9_-]+", folder):
        raise ValueError("Use a simple output folder name, such as job-001.")
    directory = ROOT / folder
    if directory.exists():
        raise ValueError("Keep this attempt. Run collect.py with the same folder.")
    request = read_json(ROOT / "request.json")
    storage = request["params"]["storage"]
    if (request["source"] != "youtube_download"
            or not re.fullmatch(r"[A-Za-z0-9_-]{11}", request["video_id"])
            or request["params"]["download_type"] != "audio_video"
            or request["params"]["output_format"] != "mp4"
            or storage["storage_type"] != "s3"
            or set(storage) != {"storage_type", "storage_url", "region", "object_prefix"}
            or not re.fullmatch(r"[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]", storage["storage_url"])
            or not re.fullmatch(r"[a-z0-9-]+", storage["region"])
            or not re.fullmatch(r"[A-Za-z0-9_-]+(/[A-Za-z0-9_-]+)*", storage["object_prefix"])):
        raise ValueError("Check the video, MP4 options and Amazon S3 destination.")
    key = secret("FLASHDATA_API_KEY")
    access = secret("FLASHDATA_STORAGE_ACCESS_KEY")
    secret_key = secret("FLASHDATA_STORAGE_SECRET_KEY")
    directory.mkdir(mode=0o700)
    # Save the plan BEFORE sending. Keep upload credentials out of this file.
    (directory / "request.json").write_text(json.dumps(request, indent=2), encoding="utf-8")
    (directory / "submitted-at.txt").write_text(
        datetime.now(timezone.utc).isoformat(), encoding="utf-8")
    storage.update(access_key=access, secret_key=secret_key)
    response = requests.post(
        "https://data.flashdata.dev/v1/queries", json=request,
        headers={"X-API-Key": key, "Accept": "application/json"},
        timeout=(10, 120), allow_redirects=False)
    (directory / "submission.json").write_bytes(response.content)
    (directory / "submission-headers.txt").write_text(
        "\n".join(f"{k}: {v}" for k, v in response.headers.items()), encoding="utf-8")
    (directory / "submission-http.txt").write_text(str(response.status_code))
    if response.status_code not in (200, 201, 202):
        raise ValueError(f"HTTP {response.status_code}. Inspect the saved attempt.")
    receipt = response.json()
    if (receipt.get("source") != "youtube_download"
            or not re.fullmatch(r"[A-Za-z0-9_-]+", receipt.get("id", ""))):
        raise ValueError("Missing job ID. Check History before submitting again.")
    print("Submitted:", receipt["id"], "— keep", directory)


if __name__ == "__main__":
    try:
        main()
    except (IndexError, KeyError, OSError, ValueError, requests.RequestException) as error:
        print("Network request failed. Keep this attempt and inspect its saved files."
              if isinstance(error, requests.RequestException) else str(error), file=sys.stderr)
        sys.exit(1)
Esegui dal download-video/
python submit.py job-001

ricevuta prevista

Stampa di successo Inviato: job_... e salva submission.json. La ricevuta conferma che il lavoro è stato accettato; non è la consegna completata o l'addebito finale.

job-001/submission.json · abbreviato
{
  "id": "job_example",
  "source": "youtube_download",
  "status": "pending",
  "usage": {
    "credits": 0
  }
}

3. Attendere la consegna e salvare il suo record

Salvare collect.py accanto a submit.py, o collect.sh accanto a submit.sh. Eseguire con la stessa cartella job-001. Controlla il lavoro salvato una volta. Per l'in sospeso o l'elaborazione, attendere i secondi 10 ed eseguire nuovamente lo stesso comando.

Quando completato, salva delivery.json. Un reindirizzamento firmato recupera il record di consegna JSON, non il MP4; lo script lo segue senza inoltrare la chiave FlashData. Un delivery.json salvato viene riutilizzato senza un'altra richiesta API.

download-video/collect.py
# Save as download-video/collect.py, beside submit.py.
import os
import re
import sys
from urllib.parse import urlsplit

import requests
from submit import ROOT, read_json, secret


def main():
    os.umask(0o077)
    folder = sys.argv[1]
    if not re.fullmatch(r"[A-Za-z0-9_-]+", folder):
        raise ValueError("Use the saved output folder name.")
    directory = ROOT / folder
    if (directory / "delivery.json").exists():
        print("Already saved:", directory / "delivery.json")
        return
    receipt = read_json(directory / "submission.json")
    job_id = receipt["id"]
    if receipt["source"] != "youtube_download" or not re.fullmatch(r"[A-Za-z0-9_-]+", job_id):
        raise ValueError("Inspect submission.json before continuing.")
    headers = {"X-API-Key": secret("FLASHDATA_API_KEY"), "Accept": "application/json"}
    url = "https://api.flashdata.dev/v2/jobs/" + job_id

    def get(url, name, headers):
        response = requests.get(url, headers=headers, timeout=(10, 120), allow_redirects=False)
        (directory / name).write_bytes(response.content)
        (directory / (name + ".headers")).write_text(
            "\n".join(f"{k}: {v}" for k, v in response.headers.items()), encoding="utf-8")
        (directory / (name + ".http")).write_text(str(response.status_code))
        return response

    status = get(url, "job-status.json", headers)
    if status.status_code != 200:
        raise ValueError(f"HTTP {status.status_code}. Inspect job-status.json and its headers.")
    job = status.json()["job"]
    if job["id"] != job_id or job["source"] != "youtube_download":
        raise ValueError("The job does not match the saved receipt.")
    if job["status"] in ("pending", "processing"):
        print(job["status"] + ". Wait 10 seconds, then run this command again.")
        return
    if job["status"] != "completed":
        raise ValueError("Job " + job["status"] + ". Inspect job-status.json; do not resubmit.")
    result = get(url + "/results", "delivery.pending.json", headers)
    if result.status_code == 302:
        location = result.headers.get("Location", "")
        parsed = urlsplit(location)
        if parsed.scheme != "https" or not parsed.hostname or parsed.username or parsed.password:
            raise ValueError("Expected an HTTPS result URL.")
        # This URL retrieves the JSON delivery record, not the video.
        # Never forward the FlashData key to the signed storage URL.
        result = get(location, "delivery.pending.json", {})
    if result.status_code != 200:
        raise ValueError(f"HTTP {result.status_code}. Run collect.py again after resolving it.")
    delivery = result.json()
    if (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 delivery.pending.json before using the result.")
    (directory / "delivery.pending.json").replace(directory / "delivery.json")
    print("Saved:", directory / "delivery.json")
    print("Usage:", delivery.get("usage"))


if __name__ == "__main__":
    try:
        main()
    except (IndexError, KeyError, OSError, ValueError, requests.RequestException) as error:
        print("Network request failed. Keep this attempt and inspect its saved files."
              if isinstance(error, requests.RequestException) else str(error), file=sys.stderr)
        sys.exit(1)
Controllare il lavoro salvato
python collect.py job-001

Che cosa contiene delivery.json

Il risultato include file_url, file_size in byte e md5. l'utilizzo riporta la carica del lavoro completata. Tieni il record completo. Il file URL nomina il tuo oggetto S3; non rende un secchio privato pubblicamente leggibile.

job-001/delivery.json · campi illustrativi
{
  "source": "youtube_download",
  "status": "done",
  "results": [
    {
      "file_url": "https://your-media-bucket.s3.us-east-1.amazonaws.com/recipes/clip-001/jNQXAC9IVRw.mp4",
      "file_size": 1048576,
      "md5": "0123456789abcdef0123456789abcdef"
    }
  ]
}

4. Leggi l'oggetto privato e verificalo

Salvare lo script di verifica accanto agli altri script. Utilizzare l'identità AWS locale configurata con l'accesso letto all'oggetto. Lo script controlla che la consegna appartiene al secchio S3, prefisso e nome file video, quindi lo scarica a media.mp4.part.

Solo un conteggio byte corrispondente e MD5 producono media.mp4 e verified.json. La verifica in esecuzione verifica nuovamente un media.mp4 esistente localmente. Questo passaggio legge il tuo oggetto S3; non invia un altro download FlashData.

download-video/verify.py
# Save as download-video/verify.py, beside submit.py.
import hashlib
import json
import os
import re
import sys
from contextlib import closing
from datetime import datetime, timezone
from urllib.parse import urlsplit

import boto3
from submit import ROOT, read_json


def main():
    os.umask(0o077)
    folder = sys.argv[1]
    if not re.fullmatch(r"[A-Za-z0-9_-]+", folder):
        raise ValueError("Use the saved output folder name.")
    directory = ROOT / folder
    request = read_json(directory / "request.json")
    receipt = read_json(directory / "submission.json")
    job = read_json(directory / "job-status.json")["job"]
    delivery = read_json(directory / "delivery.json")
    if (request["source"] != "youtube_download" or receipt["source"] != "youtube_download"
            or job["id"] != receipt["id"] or job["source"] != "youtube_download"
            or job["status"] != "completed" or delivery.get("source") != "youtube_download"
            or delivery.get("status") != "done" or len(delivery["results"]) != 1):
        raise ValueError("Check the saved request, receipt, status and delivery.")
    storage = request["params"]["storage"]
    bucket, region, prefix = (storage[k] for k in ("storage_url", "region", "object_prefix"))
    file = delivery["results"][0]
    parsed = urlsplit(file["file_url"])
    # This recipe uses an ASCII prefix and the MP4 filename generated for the video.
    object_key = prefix + "/" + request["video_id"] + ".mp4"
    if (storage["storage_type"] != "s3" or parsed.scheme != "https"
            or parsed.netloc != bucket + ".s3." + region + ".amazonaws.com"
            or parsed.path != "/" + object_key or parsed.query or parsed.fragment
            or 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("Delivery URL, byte count or MD5 does not match this recipe's request.")
    local = directory / "media.mp4"
    pending = directory / "media.mp4.part"
    if not local.exists():
        # Boto3 uses your local AWS read identity, not the upload key sent to FlashData.
        with pending.open("xb") as output:
            s3 = boto3.client("s3", region_name=region)
            with closing(s3.get_object(Bucket=bucket, Key=object_key)["Body"]) as stream:
                while chunk := stream.read(1024 * 1024):
                    output.write(chunk)
        local = pending
    size, digest = 0, hashlib.md5(usedforsecurity=False)
    with local.open("rb") as stream:
        while chunk := stream.read(1024 * 1024):
            size += len(chunk)
            digest.update(chunk)
    if size != file["file_size"] or digest.hexdigest() != file["md5"].lower():
        raise ValueError("Size or MD5 mismatch. Keep the local file for inspection.")
    final = directory / "media.mp4"
    if local == pending:
        pending.rename(final)
    record = {
        "job_id": receipt["id"], "video_id": request["video_id"],
        "bucket": bucket, "object_key": object_key, "bytes": size, "md5": digest.hexdigest(),
        "verified_at": datetime.now(timezone.utc).isoformat(), "usage": delivery.get("usage"),
    }
    (directory / "verified.json").write_text(json.dumps(record, indent=2), encoding="utf-8")
    print("Verified:", final, "—", size, "bytes; MD5 matches.")


if __name__ == "__main__":
    try:
        main()
    except Exception as error:
        print(str(error), file=sys.stderr)
        sys.exit(1)
Verificare la consegna salvata
python verify.py job-001

Risultato di successo

Il conteggio di byte sopra è illustrativo. Ora avete il MP4 nel vostro secchio, una copia locale verificata, e verified.json che digita il file al suo lavoro ID, il video ID, la chiave dell'oggetto, il checksum e l'utilizzo segnalato.

Terminal
Verified: .../job-001/media.mp4 — 1048576 bytes; MD5 matches.

Riprendi senza un secondo download

Che cosa è successo?Prossima azione
La sottomissione è stata aggiornata o nessun lavoro ID è stato salvatoMantenere il lavoro-001 e controllare History utilizzando il suo timestamp e video. Non eliminare la cartella per forzare un'altra presentazione. Recuperare il lavoro originale prima di decidere se è necessaria una nuova richiesta.
Pending / elaborazioneAttendere i secondi 10, quindi eseguire la riscossione con job-001. Legge solo il lavoro esistente.
Lavoro fallitoIspezionare job-status.json per l'errore. Fissare la configurazione video o di archiviazione prima di avviare esplicitamente un nuovo lavoro in una nuova cartella e prefisso.
401 / 403 / 402 / 429Controllare la chiave, il permesso o l'equilibrio. Per 429, leggere Retry-After nelle intestazioni salvate e attendere. Gli script non ripropongono automaticamente la presentazione.
Rimborso del risultato fallito o della sua firma URL scadutoRicorrere raccogliere per job-001 per richiedere di nuovo il risultato esistente.
S3 AccessDeniedFissare la politica locale di lettura AWS identità o secchio. L'accesso al caricamento FlashData e l'accesso alla lettura locale sono separati.
File parziale, percorso sbagliato, conteggio byte o MD5Mantenere la consegna salvata e file per l'ispezione. Per una nuova S3 leggere dopo aver risolto la causa, spostare media.mp4.part da parte, quindi eseguire la verifica. Non riscattatevi.