Langkau ke kandungan
MS
Dapatkan kunci API
Semak dokumentasi

Contoh

Memkaya sebuah berkas video IDs

Tukar fail ID YouTube kepada metadata JSON dan CSV, dengan satu hasil bagi setiap video. Gunakan Python atau Bash bersama FlashData CLI.

Pada halaman ini

Sebelum kau mulai

Gunakan FlashData CLI v1.2.1 pada PATH, ditambah Python 3.10+ (pustaka standar saja), atau Bash dengan jq dan OpenSSL. Kedua versi menggunakan CLI untuk upload, pemulihan pekerjaan dan retrise-part retrieveval. On Windows, gunakan Git Bash * Untuk * Bash Version.

Anda perlu kunci API pemilik dengan izin youtube_metadata dan kredit yang tersedia. Anda menggunakan kembali log masuk pemilik tersimpan, atau jalankan auth login sekali dan masukkan kunci pada prompt tersembunyinya. Agen-agen dapat memasok FLASHDATA_API_KEY dari toko rahasia mereka.

Contoh-contoh ini menggunakan profil dan direktori keadaan CLI yang default. Simpan rekening yang sama dan simpan keadaan untuk pemulihan. ÁIf auth status menunjukkan akses sementara, mengklaimnya sebelum memulai Bulk.

Hanya jika Anda tidak memiliki log masuk pemilik tersimpan
flashdata auth login
Periksa akses dan biaya dari contoh dua video ini
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. Siapkan video IDs

Buat folder barang-barang dan simpan video-ids.txt disana. Buka terminal di dalam folder itu. Gunakan satu 11-karakter ID per baris, tanpa header, baris kosong atau penuh YouTube URLs.

Ifía memilih satu skrip persiapan dan menyimpannya di samping video-ids.txt. Ia menolak invalid dan duplikasi IDs, kemudian menyimpan snapshot input normalisasi, pilihan metadata dan jalankan ID di bawah prepared/. Perintah input dipertahankan.

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)
Lari dari barang-barang besar/
python prepare.py videos-001

Apa yang dipersiapkan

\"Expanded Expected 2\" video unik untuk video-001. Tetap bersiap-siap/ tidak berubah. Metadata metadata menggunakan include_formats: false dan include_chapters: false. Setiap video yang diterima oleh Wiredon adalah item yang dapat diagih secara terpisah; baris duplikat akan diproses secara terpisah, sehingga resep ini berhenti sebelum mengirimkannya.

Anda belum menggunakan ID untuk tugas yang berbeda. ¡Tinggalkan kembali video-001Q untuk tugas ini. Sebuah ID baru adalah untuk sebuah dataset baru atau refresh disengaja.

2. Diangkat dan dikumpulkan hasilnya

Simpan process.py atau process.sh dalam bentuk pukal sebelum menjalankannya. CLI menciptakan satu pekerjaan Bulk, mengunggah IDs yang telah disiapkan, mulai memproses dan menyimpan setiap bagian hasil ke dalam bulk-results.ndjson. Wait lokal berhenti setelah 30 menit; pekerjaan server diterima terus berlanjut.

Setiap percobaan mendapatkan foldernya sendiri di bawah percobaan/, dengan penerimaan CLI, kesalahan dan disimpan dijalankan. ready.txt menunjuk ke hasil akhir terbaru. Exit 2 berarti hasil lengkap termasuk video yang gagal; terus mengekspor dan memeriksa baris-baris tersebut.

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)
Proses proses berkas yang telah disiapkan
python process.py submit

Periksa kemajuan dari terminal lain

Lari dari barang-barang besar dengan akun CLI yang sama. Tindakan status menunjukkan aksi yang disimpan dijalankan dan membaca pekerjaan Bulk jauh ketika sebuah ID tersedia. Ini tidak menciptakan atau melanjutkan pekerjaan.

Bobot membaca kemajuan saat ini
python process.py status

3. africario Reconcile and export

Simpan export.py atau export.sh di samping skrip lain, kemudian jalankan. Ini memeriksa run tersimpan dan input hash, kemudian cocok setiap hasil oleh indeks berbasis nol dan video_id. Bagian - bagian hasil yang dihasilkan mungkin tidak teratur. Hilang, duplikat atau baris tidak cocok menghentikan ekspor.

