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

Przykłady

Wzbogacenie pliku wideo IDs

Przekręć plik YouTube ID w metadane JSON i CSV, z jednym wynikiem na wideo. Python lub Bash z FlashData CLI.

Na tej stronie

Zanim zaczniesz

Użyj FlashData CLI v1.2.1 na PATH, plus Python 3.10 + (tylko standardowa biblioteka), lub Bash z jq i OpenSSL. Obie wersje wykorzystują CLI do wysyłania, odzyskiwania zadań i pobierania części wynikowej. Na Windows, użyj Git Bash dla wersji Bash.

Potrzebujesz właściciela klucza API z pozwoleniem youtube_metadata i dostępnymi kredytami. Ponownie użyj zapisanego logowania właściciela, lub uruchom auth login raz i wprowadź klucz w ukrytym trybie. Agenci mogą dostarczyć FLASHDATA_API_KEY ze swojego tajnego sklepu.

Przykłady te używają domyślnego profilu CLI i katalogu stanu. Zachowaj to samo konto i uratuj stan do odzyskania. Jeżeli auth status wykazuje tymczasowy dostęp, należy go zgłosić przed rozpoczęciem stosowania Bulk.

Tylko jeśli nie masz zapisanego logowania właściciela
flashdata auth login
Sprawdź dostęp i koszt tego dwuwideo przykładu
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. Przygotuj wideo IDs

Utwórz folder wzbogacania masy i zapisz tam video-ids.txt. Otwórz terminal w tym folderze. Użyj jednego znaku 11- ID na linię, bez nagłówka, pustych linii lub pełnego YouTube URLs.

Wybierz jeden skrypt przygotowania i zapisz go obok video-ids.txt. Odrzuca nieprawidłowy i duplikat IDs, a następnie zapisuje znormalizowane migawki wejściowe, opcje metadanych i uruchomić ID pod prepared/. Zamówienie jest zachowane.

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)
Uruchom od wzbogacania luzem /
python prepare.py videos-001

Co jest przygotowane

Oczekuj Gotowe 2 unikalne filmy do video-001. Należy być przygotowanym / niezmienionym. Metadane wykorzystują include_formats: false i include_chapters: false. Każdy zaakceptowany film wideo jest oddzielnym elementem billable; duplikaty linie będą przetwarzane oddzielnie, więc przepis ten zatrzymuje się przed ich przesłaniem.

Użyj uruchomienia ID, którego nie użyłeś do innego zadania. Zachowaj video-001 do tego zadania powtórki i odzyskiwania. Nowy bieg ID jest dla zamierzonego nowego zbioru danych lub odświeżenia.

2. Prześlij i zbieraj wyniki

Przed uruchomieniem należy zapisać process.py lub process.sh w wzbogaceniu luzem. CLI tworzy jedno zadanie Bulk, przesyła przygotowany IDs, rozpoczyna przetwarzanie i zapisuje każdą część wyniku do bulk-results.ndjson. Lokalne oczekiwania zatrzymują się po minutach 30; akceptowana praca serwera trwa.

Każda próba uzyskania własnego folderu pod próbą /, z paragonem CLI, błędem i zapisanym uruchomieniem. ready.txt wskazuje na ostatni kompletny wynik. Wyjście 2 oznacza kompletne wyniki obejmują nieudany film; kontynuować eksport i kontrolę tych wierszy.

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)
Przetwarzanie przygotowanego pliku
python process.py submit

Sprawdź postęp z innego terminala

Uruchom od wzbogacania luzem z tym samym kontem CLI. Akcja statusu pokazuje zapisany przebieg i odczytuje swoje zdalne zadanie Bulk, kiedy jest dostępny ID. Nie tworzy ani nie wznawia pracy.

Czytaj bieżący postęp
python process.py status

3. Reconcile i eksport

Zapisz export.py lub export.sh obok innych skryptów, a następnie uruchom go. Sprawdza zapisany przebieg i wejście hash, a następnie dopasowuje każdy wynik przez indeks zerowy i video_id. Rezultaty mogą wyjść z porządku. Zaginione, duplikowane lub niedopasowane wiersze zatrzymują wywóz.

