Überspringen zum Inhalt
DE
API-Schlüssel
Dokumentation durchsuchen

Beispiele

Anreichern einer Videodatei IDs

Verwandeln Sie eine YouTube ID-Datei in Metadaten JSON und CSV, mit einem Ergebnis pro Video. Verwenden Sie Python oder Bash mit dem FlashData CLI.

Auf dieser Seite

Bevor Sie anfangen

Verwenden Sie FlashData CLI v1.2.1 auf PATH, plus Python 3.10+ (nur Standardbibliothek) oder Bash mit jq und OpenSSL. Beide Versionen verwenden den CLI für Upload, Job Recovery und Retrieval von Ergebnisteilen. Verwenden Sie unter Windows Git Bash für die Bash-Version.

Sie benötigen einen Besitzer-API-Schlüssel mit youtube_metadata-Berechtigung und verfügbaren Credits. Verwenden Sie Ihr gespeichertes Besitzer-Login erneut oder führen Sie auth login einmal aus und geben Sie den Schlüssel in der versteckten Eingabeaufforderung ein. Agenten können FLASHDATA_API_KEY aus ihrem Geheimladen liefern.

Diese Beispiele verwenden das Standard-CLI-Profil und das Zustandsverzeichnis. Behalten Sie das gleiche Konto und gespeicherten Zustand für die Wiederherstellung. Wenn auth status einen temporären Zugriff anzeigt, fordern Sie ihn an, bevor Sie Bulk starten.

Nur wenn Sie kein gespeichertes Besitzer-Login haben
flashdata auth login
Überprüfen Sie den Zugriff und die Kosten dieses Zwei-Video-Beispiels
flashdata --version
flashdata auth status --json
flashdata account balance --json
flashdata account pricing --source youtube_metadata --request-count 2 --json
flashdata account limits --json

1. Bereiten Sie das Video IDs vor

Erstellen Sie einen Ordner zur Massenanreicherung und speichern Sie dort video-ids.txt. Öffnen Sie ein Terminal in diesem Ordner. Verwenden Sie ein 11-Zeichen ID pro Zeile, ohne Kopfzeile, leere Zeilen oder volles YouTube URLs.

Wählen Sie ein Vorbereitungsskript und speichern Sie es neben video-ids.txt. Es lehnt ungültige und doppelte IDs ab und speichert dann einen normalisierten Eingabe-Snapshot, Metadatenoptionen und die Ausführung von ID unter prepared/. Die Eingabereihenfolge bleibt erhalten.

bulk-enrichment/video-ids.txt
jNQXAC9IVRw
dQw4w9WgXcQ
bulk-enrichment/prepare.py
# Save as bulk-enrichment/prepare.py. Python 3.10+, standard library only.
import hashlib
import json
import os
import re
import sys
from pathlib import Path
from subprocess import run, CalledProcessError, DEVNULL

ROOT = Path(__file__).resolve().parent
try:
    os.umask(0o077)
    run_id = sys.argv[1]
    if not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9_.:@+-]{0,159}", run_id):
        raise ValueError("Choose a valid, stable run ID.")
    ids = (ROOT / "video-ids.txt").read_text(encoding="utf-8-sig").splitlines()
    ids = [line.strip() for line in ids]
    if not ids or any(not re.fullmatch(r"[A-Za-z0-9_-]{11}", value) for value in ids):
        raise ValueError("Use one 11-character video ID per line, with no blank rows or URLs.")
    if len(set(ids)) != len(ids):
        raise ValueError("Remove duplicate IDs before submitting; they would be processed separately.")
    data = ("\n".join(ids) + "\n").encode("utf-8")
    prepared = ROOT / "prepared"
    prepared.mkdir(mode=0o700)  # Refuse to overwrite an existing input snapshot.
    (prepared / "video-ids.txt").write_bytes(data)
    (prepared / "options.json").write_text(json.dumps({
        "include_formats": False, "include_chapters": False,
    }, indent=2), encoding="utf-8")
    if os.name == "nt":
        # The CLI requires a private options file, including on Windows.
        command = """
$ErrorActionPreference = 'Stop'
$path = [System.IO.Path]::GetFullPath("./prepared/options.json")
$user = [System.Security.Principal.WindowsIdentity]::GetCurrent().User
$acl = [System.Security.AccessControl.FileSecurity]::new()
$acl.SetAccessRuleProtection($true, $false)
$acl.AddAccessRule([System.Security.AccessControl.FileSystemAccessRule]::new($user, 'FullControl', 'Allow'))
[System.IO.File]::SetAccessControl($path, $acl)
"""
        run(["powershell.exe", "-NoProfile", "-NonInteractive", "-Command", command],
            cwd=ROOT, stdin=DEVNULL, check=True, capture_output=True)
    plan = {"run_id": run_id, "source": "youtube_metadata", "input_count": len(ids),
            "input_sha256": hashlib.sha256(data).hexdigest()}
    (prepared / "plan.json").write_text(json.dumps(plan, indent=2), encoding="utf-8")
    print("Prepared", len(ids), "unique videos for", run_id)
