Lewati ke isi
ID
Dapatkan kunci API
Jelajahi dokumentasi

Panduan

Bulk pemrosesan berkas

Proses berkas video IDs, mengambil setiap bagian hasil dan memeriksa cakupan sebelum mengimpor data ke aplikasi Anda.

Di halaman ini

Dari berkas ID ke suatu data yang diperiksa

Gunakan alur kerja ini untuk katalog video, koleksi penelitian atau antrian gangguan. Satu berkas menggunakan satu sumber dan pilihan yang sama untuk setiap ID. Mulailah dengan dua video metadata sampel, kemudian mengganti file Anda sendiri.

Berkas yang dihasilkan oleh alur kerja ini
video-ids.txt → Bulk pekerjaan ghanbe bulk-results.ndjson
  audit/completed.ndjson hasil aplikasi Anda
  audit/failed-video-ids.txt mengkonfirmasi kegagalan untuk ditinjau
  Masukan audit/missing.ndjson yang hasil yang hilang
  audit/summary.json cakupan dan jumlah hasil

Sebelum Anda mulai

Pasang CLI dan gunakan profil yang ada atau FLASHDATA_API_KEY dengan izin youtube_metadata. Konfirmasi data.accessVerified: true dan tinjau saldo yang tersedia, harga untuk dua permintaan dan batas saat ini. Untuk file Anda sendiri, gunakan ID menghitung ketika memeriksa harga. Masing-masing diproses ID adalah query terpisah, bukan satu biaya datar untuk file.

Gunakan Bash dengan jq atau PowerShell 7 untuk langkah-langkah 1–3. Audit impor opsional dalam langkah 4 menggunakan Python 3.10 + dan perpustakaan standar. CLI sendiri tidak membutuhkan Node.js maupun Python.

Cek akses dan akun bebas
flashdata auth status --json
flashdata account balance --json
flashdata account pricing --source youtube_metadata --request-count 2
flashdata account limits

1. Siapkan IDs

Jalankan dalam folder kerja baru. Gunakan UTF-8 teks dengan satu 11-character video ID per baris, bukan YouTube URL. Ukuran berkas maksimum adalah 2 GiB. Hapus baris kosong dan duplikat: CLI menolak masukan yang salah, dan diulang IDs diproses secara terpisah.

Bash
# Run in a new working directory.
(
  set -euC
  printf '%s\n' 'jNQXAC9IVRw' 'dQw4w9WgXcQ' > video-ids.txt
)
cat video-ids.txt

2. Jalankan berkas

CLI menciptakan pekerjaan, meng-upload file, mulai memproses dan menyimpan setiap bagian hasil menjadi satu berkas NDJSON. Gunakan path keluaran baru. ID lokal pertama kali menyimpan tanda terima pekerjaan remote untuk pemulihan.

Bash
flashdata bulk run --source youtube_metadata \
  --input video-ids.txt --run-id bulk-first \
  --output bulk-results.ndjson --timeout 30m --json

3. Inspeksi hasil

Buka bulk-results.ndjson. Setiap baris adalah catatan JSON dengan indeks, video_id dan status. Baris sukses berisi larik hasil; baris gagal mengandung galat. Gabung catatan ke masukan dengan indeks berbasis zero-, bukan file order. Perintah Bash menggunakan jq.

Salah satu baris sukses yang diselenggarakan
{"index":0,"video_id":"jNQXAC9IVRw","source":"youtube_metadata","status":"completed","results":[{"videoId":"jNQXAC9IVRw","title":"Example video title"}]}
Bash
# Bash + jq: read each record without loading the whole file.
jq -c '{index, video_id, status, title: .results[0].title, error}' bulk-results.ndjson

4. Periksa cakupan sebelum mengimpor

Simpan audit-bulk.py di bawah ini. Jalankan terhadap berkas masukan yang tidak berubah dan semua hasil diambil. Ini memeriksa setiap indeks, video ID dan sumber, menolak baris hasil duplikat, dan memisahkan kegagalan dikonfirmasi dari hasil yang hilang. Untuk sumber lain, tambahkan --source SOURCE_ID.

Mengharapkan inputRows: 2, selesai: 2, gagal: 0, hilang: 0 dan allSucceeded: true untuk sampel sukses. Hanya baris yang selesai yang ada dalam impor hasil aplikasi. Menjaga ringkasan audit dan hasil yang tidak sukses bersama mereka.