Pengeksportan evaporasi mempertahankan objek data meta penuh, kesalahan dan laporan penggunaan untuk setiap baris. Video Gagal tetap terlihat dengan metadata: null. Contoh kecil ini memuat hasil ke memori; gunakan audit streaming dalam pemrosesan berkas Bulk untuk sebuah dataset besar.

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)
Ekspor secara lokal · tidak ada panggilan API
python export.py

Anda menggunakan berkas tereksport

Kejayaan mencetak ringkasan dan menyimpan nama berkas. Ekspor export keluar 0 ketika setiap video berhasil, 2 ketika beberapa gagal, atau 1 ketika validasi atau penulisan gagal. Bahan ekspor/disimpan; baca secara lokal bukan penyerahan yang dijalankan ulang.

Berkas di bawah ekspor/Gunalah untuk
videos.jsonPengimporan ke dalam aplikasi atau alur kerja agen Anda. Baris-baris menjaga urutan masukan, metadata, kesalahan dan penggunaan.
videos.csvSemak tajuk, tempoh dan kegagalan dalam hamparan. Teks yang menyerupai formula diawali dengan apostrof; JSON mengekalkan teks asal.
summary.jsonCakupan dan penghitungan completed/failed, dihubungkan dengan jangka ID dan Bulk ID.
failed-video-ids.txtReview view hanya mengkonfirmasi video yang gagal sebelum memutuskan permintaan berbayar lainnya. Kosong ketika semua berhasil.
Membaca ringkasan dan data meta yang disimpan
python -m json.tool export/summary.json
python -m json.tool export/videos.json

Contoh hasil dengan video yang gagal

excerpt videos.jsonllustrative. Sebuah pekerjaan Bulk yang selesai dapat memuat video yang gagal. Jangan anggap video gagal sebagai hasil sukses kosong atau jatuhkan secara diam-diam dari dataset Anda.

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

Pulihkan pekerjaan yang sama

Jika menunggu dihentikan atau bagian hasilnya tidak dapat dibaca, jalankan pemulihan. Ini mengumpulkan pekerjaan yang sudah ada ke dalam folder percobaan segar dan memperbarui ready.txt hanya setelah penerimaan lengkap. Ia tidak mengunggah atau menyerahkan pekerjaan pengganti. Kemudian menjalankan pengekspor jika ekspor/ belum dibuat.

Hasil yang diselamatkan oleh KemuliaanTindakan berikutnya
bulk_item_failuresEkspor dan tinjau failed-video-ids.txt. Jangan kirim kembali semua video sukses.
partial_resultSimpan berkas sebagiannya. Pemulihan kembali yang sama untuk mengambil semua bagian sebelum mengekspor.
running / finalizingPulihkan kemudian menggunakan ID, profil dan direktori keadaan yang sama.
pausedKemuat baca pauseReason dalam status, perbaiki penyebabnya, kemudian resume secara eksplisit bahwa Bulk ID menggunakan panduan kontrol.
awaiting_upload / bulk_input_requiredPeriksa draf yang disimpan. Unggah berkas asli yang telah dipersiapkan dan mulailah yang sudah ada Bulk ID); pemulihan tidak mengulangi tindakan ini.
Pengiriman tak pasti atau tidak ada ID jauh¡Keep the run and inspect the disimpan error dan Bulk Jobs sebelum mencoba lagi. ID baru bisa membuat pekerjaan lain.
Sumber salah, baris hilang atau input hash tidak cocokTidak ada ekspor yang diterima. Periksa snapshot yang telah disiapkan, simpan berkas lari dan hasil; jangan buat metadata yang hilang.
Periksalah, kemudian pulihkan pekerjaan yang ada
python process.py status
python process.py recover

Simpan snapshot ini atau segarkannya dengan sengaja

Simpan hasil selesai dalam jendela retensi jam 24. ekspor Anda tetap file lokal untuk digunakan kembali. Untuk menyegarkan metadata kemudian, gunakan folder kerja baru dan jalankan ID, dan tinjau kembali biaya permintaan baru terlebih dahulu.