Eksporter zachowuje pełny obiekt metadanych, błąd i zgłoszone użycie dla każdego wiersza. Nieudane filmy pozostają widoczne z metadata: null. Ten mały przykład wczytuje wyniki do pamięci; użyj audytu strumieniowego w przetwarzaniu plików Bulk dla dużych zbiorów danych.

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)
Eksportuj lokalnie · bez połączeń API
python export.py

Użyj eksportowanych plików

Sukces drukuje streszczenie i zapisuje nazwy plików. Eksportuj wyjście 0, gdy każde wideo się powiodło, 2 gdy niektóre nie powiodły się, lub 1 kiedy walidacja lub pisanie nie powiodło się. Istniejący wywóz / jest zachowany; należy go przeczytać lokalnie zamiast ponownie uruchomić złożenie.

Plik w eksporcie /Użyj go do
videos.jsonImportuj do aplikacji lub agenta. Wiersze zachowują kolejność wejść, metadane, błędy i wykorzystanie.
videos.csvPrzegląd tytułów, okresów i awarii w arkuszu kalkulacyjnym. Tekst podobny do wzoru jest poprzedzony apostrofem; JSON zachowuje oryginalny tekst.
summary.jsonSprawdź zasięg i numery completed/failed, związane z uruchomieniem ID i Bulk ID.
failed-video-ids.txtPrzegląd tylko potwierdzone nieudane filmy przed podjęciem decyzji o innym płatnym wniosku. Puste, gdy wszystko się udało.
Przeczytaj zapisane podsumowanie i metadane
python -m json.tool export/summary.json
python -m json.tool export/videos.json

Przykład wyniku z nieudanym filmem

Przykładowy fragment videos.json. Zakończone zadanie Bulk może zawierać nieudane filmy. Nie należy traktować nieudanych filmów jako pustych udanych wyników ani po cichu upuszczać ich z zestawu danych.

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
  }
]

Odzyskanie tej samej pracy

Jeśli nie można odczytać części z oczekiwania lub części wyniku, uruchom recovery. Zbiera istniejące zadanie do nowego folderu prób i aktualizuje ready.txt dopiero po całkowitym odzyskaniu. Nie wysyła ani nie przekazuje prac zastępczych. Następnie uruchomić eksportera, jeśli wywóz / nie został jeszcze utworzony.

Oszczędzony wynikNastępna akcja
bulk_item_failuresEksport i przegląd failed-video-ids.txt. Nie należy ponownie wykorzystywać wszystkich udanych filmów wideo.
partial_resultZachowaj częściowy plik. Odzyskać ten sam bieg, aby odzyskać wszystkie części przed wywozem.
running / finalizingOdzyskiwanie później przy użyciu tego samego katalogu ID, profilu i stanu.
pausedPrzeczytaj pauseReason w stanie, naprawić przyczynę, a następnie wyraźnie wznowić, że Bulk ID za pomocą instrukcji obsługi.
awaiting_upload / bulk_input_requiredSprawdź zapisany szkic. Wyślij oryginał przygotowanego pliku i uruchom istniejący Bulk ID; odzysk nie powtarza tych działań.
Niepewne złożenie lub brak zdalnego IDPrzed ponownym wypróbowaniem należy zachować bieg i sprawdzić zapisany błąd oraz Bulk Jobs. Nowy bieg ID może stworzyć kolejne zadanie.
Złe źródło, brakujące wiersze lub błąd w haszu wejściowymNie przyjmuje się wywozu. Sprawdź przygotowane migawki, zapisany plik uruchom i wynik; nie wymyślaj brakujących metadanych.
Sprawdź, a następnie odzyskaj istniejącą pracę
python process.py status
python process.py recover

Zapisz to zdjęcie lub odśwież go celowo

Zapisuje ukończone wyniki w oknie retencji 24- hour. Twój eksport pozostaje lokalnymi plikami do ponownego użycia. Aby odświeżać metadane później, użyj nowego folderu roboczego i uruchom ID, a następnie najpierw przejrzyj koszt nowego żądania.