Pular para o conteúdo
PT
Obter chave API
Explorar documentação

Exemplos

Enriqueça um arquivo de vídeo IDs

Transforme um arquivo YouTube ID em metadados JSON e CSV, com um resultado por vídeo. Use Python ou Bash com FlashData CLI.

Nesta página

Antes de começar

Use FlashData CLI v1.2.1 no PATH, mais Python 3.10+ (apenas biblioteca padrão), ou Bash com jq e OpenSSL. Ambas as versões usam o CLI para upload, recuperação de trabalho e recuperação de parte de resultado. Em Windows, use Git Bash para a versão Bash.

Você precisa de uma chave API com permissão youtube_metadata e créditos disponíveis. Reutilize seu login de proprietário salvo, ou execute auth login uma vez e digite a chave em seu prompt oculto. Agentes podem fornecer FLASHDATA_API_KEY de sua loja secreta.

Estes exemplos usam o perfil padrão CLI e diretório de estado. Mantenha a mesma conta e salve o estado para recuperação. Se auth status mostrar acesso temporário, reclame antes de iniciar Bulk.

Só se você não tiver o login do proprietário salvo
flashdata auth login
Verifique o acesso e o custo deste exemplo de dois 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. Prepare o vídeo IDs

Crie uma pasta de enriquecimento e salve o video-ids.txt lá. Abra um terminal nessa pasta. Use um 11 ID por linha, sem cabeçalho, linhas em branco ou YouTube URLs completo.

Escolha um script de preparação e guarde ao lado do video-ids.txt. Rejeita IDs inválido e duplicado, então salva um instantâneo de entrada normalizado, opções de metadados e a execução ID sob prepared/. A ordem de entrada está preservada.

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)
Fuja de grande enriquecimento
python prepare.py videos-001

O que está preparado

Esperar vídeos únicos de 2 para vídeos-001. Mantenha-se preparado e inalterado. Metadados usam include_formats: false e include_chapters: false. Cada vídeo aceito é um item bitável separado, linhas duplicadas seriam processadas separadamente, então esta receita para antes de submetê-los.

Use uma corrida ID que você não usou para uma tarefa diferente. Guarde vídeos-001 para as tentativas e recuperação desta tarefa. Uma nova execução ID é para um novo conjunto de dados intencional ou atualização.

2. Submeta-se e recolha os resultados

Salve process.py ou process.sh em grande enriquecimento antes de executá-lo. O CLI cria um trabalho Bulk, faz upload do IDs preparado, começa a processar e salva cada parte do resultado em bulk-results.ndjson. A espera local para depois de 30 minutos; o trabalho do servidor aceito continua.

Cada tentativa tem sua própria pasta sob tentativas /, com o CLI Recibo, erro e execução salva. ready.txt aponta para o último resultado completo. Sair do 2 significa que os resultados completos incluem vídeos fracassados, continuar a exportar e inspecionar essas linhas.

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)
Processe o arquivo preparado
python process.py submit

Verifique o progresso de outro terminal

Fuja do enriquecimento com a mesma conta CLI. A ação de status mostra a execução salva e lê seu trabalho remoto Bulk quando um ID está disponível. Ele não cria ou retoma o trabalho.

Leia o progresso atual
python process.py status

3. Reconcile e exporte

Salve export.py ou export.sh ao lado dos outros scripts, então execute-o. Ele verifica o haxixe de entrada e execução salva, então corresponde a todos os resultados por índice zero e video_id. As partes do resultado podem chegar fora de ordem. Desaparecidos, duplicados ou linhas desiguais param a exportação.

O exportador mantém o objeto completo de metadados, erro e o uso relatado para cada linha. Vídeos fracassados ficam visíveis com metadata: null. Este pequeno exemplo carrega os resultados em memória, use a auditoria de streaming no processamento de arquivos Bulk para um grande conjunto de dados.

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 · sem chamadas API
python export.py

Use os arquivos exportados

O sucesso imprime o resumo e salva nomes de arquivos. Exportar sai 0 quando cada vídeo foi bem sucedido, 2 quando alguns falharam, ou 1 quando a validação ou escrita falhou. Uma exportação existente está preservada, leia-a localmente em vez de repetir a submissão.

Arquivo sob exportaçãoUse-o para
videos.jsonImportar para o seu fluxo de trabalho de aplicativo ou agente. Linhas mantêm a ordem de entrada, metadados, erros e uso.
videos.csvRevise títulos, durações e falhas em uma planilha. Texto tipo fórmula é prefixado com um apóstrofo; JSON mantém o texto original.
summary.jsonVerifique a cobertura e a conta completed/failed, ligada à corrida ID e Bulk ID.
failed-video-ids.txtA revisão só confirmou os vídeos fracassados antes de decidir sobre outro pedido pago. Vazio quando tudo foi bem sucedido.
Leia o resumo salvo e metadados
python -m json.tool export/summary.json
python -m json.tool export/videos.json

Resultado do exemplo com um vídeo fracassado

Excerto ilustrativo do videos.json. Um trabalho Bulk completo pode conter vídeos fracassados. Não trate um vídeo fracassado como um resultado de sucesso vazio ou solte-o silenciosamente de seu conjunto de dados.

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

Recupere o mesmo trabalho

Se a espera parou ou uma parte do resultado não pôde ser lida, corra para se recuperar. Coleta o trabalho existente em uma nova pasta de tentativas e atualiza ready.txt somente após a recuperação completa. Não faz upload ou submete trabalhos de substituição. Então execute o exportador se a exportação / ainda não foi criado.

Resultado salvoPróxima ação
bulk_item_failuresExportar e revisar failed-video-ids.txt. Não reenvie todos os vídeos de sucesso.
partial_resultPreservar o arquivo parcial. Recupere a mesma corrida para recuperar todas as partes antes de exportar.
running / finalizingRecupere-se mais tarde usando o mesmo ID, perfil e diretório de estado.
pausedLeia pauseReason em status, conserte a causa, e então reinicie explicitamente que Bulk ID usando o guia de controle.
awaiting_upload / bulk_input_requiredInspecione o rascunho salvo. Envie o arquivo original preparado e comece o Bulk ID existente; a recuperação não reproduz essas ações.
Submissão incerta ou sem ID remotoMantenha a corrida e inspecione o erro salvo e Bulk Jobs antes de tentar novamente. Uma nova corrida ID pode criar outro trabalho.
Fonte errada, falta de linhas ou input hash mismatchNenhuma exportação é aceita. Verifique o instantâneo preparado, o arquivo de execução e resultado salvo; não invente metadados perdidos.
Inspecione e recupere o trabalho existente
python process.py status
python process.py recover

Guarde esta foto ou refresque-a deliberadamente

Economize resultados completos na janela de retenção 24-hora. Suas exportações permanecem arquivos locais para reutilização. Para atualizar os metadados mais tarde, use uma nova pasta de trabalho e execute ID, e reveja o novo custo da solicitação primeiro.