Simpan audit-bulk.py

Buat audit-bulk.py di samping video-ids.txt dan bulk-results.ndjson dalam folder kerja. Salin kode lengkap di bawah ini dan simpan.

Skrip membaca baris demi baris berkas dan menggunakan indeks SQLite lokal daripada memuat seluruh data ke dalam memori. Ini membutuhkan berkas masukan yang sah dari video IDs. Setiap audit menggunakan direktori keluaran baru; berkas parsial tetap terpisah sampai parsing selesai.

audit-bulk.py
# audit-bulk.py — Python 3.10+, standard library only; no network requests.
import argparse
import json
import re
import sqlite3
import sys
from contextlib import ExitStack
from pathlib import Path

parser = argparse.ArgumentParser()
parser.add_argument('--input', required=True)
parser.add_argument('--results', required=True)
parser.add_argument('--out', required=True)
parser.add_argument('--source', default='youtube_metadata')
args = parser.parse_args()
out = Path(args.out)
try:
    out.mkdir()  # Keep any previous audit. Use a new directory for another attempt.
    with ExitStack() as stack:
        db = sqlite3.connect(out / 'index.sqlite')
        stack.callback(db.close)
        db.execute('CREATE TABLE inputs (idx INTEGER PRIMARY KEY, video_id TEXT, outcome TEXT)')
        count = 0
        with open(args.input, encoding='utf-8-sig') as inputs:
            for index, line in enumerate(inputs):
                video_id = line.strip()
                if not re.fullmatch(r'[A-Za-z0-9_-]{11}', video_id):
                    raise ValueError('Invalid ID on input line ' + str(index + 1))
                db.execute('INSERT INTO inputs VALUES (?, ?, NULL)', (index, video_id))
                count += 1
        if not count:
            raise ValueError('The input file is empty.')
        db.commit()
        files = {name: stack.enter_context(open(out / (name + '.part'), 'x', encoding='utf-8'))
                 for name in ['completed.ndjson', 'failed.ndjson', 'missing.ndjson', 'failed-video-ids.txt']}
        completed = failed = 0
        with open(args.results, encoding='utf-8-sig') as results:
            for line_number, line in enumerate(results, 1):
                if not line.strip():
                    continue
                row = json.loads(line)
                if not isinstance(row, dict) or type(row.get('index')) is not int:
                    raise ValueError('Invalid result index on line ' + str(line_number))
                expected = db.execute('SELECT video_id, outcome FROM inputs WHERE idx = ?',
                                      (row['index'],)).fetchone()
                if (not expected or row.get('video_id') != expected[0]
                        or row.get('source') != args.source or expected[1] is not None):
                    raise ValueError('Unknown, duplicate or mismatched result on line ' + str(line_number))
                status = row.get('status')
                if status not in ['completed', 'failed']:
                    raise ValueError('Unexpected item status on line ' + str(line_number))
                if status == 'completed':
                    if not isinstance(row.get('results'), list):
                        raise ValueError('Completed row is missing its results array.')
                    if args.source == 'youtube_metadata' and (len(row['results']) != 1
                            or not isinstance(row['results'][0], dict)
                            or row['results'][0].get('videoId') != expected[0]):
                        raise ValueError('Metadata does not belong to the requested video.')
                    completed += 1
                else:
                    failed += 1
                db.execute('UPDATE inputs SET outcome = ? WHERE idx = ?', (status, row['index']))
                files[status + '.ndjson'].write(json.dumps(row, ensure_ascii=False) + '\n')
        db.commit()
        missing = 0
        for index, video_id in db.execute('SELECT idx, video_id FROM inputs WHERE outcome IS NULL ORDER BY idx'):
            files['missing.ndjson'].write(json.dumps({'index': index, 'video_id': video_id,
                                                     'status': 'missing_result'}) + '\n')
            missing += 1
        for (video_id,) in db.execute("SELECT video_id FROM inputs WHERE outcome = 'failed' GROUP BY video_id ORDER BY MIN(idx)"):
            files['failed-video-ids.txt'].write(video_id + '\n')
        summary = {'source': args.source, 'inputRows': count, 'completed': completed,
                   'failed': failed, 'missing': missing, 'coverageComplete': missing == 0,
                   'allSucceeded': failed == 0 and missing == 0}
    for name in files:
        (out / (name + '.part')).rename(out / name)
    with open(out / 'summary.json', 'x', encoding='utf-8') as output:
        json.dump(summary, output, indent=2)
    print(json.dumps(summary, indent=2))
    sys.exit(0 if summary['allSucceeded'] else 2)
