Saltar al contenido
ES
Obtener clave API
Explorar documentación

Ejemplos

Enriquece un archivo de identificadores de vídeo

Convierte un archivo de IDs de YouTube en metadatos JSON y CSV, con un resultado por vídeo. Usa Python o Bash con la CLI de FlashData.

En esta página

Antes de empezar

Necesitas FlashData CLI v1.2.1 en PATH y Python 3.10+ (solo la biblioteca estándar), o Bash con jq y OpenSSL. Ambas versiones usan la CLI para subir archivos, recuperar trabajos y obtener las partes del resultado. En Windows, usa Git Bash para la versión Bash.

Necesitas una tecla API propietario con permiso youtube_metadata y créditos disponibles. Reutiliza tu login de propietario guardado, o ejecute el login de auth una vez e introduce la llave en su mensaje oculto. Los agentes pueden suministrar FLASHDATA_API_KEY de su tienda secreta.

Estos ejemplos utilizan el perfil predeterminado CLI y el directorio estatal. Mantenga esa misma cuenta y estado guardado para la recuperación. Si el estado de auth muestra acceso temporal, reclame antes de iniciar Bulk.

Sólo si no tienes acceso al propietario guardado
flashdata auth login
Compruebe el acceso y el costo de este ejemplo de dos vídeos
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. Preparar el vídeo IDs

Cree una carpeta de enriquecimiento a granel y guarde video-ids.txt allí. Abra una terminal en esa carpeta. Utilice un 11-character ID por línea, sin un encabezado, líneas en blanco o YouTube completo URLs.

Elija un script de preparación y guardarlo junto a video-ids.txt. Rechaza IDs inválido y duplicado, a continuación, guarda una instantánea de entrada normalizada, opciones de metadatos y la ejecución ID bajo preparo/. El orden de entrada se conserva.

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)
Corresponde al enriquecimiento masivo/
python prepare.py videos-001

Lo que se prepara

Se espera preparado 2 videos únicos para videos-001. Mantener preparado/sin cambios. Metadata utiliza include_formats: falso y include_chapters: falso. Cada vídeo aceptado es un artículo de facturación independiente; líneas duplicadas se procesarían por separado, por lo que esta receta se detiene antes de enviarlos.

Utilice un ID de ejecución que no ha utilizado para una tarea diferente. Retener vídeos-001 para las retries y recuperación de esta tarea. Un nuevo ID de ejecución es para un nuevo dataset o actualización intencional.

2. Presentar y recoger los resultados

Guardar process.py o process.sh en el enriquecimiento a granel antes de ejecutarlo. El CLI crea un trabajo Bulk, carga el IDs preparado, comienza a procesar y guarda cada parte de resultado en bulk-results.ndjson. La espera local se detiene después de los minutos 30; el trabajo de servidor aceptado continúa.

Cada intento consigue su propia carpeta bajo intentos/, con el recibo CLI, error y ejecución guardada. ready.txt señala al último resultado completo. Exit 2 significa resultados completos incluyen videos fallidos; continúan exportando e inspeccionando esas filas.

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)
Procesar el archivo preparado
python process.py submit

Compruebe el progreso de otra terminal

Corre desde el enriquecimiento masivo con la misma cuenta CLI. La acción de estado muestra la ejecución guardada y lee su trabajo remoto Bulk cuando está disponible un ID. No crea ni reanuda el trabajo.

Lea el progreso actual
python process.py status

3. Reconcile and export

Guardar export.py o export.sh junto a los otros scripts, luego ejecutarlo. Chequea el hash de ejecución y entrada guardados, luego coincide con cada resultado por índice cero y video_id. Las partes del resultado pueden llegar fuera de orden.

El exportador conserva el objeto de metadatos completo, el error y el uso reportado para cada fila. Los videos fallidos permanecen visibles con metadatos: null. Este pequeño ejemplo carga los resultados en la memoria; utilice la auditoría de streaming en el procesamiento de archivos Bulk para un conjunto de datos grande.

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)
Exportar localmente · sin llamadas API
python export.py

Utilice los archivos exportados

El éxito imprime el resumen y los nombres de archivo guardados. Salidas de exportación 0 cuando cada vídeo tuvo éxito, 2 cuando algunos fallaron, o 1 cuando la validación o escritura fallaron. Se conserva una exportación/ existente; leerlo localmente en lugar de la reimpresión de la presentación.

File under export/Úsalo para
videos.jsonImporte en su aplicación o flujo de trabajo de agente. Las filas mantienen orden de entrada, metadatos, errores y uso.
videos.csvTítulos de revisión, duración y fracasos en una hoja de cálculo. El texto tipo fórmula está prefijado con un apostrofe; JSON conserva el texto original.
summary.jsonComprobar la cobertura y los recuentos completos de /failed, vinculados a la ejecución ID y Bulk ID.
failed-video-ids.txtRevisar sólo los vídeos confirmados antes de decidir sobre otra solicitud pagada. Vacío cuando todos lo lograron.
Lea el resumen guardado y los metadatos
python -m json.tool export/summary.json
python -m json.tool export/videos.json

Resultado de ejemplo con un vídeo fallido

Ilustrativo videos.json excerpt. Un trabajo Bulk completado puede contener videos fallidos. No trate un video fallido como un resultado exitoso vacío o dejarlo caer silenciosamente desde su conjunto de datos.

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

Recuperar el mismo trabajo

Si la espera se detuvo o una parte de resultado no se podía leer, ejecutar la recuperación. Recopila el trabajo existente en una carpeta de intentos frescos y actualiza ready.txt sólo después de la recuperación completa. No se carga ni presenta trabajo de reemplazo. A continuación, ejecutar el exportador si la exportación/ aún no se ha creado.

Resultado ahorradoSiguiente acción
bulk_item_failuresExportar y revisar failed-video-ids.txt. No vuelva a presentar todos los videos exitosos.
partial_resultPreserve el archivo parcial. Recuperar la misma carrera para recuperar todas las partes antes de exportar.
running / finalizingRecover later using the same run ID, profile and state directory.
pausedLea pauseReason en estado, corrija la causa, luego reanude explícitamente que Bulk ID usando la guía de control.
awaiting_upload / bulk_input_requiredInspeccione el borrador guardado. Cargue el archivo preparado original y comience el Bulk ID existente; la recuperación no vuelve a reproducir estas acciones.
Incierto de la presentación o no remoto IDMantenga la carrera e inspeccione el error guardado y Bulk Jobs antes de reintentar. Un nuevo ID puede crear otro trabajo.
Fuente incorrecta, filas faltantes o el desajuste de entradaNo se acepta ninguna exportación. Revise la instantánea preparada, el archivo de ejecución guardado y resultado; no invente metadatos perdidos.
Inspeccionar, luego recuperar el trabajo existente
python process.py status
python process.py recover

Guarda esta instantánea o refrescalo deliberadamente

Guardar los resultados completados dentro de la ventana de retención de 24. Sus exportaciones siguen siendo archivos locales para su reutilización. Para actualizar los metadatos más tarde, utilice una nueva carpeta de trabajo y ejecute ID, y revise el nuevo costo de solicitud primero.