except (IndexError, OSError, ValueError, CalledProcessError) as error:
    print(str(error), file=sys.stderr)
    sys.exit(1)
Aus der Schüttgutanreicherung/
python prepare.py videos-001

Was ist vorbereitet

Erwarten Sie vorbereitete 2 einzigartige Videos für Videos-001. Halten Sie sich vorbereitet / unverändert. Metadaten verwenden include_formats: false und include_chapters: false. Jedes akzeptierte Video ist ein separater abrechenbarer Artikel; doppelte Zeilen würden separat verarbeitet, so dass dieses Rezept vor dem Einreichen gestoppt wird.

Verwenden Sie eine Ausführung von ID, die Sie nicht für eine andere Aufgabe verwendet haben. Bewahren Sie Videos-001 für die Wiederholungen und Wiederherstellungen dieser Aufgabe auf. Ein neuer Lauf ID ist für einen absichtlichen neuen Datensatz oder eine Aktualisierung.

2. Einreichen und Sammeln der Ergebnisse

Speichern Sie process.py oder process.sh in der Massenanreicherung, bevor Sie es ausführen. Der CLI erstellt einen Bulk-Job, lädt den vorbereiteten IDs hoch, beginnt mit der Verarbeitung und speichert jeden Ergebnisteil in bulk-results.ndjson. Die lokale Wartezeit endet nach 30 Minuten; akzeptierte Serverarbeit geht weiter.

Jeder Versuch erhält seinen eigenen Ordner unter trys/, mit dem CLI-Empfang, dem Fehler und dem gespeicherten Ablauf. ready.txt zeigt auf das letzte vollständige Ergebnis. Exit 2 bedeutet, dass vollständige Ergebnisse fehlerhafte Videos enthalten; exportieren und inspizieren Sie diese Zeilen weiter.

bulk-enrichment/process.py
# Save as bulk-enrichment/process.py. Requires the FlashData CLI on PATH.
import hashlib
import json
import os
import sys
import tempfile
from pathlib import Path
from subprocess import run, DEVNULL

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


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