except Exception as error:
    print(str(error), file=sys.stderr)
    print('Audit not complete. Preserve this directory and inspect the inputs/results.', file=sys.stderr)
    sys.exit(1)

Jalankan audit impor

Jalankan dari folder yang berisi skrip, masukan asli dan hasil yang diunduh. Audit hanya membaca berkas lokal.

Bash
python3 audit-bulk.py --input video-ids.txt --results bulk-results.ndjson --out audit

Impor selesai baris dan menjaga audit

Berkas / sinyalGunakan dengan cara ini
completed.ndjsonGabung dengan indeks ke berkas asli. Gunakan video_id untuk kunci katalog; pertahankan identitas job/snapshot ketika menyimpan riwayat refresh.
failed.ndjson + failed-video-ids.txtKesalahan Ulasan sebelum sengaja mencoba IDs ini. Barang yang sukses dan hilang dikeluarkan dari daftar ID.
missing.ndjsonMerebut semua bagian hasil dari pekerjaan yang telah ada, lalu mengaudit berkas yang ditemukan dalam direktori baru. Hilang keluaran bukan sebuah kuiri gagal dikonfirmasi.
summary.jsoncoverageComplete cek bahwa setiap masukan memiliki hasil. allSucceeded juga membutuhkan tidak ada video gagal. Audit keluar dari 2 untuk kegagalan atau baris yang hilang.
Keluar 1 / tidak summary.jsonSalah bentuk atau tidak cocok data: memeriksa file yang disimpan. Jangan mempublikasikan sebagian audit sebagai data lengkap.

Jika beberapa video gagal

Pekerjaan Bulk yang selesai dapat berisi video gagal. CLI juga menyelamatkan baris-baris itu, lalu keluar dengan bulk_item_failures. Inspeksi kesalahan mereka sebelum memutuskan apakah akan mencoba kembali individu IDs; jangan mengirimkan kembali seluruh berkas secara otomatis.

Hanya tampilkan catatan yang gagal jq
jq -c 'select(.status != "completed") | {index, video_id, status, error}' bulk-results.ndjson

Trek kemajuan dan kapasitas

Baca tugas yang disimpan ketika perintah aslinya dijalankan. CLI membungkus status di bawah data; langsung HTTP membungkusnya di bawah pekerjaan. Periksa dengan menunda dan mundur, dan menghormati Retry-After pada 429. Suatu timeout lokal atau terminal tertutup tidak membatalkan kerja remote.

RuasBacakan sebagai
input.scannedBytes / input.bytesProses pemindaian berkas, belum selesai query atau media terunggah.
input.completeSemua masukan telah dibaca; kueri dan hasil kemasan mungkin masih berjalan.
counts.accepted / completed / failedIDs, video sukses dan video gagal. Luar biasa = applicated arthcompleted gagal.
counts.invalid / resultsBaris masukan / catatan tidak valid dikemas sejauh ini. HTTP dapat menerima berkas yang berisi baris tidak valid; CLI memvalidasi masukan sebelum mengunggah.
deliveryPengantar data pelanggan: uploadedParts, retryCount, storageType dan customerStorage. Terpisah dari setiap upload media video.
Bash
(
set -eu
BULK_ID=$(flashdata runs show bulk-first --json | jq -er '.data.remoteId')
flashdata bulk get "$BULK_ID" --json
)

Tahu kapan harus menunggu atau bertindak

Bulk secara bertahap menyerahkan dalam kapasitas maxPendingJobs akun anda, berbagi dengan pekerjaan lain. Kredit tidak cukup atau sebuah langganan tidak aktif dapat menghentikan pekerjaan. Periksa pauseReason sebelum melanjutkan.

