# Bulk pemrosesan berkas

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

Referensi kanonikal: https://flashdata.dev/id/docs/guides/bulk
Diulang: 2026-11-05 oleh FlashData

<a id="first-task"></a>

## 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

```text
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
```

- [Pertahankan catatan aplikasi IDs dengan daftar kecil](https://flashdata.dev/id/docs/guides/enrich-youtube-videos/reference.md)
- [Batch versus Bulk](https://flashdata.dev/id/docs/reference/batch-and-bulk/reference.md#choose)
- [Bulk API taman bermain](https://flashdata.dev/id/docs/reference/bulk-processing/reference.md#playground)
- [Unduhan massal video YouTube](https://flashdata.dev/id/products/youtube-download#bulk-downloads)

<a id="before-you-start"></a>

## 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

```bash
flashdata auth status --json
flashdata account balance --json
flashdata account pricing --source youtube_metadata --request-count 2
flashdata account limits
```

- [Pasang CLI](https://flashdata.dev/id/docs/guides/flashdata-cli/reference.md#install)
- [Buat kunci API](https://flashdata.dev/app/api-keys)
- [Agen akses dan mengklaim](https://flashdata.dev/id/docs/guides/agent-access/reference.md)
- [Gunakan HTTP sebagai gantinya](https://flashdata.dev/id/docs/reference/bulk-processing/reference.md#endpoints)

<a id="prepare"></a>

## 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

#### Bash

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


### PowerShell 7

#### PowerShell 7

```powershell
if (Test-Path -LiteralPath video-ids.txt) { throw 'Keep the existing file or use a new folder.' }
$idsFile = Join-Path (Get-Location) 'video-ids.txt'
$idsText = [string]::Join([char]10, @('jNQXAC9IVRw', 'dQw4w9WgXcQ', ''))
[IO.File]::WriteAllText($idsFile, $idsText, [Text.UTF8Encoding]::new($false))
Get-Content -LiteralPath video-ids.txt
```



<a id="run"></a>

## 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

#### Bash

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


### PowerShell 7

#### PowerShell 7

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


- [Periksa kemajuan di terminal lain](https://flashdata.dev/id/docs/guides/bulk/reference.md#progress)
- [Reover setelah jeda](https://flashdata.dev/id/docs/guides/bulk/reference.md#controls)

<a id="results"></a>

## 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

```json
{"index":0,"video_id":"jNQXAC9IVRw","source":"youtube_metadata","status":"completed","results":[{"videoId":"jNQXAC9IVRw","title":"Example video title"}]}
```

### Bash

#### Bash

```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
```


### PowerShell 7

#### PowerShell 7

```powershell
Get-Content -LiteralPath bulk-results.ndjson | ForEach-Object {
  $row = $_ | ConvertFrom-Json
  $title = if ($row.results) { $row.results[0].title } else { $null }
  [pscustomobject]@{ index = $row.index; video_id = $row.video_id; status = $row.status; title = $title; error = $row.error }
}
```



<a id="audit"></a>

## 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.


<a id="audit-script"></a>

### 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

```python
# 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)
```


<a id="run-audit"></a>

### Jalankan audit impor

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

#### Bash

##### Bash

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


#### PowerShell 7

##### PowerShell 7

```powershell
python audit-bulk.py --input video-ids.txt --results bulk-results.ndjson --out audit
```



<a id="import"></a>

### Impor selesai baris dan menjaga audit

| Berkas / sinyal | Gunakan dengan cara ini |
| --- | --- |
| completed.ndjson | Gabung dengan indeks ke berkas asli. Gunakan video_id untuk kunci katalog; pertahankan identitas job/snapshot ketika menyimpan riwayat refresh. |
| failed.ndjson + failed-video-ids.txt | Kesalahan Ulasan sebelum sengaja mencoba IDs ini. Barang yang sukses dan hilang dikeluarkan dari daftar ID. |
| missing.ndjson | Merebut semua bagian hasil dari pekerjaan yang telah ada, lalu mengaudit berkas yang ditemukan dalam direktori baru. Hilang keluaran bukan sebuah kuiri gagal dikonfirmasi. |
| summary.json | coverageComplete 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.json | Salah bentuk atau tidak cocok data: memeriksa file yang disimpan. Jangan mempublikasikan sebagian audit sebagai data lengkap. |

- [Mengembalikan hasil yang telah ada](https://flashdata.dev/id/docs/guides/bulk/reference.md#controls)
- [Retensi hasil](https://flashdata.dev/id/docs/guides/save-results/reference.md#bulk)

<a id="item-failures"></a>

## 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

```bash
jq -c 'select(.status != "completed") | {index, video_id, status, error}' bulk-results.ndjson
```


<a id="progress"></a>

## 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.

| Ruas | Bacakan sebagai |
| --- | --- |
| input.scannedBytes / input.bytes | Proses pemindaian berkas, belum selesai query atau media terunggah. |
| input.complete | Semua masukan telah dibaca; kueri dan hasil kemasan mungkin masih berjalan. |
| counts.accepted / completed / failed | IDs, video sukses dan video gagal. Luar biasa = applicated arthcompleted gagal. |
| counts.invalid / results | Baris masukan / catatan tidak valid dikemas sejauh ini. HTTP dapat menerima berkas yang berisi baris tidak valid; CLI memvalidasi masukan sebelum mengunggah. |
| delivery | Pengantar data pelanggan: uploadedParts, retryCount, storageType dan customerStorage. Terpisah dari setiap upload media video. |

### Bash

#### Bash

```bash
(
set -eu
BULK_ID=$(flashdata runs show bulk-first --json | jq -er '.data.remoteId')
flashdata bulk get "$BULK_ID" --json
)
```


### PowerShell 7

#### PowerShell 7

```powershell
$run = flashdata runs show bulk-first --json | ConvertFrom-Json
if ($LASTEXITCODE -ne 0 -or -not $run.data.remoteId) { throw 'Read the saved run before continuing.' }
flashdata bulk get $run.data.remoteId --json
```



<a id="states"></a>

### 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.

| Keadaan | Aksi berikutnya |
| --- | --- |
| awaiting_upload | Unggah berkas, kemudian mulai pekerjaan yang ada. |
| running / finalizing | Tunggu. Menyelesaikan bisa termasuk pertanyaan yang belum selesai, kemasan dan pengiriman penyimpanan. |
| paused | Selesaikan pauseReason dan lanjutkan pekerjaan yang sama. |
| completed | Unduh semua bagian hasil dan pemeriksaan baris gagal. |
| failed / cancelled | Inspeksi job.error dan tanda terima tersimpan. Menerima pekerjaan mungkin masih finish(Dan tidak ada suatu pun yang luput dari pengetahuan Allah) yang Dia kehendaki. |


<a id="controls"></a>

## 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.

| Situasi | Perbaiki |
| --- | --- |
| awaiting_upload | runs recover tidak memutar ulang sebuah upload atau mulai. Periksa ID yang disimpan, unggah status dan berkas asli sebelum secara eksplisit melanjutkan. |
| paused | Selesaikan penyebab laporan, lalu gunakan resume massal dengan ID yang disimpan. Pemulihan tidak dilanjutkan secara otomatis. |
| 401 / 403 | Kembalikan akses yang valid ke akun dan sumber yang mengirimkan. Gunakan kembali pekerjaan yang sama setelah otentikasi diperbaiki. |
| 409 / 410 | 409: hasilnya belum siap. 410: hasil yang disimpan sudah kadaluarsa; gunakan salinan yang tersimpan. |
| Diunggah habis waktu URL | Konfirmasikan 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

```bash
flashdata runs show bulk-first --json
flashdata runs recover bulk-first --output recovered-results.ndjson --timeout 30m --json
```

- [CLI pemulihan dan berjalan berulang](https://flashdata.dev/id/docs/guides/cli-automation/reference.md#recover)
- [Batas rate](https://flashdata.dev/id/docs/guides/usage-and-limits/reference.md)

<a id="pause"></a>

### 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

```bash
flashdata bulk pause BULK_ID --json
```

#### Lanjutkan setelah memperbaiki penyebabnya

```bash
flashdata bulk resume BULK_ID --json
```

- [Mutakhirkan pekerjaan Bulk](https://flashdata.dev/id/docs/reference/bulk-processing/reference.md#updateBulkJob)

<a id="cancel"></a>

### 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

```bash
flashdata bulk cancel BULK_ID --json
```


<a id="manifest"></a>

## 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

```bash
flashdata bulk results BULK_ID --output saved-results.ndjson --timeout 30m --json
```

- [Periksa cakupan data](https://flashdata.dev/id/docs/guides/bulk/reference.md#audit)
- [Perbaikan, bagian dan retensi referensi](https://flashdata.dev/id/docs/reference/bulk-processing/reference.md#downloadBulkJobManifest)

<a id="storage"></a>

## 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.

- [Ruas kredensial penyedia](https://flashdata.dev/id/docs/sources/youtube_download/reference.md#storage)
- [Jalur pengiriman dan objek penyimpanan](https://flashdata.dev/id/docs/reference/bulk-processing/reference.md#storage)
- [Mengkonfigurasi Bulk API permintaan](https://flashdata.dev/id/docs/reference/bulk-processing/reference.md#playground)

<a id="storage-run"></a>

### Jalankan dengan konfigurasi penyimpanan yang disimpan

#### Tambahkan penyimpanan ke alur kerja metadata

```bash
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
```