def main(action):
    os.umask(0o077)
    plan = read_json(ROOT / "prepared/plan.json")
    ids = ROOT / "prepared/video-ids.txt"
    if hashlib.sha256(ids.read_bytes()).hexdigest() != plan["input_sha256"]:
        raise ValueError("The prepared input changed. Restore it before recovery.")
    # Use the same default profile and state directory as auth login/status.
    flags = ["--json", "--non-interactive"]
    def cli(*args):
        return run(["flashdata", *args, *flags], cwd=ROOT, stdin=DEVNULL,
                   capture_output=True, text=True, encoding="utf-8")
    if action == "status":
        result = cli("runs", "show", plan["run_id"])
        if result.returncode:
            raise ValueError(result.stderr)
        saved = json.loads(result.stdout)["data"]
        print(json.dumps({k: saved.get(k) for k in
                          ("id", "remoteId", "status", "stage", "errorCode")}, indent=2))
        if saved.get("remoteId"):
            result = cli("bulk", "get", saved["remoteId"])
            print(result.stdout or result.stderr)
            return result.returncode
        return 0
    if action not in ("submit", "recover"):
        raise ValueError("Choose submit, status or recover.")
    attempts = ROOT / "attempts"
    attempts.mkdir(exist_ok=True)
    directory = Path(tempfile.mkdtemp(prefix="run-", dir=attempts))
    output = str(directory / "bulk-results.ndjson")
    if action == "submit":
        args = ["bulk", "run", "--source", plan["source"], "--input", str(ids),
                "--options", str(ROOT / "prepared/options.json"), "--run-id", plan["run_id"]]
    else:
        args = ["runs", "recover", plan["run_id"]]
    result = cli(*args, "--output", output, "--timeout", "30m")
    (directory / "receipt.json").write_text(result.stdout, encoding="utf-8")
    (directory / "error.json").write_text(result.stderr, encoding="utf-8")
    (directory / "exit-code.txt").write_text(str(result.returncode))
    print("Attempt:", directory.relative_to(ROOT))
    # bulk_item_failures still includes a complete result file with failed rows.
    code = json.loads(result.stderr).get("error", {}).get("code") if result.stderr.strip() else None
    if result.returncode and code != "bulk_item_failures":
        raise ValueError("Collection stopped. Inspect error.json; recover the same run.")
    saved = cli("runs", "show", plan["run_id"])
    (directory / "run.json").write_text(saved.stdout, encoding="utf-8")
    if saved.returncode or not Path(output).is_file():
        raise ValueError("Could not save the run record and results together.")
    record = json.loads(saved.stdout)
    data = record.get("data", {})
    if (not record.get("ok") or data.get("status") != "succeeded"
            or data.get("id") != plan["run_id"] or data.get("source") != plan["source"]
            or data.get("inputFileHash") != plan["input_sha256"]):
        raise ValueError("Inspect the run/input binding before exporting.")
    pointer = ROOT / "ready.next"
    pointer.write_text(directory.relative_to(ROOT).as_posix(), encoding="utf-8")
    pointer.replace(ROOT / "ready.txt")
    print("Results ready for export." if code is None else "Results ready; inspect failed video rows.")
    return 2 if code == "bulk_item_failures" else 0


if __name__ == "__main__":
    try:
        sys.exit(main(sys.argv[1]))
    except (IndexError, KeyError, OSError, ValueError) as error:
        print(str(error), file=sys.stderr)
        sys.exit(1)
Verarbeiten Sie die vorbereitete Datei
python process.py submit

Überprüfen Sie den Fortschritt von einem anderen Terminal

Führen Sie von der Massenanreicherung mit dem gleichen CLI-Konto aus. Die Statusaktion zeigt den gespeicherten Lauf an und liest den entfernten Bulk-Job, wenn ein ID verfügbar ist. Es schafft oder nimmt die Arbeit nicht wieder auf.

Lesen Sie aktuelle Fortschritte
python process.py status

3. Abgleich und Ausfuhr

Speichern Sie export.py oder export.sh neben den anderen Skripten und führen Sie es aus. Es überprüft den gespeicherten Run- und Input-Hash und passt dann jedes Ergebnis mit dem Null-basierten Index und video_id ab. Ergebnisteile können ausgefallen sein. Fehlende, doppelte oder nicht übereinstimmende Zeilen stoppen den Export.

Der Exporteur behält das vollständige Metadatenobjekt, den Fehler und die gemeldete Verwendung für jede Zeile. Gescheiterte Videos bleiben mit metadata: null sichtbar. Dieses kleine Beispiel lädt die Ergebnisse in den Speicher; Verwenden Sie das Streaming-Audit in der Bulk-Dateiverarbeitung für einen großen Datensatz.

bulk-enrichment/export.py
# Save as bulk-enrichment/export.py. Local files only; no API calls.
import csv
import hashlib
import json
import os
import re
import sys
from pathlib import Path