KeadaanAksi berikutnya
awaiting_uploadUnggah berkas, kemudian mulai pekerjaan yang ada.
running / finalizingTunggu. Menyelesaikan bisa termasuk pertanyaan yang belum selesai, kemasan dan pengiriman penyimpanan.
pausedSelesaikan pauseReason dan lanjutkan pekerjaan yang sama.
completedUnduh semua bagian hasil dan pemeriksaan baris gagal.
failed / cancelledInspeksi job.error dan tanda terima tersimpan. Menerima pekerjaan mungkin masih finish(Dan tidak ada suatu pun yang luput dari pengetahuan Allah) yang Dia kehendaki.

Lanjutkan arus kerja yang terganggu

Setelah timeout lokal atau diinterupsi hasil download, pulih bulk- pertama. Ini membaca pekerjaan jarak jauh yang ada; ini tidak mengirimkan data lagi. Gunakan nama berkas keluaran baru. Kesalahan partial_result mungkin meninggalkan sebagian berkas lokal; tetap terpisah dari hasil pulih.

Gunakan profil CLI yang sama dan direktori negara seluruh. Untuk profil bernama, tambahkan --profile NAMA ke setiap perintah.

SituasiPerbaiki
awaiting_uploadruns recover tidak memutar ulang sebuah upload atau mulai. Periksa ID yang disimpan, unggah status dan berkas asli sebelum secara eksplisit melanjutkan.
pausedSelesaikan penyebab laporan, lalu gunakan resume massal dengan ID yang disimpan. Pemulihan tidak dilanjutkan secara otomatis.
401 / 403Kembalikan akses yang valid ke akun dan sumber yang mengirimkan. Gunakan kembali pekerjaan yang sama setelah otentikasi diperbaiki.
409 / 410409: hasilnya belum siap. 410: hasil yang disimpan sudah kadaluarsa; gunakan salinan yang tersimpan.
Diunggah habis waktu URLKonfirmasikan pekerjaan lama tidak pernah dimulai sebelum menciptakan yang baru. Sebuah penyerahan yang tidak pasti adalah alasan untuk membaca ID yang disimpan terlebih dahulu.
Pulihkan run yang disimpan
flashdata runs show bulk-first --json
flashdata runs recover bulk-first --output recovered-results.ndjson --timeout 30m --json

Jeda atau lanjutkan pekerjaan

Ganti BULK_ID dengan ID dari runs show bulk- pertama. Jeda berhenti pengiriman baru dan hasil kemasan; kueri diterima terus. Resolve pauseReason sebelum melanjutkan. Untuk opsi yang berubah atau kredensial penyimpanan, perbarui tugas yang telah ada melalui Bulk API.

Jeda
flashdata bulk pause BULK_ID --json
Lanjutkan setelah memperbaiki penyebabnya
flashdata bulk resume BULK_ID --json

Batal permanen

Hanya membatalkan ketika Anda berniat untuk meninggalkan pekerjaan. Pembatalan tidak membatalkan kueri diterima atau pengembalian uang menyelesaikan pekerjaan. Menghitung masih bisa berubah, dan tidak ada daftar lengkap yang diterbitkan. Jeda dapat diubah.

Batalkan tugas yang dipilih
flashdata bulk cancel BULK_ID --json

Ambil setiap bagian hasil

Untuk pekerjaan yang telah ada, CLI mengikuti manifest nya dan menyimpan setiap bagian hasil menjadi satu berkas NDJSON. Gunakan path keluaran baru dan jalankan audit impor pada berkas gabungan. Hasil unduh menjelaskan media yang dikirim; mereka bukan MP4 atau byte audio.

Ambil semua bagian dari tugas yang telah ada
flashdata bulk results BULK_ID --output saved-results.ndjson --timeout 30m --json

Bawa ke tempat penyimpananmu

Simpan kredensial penyedia Anda sebagai storage.json dalam folder kerja sebelum menjalankan perintah ini. Gunakan ruas penyedia yang terhubung di bawah; jaga berkas pribadi. CLI 's --storage-config membaca berkas JSON ini dan memilih result_storage untuk data atau penyimpanan untuk media. --options juga mengambil jalur berkas, bukan inline JSON.

Jalankan dengan konfigurasi penyimpanan yang disimpan

Tambahkan penyimpanan ke alur kerja metadata
flashdata bulk run --source youtube_metadata --input video-ids.txt --storage-config storage.json --run-id bulk-with-storage --output stored-results.ndjson --timeout 30m --json