Перейти до вмісту
UK
Отримати ключ API
Переглянути документацію

Приклади

Збагатити файл відео IDs

Увімкніть файл YouTube ID у метадані JSON та CSV з одним результатом за відео. Використовуйте Python або Bash з FlashData CLI.

На цій сторінці

Перед тим, як початися

Використовуйте FlashData CLI v1.2.1 на PATH, плюс Python 3.10+ (тільки стандартна бібліотека), або Bash з jq і OpenSSL. Обидві версії використовують CLI для завантаження, відновлення роботи та ретривального результату. На Windows використовується Git Bash для версії Bash.

Вам потрібно власник API ключ з дозволом youtube_metadata і доступним кредитом. Зробіть свій збережений логін власника, або запустіть auth login один раз і введіть ключ на його приховану підказку. Агенти можуть поставляти FLASHDATA_API_KEY з свого секретного магазину.

Ці приклади використовують профіль CLI і каталог стану. Зберігати цей самий обліковий запис і збережений стан для відновлення. Якщо auth status показує тимчасовий доступ, перед тим як розпочати Bulk.

Тільки якщо ви не втрачили логін власника
flashdata auth login
Перевірити доступ і вартість цього двовідео прикладу
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. Приготувати відео IDs

Створюйте папку-опитування та зберігайте video-ids.txt. Відкрийте термінал в цій папці. Використовуйте один 11-character ID за лінію, без заголовка, порожні лінії або повний YouTube URLs.

Виберіть один скрипт підготовки і зберегти його біля video-ids.txt. Відхилено недійсним і дублікатом IDs, потім зберігає нормалізовану вводну знімку, параметри метаданих і запуск ID під prepared/. Збережено порядок введення.

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)
Запуск з об'ємної обробки /
python prepare.py videos-001

Що готується

Expect Приготований 2 унікальний відео для відео-001. Зберігати готовий/змінити. Метадані використовує include_formats: false і include_chapters: false. Кожен прийнятий відео є окремим вексельним елементом; дублікати рядків будуть оброблятися окремо, тому цей рецепт зупиняється перед їх поданням.

Використовуйте запуск ID, який ви не використовували для іншого завдання. Зберігати відео-001 для цього завдання речення і відновлення. Новий запуск ID призначений для навмисного нового набору даних або оновлення.

2. Відправити і збирати результати

Заощаджуйте process.py або process.sh в об'ємному об'ємі до його запуску. CLI створює одну з завдань Bulk, що додає підготовлену IDs, запускає обробку і зберігає кожен результат в bulk-results.ndjson. Займається локальна очікування після протоколу 30; триває робота сервера.

Кожна спроба отримує власну папку за спробами /, з чеком CLI, помилкою та збереженою працею. ready.txt вказує на останній результат. Exit 2 означає повне результати включають невдалі відео; продовжувати експортувати і перевіряти ці рядки.

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)
Процес підготовленого файлу
python process.py submit

Перевірити прогрес з іншого терміналу

Запуск з об'ємної обробки з таким же обліковим записом CLI. Стан показує збережену роботу і прочитає її віддалену роботу Bulk, коли доступний ID. Це не створює або відновлює роботу.

Читання поточного прогресу
python process.py status

3. Консультування та експорт

Заощаджуйте export.py або export.sh біля інших скриптів, потім запустіть його. Він перевіряє збережений хід і вхідний хеш, потім відповідає кожному результаті нульового індексу і video_id. З замовлень можна приїхати з замовлення. Випробування, дублікати або незрівняні рядки зупиняють експорт.

Експортер зберігає об'єкт повного метаданих, помилки та використання даних для кожного рядка. Непроблемні відео, що залишаються видимими з metadata: null. Цей невеликий приклад завантажує результати в пам'ять; використовувати аудит потокового передавання в файлах Bulk для великого набору даних.

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)
Експорт локально · немає API
python export.py

Використовуйте експортовані файли

Успіх друкує резюме і збережені імена файлів. Експорт виходів 0, коли кожен відео вдалося, 2, коли хтось не вдалося, або 1 при виконанні перевірки або запису не вдалося. Збережено існуючий експорт/збереження; читати його локально замість перевипуску.

Файл під експорт/Використовуйте його для
videos.jsonІмпорт у ваш процес роботи або агента. Пороги зберігають порядок введення, метадані, помилки та використання.
videos.csvПерегляд заголовків, тривалостей і збоїв у таблиці. Формула-подібний текст прописується апотрофією; JSON зберігає оригінальний текст.
summary.jsonПеревірити покриття і кількість completed/failed, пов'язаних з запуском ID і Bulk ID.
failed-video-ids.txtОгляд тільки підтверджено невдалі відео перед відмовою на іншому платному запиті. Помилки, коли все вдалося.
Читати збережені резюме та метадані
python -m json.tool export/summary.json
python -m json.tool export/videos.json

Приклад результату з невдалим відео

Ілюстрація videos.json Вирізка. Закінчена робота Bulk може містити незрівняні відео. Не лікуйте відео, як порожній результат, так і безшумно опустіть його з вашого набору даних.

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

Відновити те ж саме роботу

Якщо очікування припинили або результат, не можна прочитати, запустіть відновлення. Збирає існуючу роботу в папку свіжої спроби та оновлення ready.txt тільки після завершення ретривального. Не завантажуйте або подайте заміну роботи. Після чого експортер не був створений, якщо експортувати / ще не був створений.

Збережений результатПопередня дія
bulk_item_failuresЕкспорт та огляд failed-video-ids.txt. Не відшкодувати всі успішні відео.
partial_resultЗбережіть частковий файл. Відновити той самий курс, щоб отримати всі частини до експорту.
running / finalizingЗа допомогою одного запуску ID, профілю та державного каталогу.
pausedЧитайте pauseReason в статусі, зафіксуйте причину, потім явно відновіть, що Bulk ID за допомогою керівництва управління.
awaiting_upload / bulk_input_requiredОглянути збережений проект. Завантажте оригінальний підготовлений файл і запустіть існуючий Bulk ID; відновлення не повторює ці дії.
Неперевірити подання або відсутність віддаленого IDЗберігайте роботу і перевірте збережену помилку і Bulk Новий запуск ID може створити ще одну роботу.
Wrong джерело, відсутні ряди або вхід має неправильнийНе прийнято експорт. Перевірити підготовлений знімок, збережений файл запуску та результат; не впускати відсутні метадані.
Інспекція, після чого відновити існуючу роботу
python process.py status
python process.py recover

Заощаджуйте цей знімок або освіжайте його навмисно

Заощаджуйте завершені результати у вікні затримки 24-години. Ваші експорти залишаються локальними файлами для повторного використання. Щоб оновити метадані пізніше, скористайтеся новою папкою та запустіть ID, а також спочатку переглядайте вартість запиту.