ROOT = Path(__file__).resolve().parent
try:
    os.umask(0o077)
    directory = (ROOT / "ready.txt").read_text(encoding="utf-8").strip()
    if not re.fullmatch(r"attempts/run-[A-Za-z0-9_-]+", directory):
        raise ValueError("Use the ready.txt written by process.py or process.sh.")
    directory = ROOT / directory
    def read_json(path):
        return json.loads(path.read_text(encoding="utf-8"))
    plan = read_json(ROOT / "prepared/plan.json")
    raw = (ROOT / "prepared/video-ids.txt").read_bytes()
    ids = raw.decode("utf-8").splitlines()
    saved = read_json(directory / "run.json")
    run = saved["data"]
    digest = hashlib.sha256(raw).hexdigest()
    if (not saved.get("ok") or run.get("status") != "succeeded" or run.get("kind") != "bulk:run"
            or run.get("id") != plan["run_id"] or run.get("source") != "youtube_metadata"
            or run.get("inputFileHash") != digest or plan["input_sha256"] != digest
            or plan["input_count"] != len(ids) or not run.get("remoteId")):
        raise ValueError("The saved run does not match this input file.")
    # This recipe loads a small file into memory to validate it before writing exports.
    records = {}
    with (directory / "bulk-results.ndjson").open(encoding="utf-8") as source:
        for line in source:
            row = json.loads(line)
            index = row.get("index")
            if (type(index) is not int or not 0 <= index < len(ids) or index in records
                    or row.get("video_id") != ids[index] or row.get("source") != "youtube_metadata"
                    or row.get("status") not in ("completed", "failed")):
                raise ValueError("Unknown, duplicate or mismatched result row.")
            metadata = None
            if row["status"] == "completed":
                results = row.get("results")
                if (not isinstance(results, list) or len(results) != 1
                        or not isinstance(results[0], dict) or results[0].get("videoId") != ids[index]):
                    raise ValueError("Completed metadata does not match its video.")
                metadata = results[0]
            records[index] = {
                "index": index, "video_id": ids[index], "status": row["status"],
                "metadata": metadata, "error": row.get("error"), "usage": row.get("usage"),
            }
    if len(records) != len(ids):
        raise ValueError("Missing result rows. Recover the same run before exporting.")
    videos = [records[index] for index in range(len(ids))]
    failed = [v["video_id"] for v in videos if v["status"] == "failed"]
    output = ROOT / "export"
    output.mkdir(mode=0o700)  # Never overwrite an earlier export.
    (output / "videos.json").write_text(json.dumps(videos, ensure_ascii=False, indent=2), encoding="utf-8")
    def cell(value):
        if value is None:
            return ""
        if not isinstance(value, str):
            value = json.dumps(value, ensure_ascii=False, separators=(",", ":"))
        # Keep remote text from being interpreted as a spreadsheet formula.
        return "'" + value if re.match(r"^[ \t\r\n]*[=+@-]|^[\t\r\n]", value) else value
    with (output / "videos.csv").open("x", encoding="utf-8", newline="") as target:
        writer = csv.writer(target)
        writer.writerow(["index", "video_id", "status", "title", "duration", "error"])
        for video in videos:
            metadata = video["metadata"] or {}
            writer.writerow([cell(v) for v in (video["index"], video["video_id"], video["status"],
                            metadata.get("title"), metadata.get("duration"), video["error"])])
    (output / "failed-video-ids.txt").write_bytes("".join(v + "\n" for v in failed).encode("utf-8"))
    summary = {"run_id": plan["run_id"], "bulk_id": run["remoteId"], "input_count": len(ids),
               "completed": len(ids) - len(failed), "failed": len(failed), "coverage_complete": True}
    (output / "summary.json").write_text(json.dumps(summary, indent=2), encoding="utf-8")
    print(json.dumps(summary, indent=2))
    print("Saved export/videos.json, videos.csv and failed-video-ids.txt")
    sys.exit(2 if failed else 0)
except (OSError, ValueError, KeyError, TypeError) as error:
    print(str(error), file=sys.stderr)
    sys.exit(1)
Lokal exportieren · keine API Anrufe
python export.py

Verwenden Sie die exportierten Dateien

Success druckt die Zusammenfassung und die gespeicherten Dateinamen. Exportieren Sie 0, wenn jedes Video erfolgreich war, 2, wenn einige fehlgeschlagen sind, oder 1, wenn die Validierung oder das Schreiben fehlgeschlagen ist. Ein bestehender Export / bleibt erhalten; lesen Sie ihn lokal, anstatt die Einreichung erneut auszuführen.

Datei unter Export/Verwenden Sie es für
videos.jsonImportieren Sie in Ihre App oder Agent Workflow. Zeilen behalten Eingabereihenfolge, Metadaten, Fehler und Nutzung.
videos.csvÜberprüfen Sie Titel, Dauer und Fehler in einer Tabelle. Formelähnlicher Text wird mit einem Apostroph vorangestellt; JSON behält den Originaltext bei.
summary.jsonÜberprüfen Sie die Abdeckung und die completed/failed-Zählung, die mit dem Lauf ID und Bulk ID verknüpft ist.
failed-video-ids.txtDie Überprüfung bestätigte nur fehlgeschlagene Videos, bevor sie sich für eine andere bezahlte Anfrage entschied. Leere, wenn alles gelungen ist.
Lesen Sie die gespeicherte Zusammenfassung und Metadaten
python -m json.tool export/summary.json
python -m json.tool export/videos.json

Beispielergebnis mit einem fehlgeschlagenen Video

Beispielhafter videos.json-Auszug. Ein abgeschlossener Bulk-Job kann fehlgeschlagene Videos enthalten. Behandeln Sie ein fehlgeschlagenes Video nicht als leeres erfolgreiches Ergebnis oder lassen Sie es stillschweigend aus Ihrem Datensatz fallen.

export/videos.json
[
  {
    "index": 0,
    "video_id": "jNQXAC9IVRw",
    "status": "completed",
    "metadata": {
      "videoId": "jNQXAC9IVRw",
      "title": "Example video",
      "duration": 19
    },
    "error": null,
    "usage": null
  },
  {
    "index": 1,
    "video_id": "dQw4w9WgXcQ",
    "status": "failed",
    "metadata": null,
    "error": {
      "code": "example_video_unavailable"
    },
    "usage": null
  }
]

Den gleichen Job wiederherstellen

Wenn das Warten gestoppt wurde oder ein Ergebnisteil nicht gelesen werden konnte, führen Sie die Wiederherstellung aus. Es sammelt den vorhandenen Job in einem neuen Versuchsordner und aktualisiert ready.txt erst nach vollständigem Abruf. Es werden keine Ersatzarbeiten hochgeladen oder eingereicht. Führen Sie dann den Exporteur aus, wenn der Export / noch nicht erstellt wurde.

Gespeichertes ErgebnisNächste Maßnahme
bulk_item_failuresExportieren und überprüfen Sie failed-video-ids.txt. Nicht alle erfolgreichen Videos erneut einreichen.
partial_resultBewahren Sie die Teildatei. Stellen Sie den gleichen Lauf wieder her, um alle Teile vor dem Export abzurufen.
running / finalizingWiederherstellen Sie später mit dem gleichen Lauf ID, Profil und Zustandsverzeichnis.
pausedLesen Sie pauseReason im Status, beheben Sie die Ursache und setzen Sie dann Bulk ID mithilfe des Steuerhandbuchs explizit fort.
awaiting_upload / bulk_input_requiredÜberprüfen Sie den gespeicherten Entwurf. Laden Sie die ursprünglich vorbereitete Datei hoch und starten Sie die vorhandene Bulk ID; die Wiederherstellung wiederholt diese Aktionen nicht.
Unsichere Übermittlung oder keine Remote-IDHalten Sie den Lauf und überprüfen Sie den gespeicherten Fehler und Bulk Jobs, bevor Sie erneut versuchen. Ein neuer Lauf ID kann einen anderen Job erstellen.
Falsche Quelle, fehlende Zeilen oder Input-Hash-MismatchEs wird kein Export akzeptiert. Überprüfen Sie die vorbereitete Snapshot-, gespeicherte Run- und Ergebnisdatei; erfinden Sie keine fehlenden Metadaten.
Inspizieren und anschließend vorhandene Arbeit wiederherstellen
python process.py status
python process.py recover

Speichern Sie diesen Snapshot oder aktualisieren Sie ihn absichtlich

Speichern Sie abgeschlossene Ergebnisse innerhalb des 24-Stunden-Retentionsfensters. Ihre Exporte bleiben lokale Dateien zur Wiederverwendung. Um Metadaten später zu aktualisieren, verwenden Sie einen neuen Arbeitsordner und führen Sie ID aus, und überprüfen Sie zuerst die Kosten für die neue Anforderung.