# Bulkファイル処理

IDsのファイルを処理し、すべての結果の部分を取得し、アプリケーションのデータセットをインポートする前にカバレッジをチェックします。

キャニシニカル参照: https://flashdata.dev/ja/docs/guides/bulk
レビュー: FlashData による 2026-11-05

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

## IDファイルから、チェックされたデータセットへ

ビデオカタログ、リサーチコレクション、またはインジェクションキューのこのワークフローを使用します。 1つのファイルは、すべてのIDの1つのソースと同じオプションを使用します。 2 のビデオメタデータサンプルで起動し、自分のファイルを置換します。

### このワークフローで生成されたファイル

```text
video-ids.txt → Bulk ジョブ → bulk-results.ndjson
  → audit/completed.ndjson は、アプリケーションでの結果を表示します。
  → audit/failed-video-ids.txt では、レビューの失敗を確認しました
  → audit/missing.ndjson 結果が欠けている入力
  → audit/summary.jsonのカバレッジと結果のカウント
```

- [小さなリストでアプリケーションレコードIDsを保ちましょう](https://flashdata.dev/ja/docs/guides/enrich-youtube-videos/reference.md)
- [Batch 対 Bulk](https://flashdata.dev/ja/docs/reference/batch-and-bulk/reference.md#choose)
- [Bulk APIの運動場](https://flashdata.dev/ja/docs/reference/bulk-processing/reference.md#playground)
- [YouTube 動画の一括ダウンロード](https://flashdata.dev/ja/products/youtube-download#bulk-downloads)

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

## はじめる前に

CLIをインストールし、既存のプロファイルまたはFLASHDATA_API_KEYをyoutube_metadataの権限で使用してください。 data.accessVerified: true を確認し、2つのリクエストと現在の制限の利用可能な残高、価格設定を確認します。 独自のファイルでは、ID のカウントを、価格設定をチェックするときに使用します。 ID は、ファイルに対して1つのフラットチャージではなく、別のクエリです。

利用条件 Bash とりあえず jq または PowerShell 7 手順のため 1–3. ステップ4のオプションのインポート監査は、Python 3.10+と標準ライブラリを使用しています。 CLI自体はNode.jsとPythonを要求しません。

### 無料のアクセスとアカウントチェック

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

- [CLIをインストール](https://flashdata.dev/ja/docs/guides/flashdata-cli/reference.md#install)
- [APIキーを作成する](https://flashdata.dev/app/api-keys)
- [エージェントのアクセスとクレーム](https://flashdata.dev/ja/docs/guides/agent-access/reference.md)
- [代わりにHTTPを使う](https://flashdata.dev/ja/docs/reference/bulk-processing/reference.md#endpoints)

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

## 1. IDsを準備する

新しい作業フォルダで実行します。 利用条件 UTF-8 1つのテキスト 11-キャラクタービデオ ID ラインごとに、 YouTube URL. 最大ファイルサイズは2 GiBです。 空白行と重複を削除します。CLIは誤字入力を拒否し、IDsは別々に処理されます。

### 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. ファイルを実行します

CLI は、ジョブを作成したり、ファイルをアップロードしたり、すべての結果が 1 つの NDJSON ファイルに処理し、保存したりします。 新しい出力パスを使用します。 ローカルランIDバルクファーストは回復のための遠隔仕事のレシートを保ちます。

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


- [別のターミナルで進捗状況をチェック](https://flashdata.dev/ja/docs/guides/bulk/reference.md#progress)
- [タイムアウト後に回復する](https://flashdata.dev/ja/docs/guides/bulk/reference.md#controls)

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

## 3. 結果の特定

bulk-results.ndjson を開きます。 各行は、インデックス、video_id、ステータスのJSONレコードです。 成功した行には、結果の配列が含まれている。失敗した行にはエラーが含まれている。 ファイル注文ではなくゼロベースインデックスでレコードを入力します。 Bash コマンドは jq を使用します。

### 1つの成功した行・省略例

```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. 輸入前にカバレッジをチェック

audit-bulk.pyを以下に保存します。 変更されていない入力ファイルと、すべての取得された結果の部分に対して実行します。 すべてのインデックス、ビデオ ID とソースをチェックし、重複した結果の行を拒否し、確認された失敗を欠落した結果から分離します。 別のソースについては、--source SOURCE_ID を追加します。

期待するinputRows:2、完了:2、失敗しました:0、欠落:0とallSucceeded: true成功サンプルのための。 完了した行のみが、アプリケーションの結果インポートに所属しています。 監査要約と、それらを一緒に失敗した結果を保持してください。


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

### 保存 audit-bulk.py

video-ids.txt と bulk-results.ndjson の横にある audit-bulk.py を作業フォルダに作成します。 下記のコードをコピーして保存します。

スクリプトは、データセット全体をメモリにロードする代わりに、行ごとにファイルラインを読み、ローカルSQLiteインデックスを使用します。 ビデオIDsの有効な入力ファイルが必要です。 各監査は、新しい出力ディレクトリを使用します。 部分的なファイルは、終了を解析するまでは別々に残ります。

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

### インポート監査を実行

スクリプト、元の入力、ダウンロードした結果を含むフォルダから実行します。 監査はローカルファイルのみを読み込みます。

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

### 完了した行をインポートし、監査を維持

| ファイル/信号 | このようにして使う |
| --- | --- |
| completed.ndjson | 元のファイルへインデックスで登録してください。 video_idをカタログキーに使用し、更新履歴を保存する際のjob/snapshot IDを保持します。 |
| failed.ndjson + failed-video-ids.txt | これらのIDsを意図的に再試行する前にエラーを確認します。 失敗したIDリストから、成功したアイテムと欠落アイテムは除外されます。 |
| missing.ndjson | 既存のジョブからすべての結果の部分を回復し、回復したファイルを新しいディレクトリに監査します。 出力を見逃すことは、失敗したクエリは確認されません。 |
| summary.json | coverageCompleteは、すべての入力が結果を持っていることを確認します。 allSucceededは、失敗した動画を必要としません。 監査は、障害または欠行の2を終了します。 |
| 1/いいえsummary.jsonを終了して下さい | 変形または不一致したデータ:保存したファイルを調べます。 部分的な監査を完全なデータセットとして公開しないでください。 |

- [既存の結果の回復](https://flashdata.dev/ja/docs/guides/bulk/reference.md#controls)
- [結果の保持](https://flashdata.dev/ja/docs/guides/save-results/reference.md#bulk)

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

## 一部の動画が失敗した場合

Bulk ジョブが完了すると、失敗した動画が格納されます。 CLI はそれらの行を保存し、bulk_item_failures で終了します。 個々のIDsを再試行するかどうかを決定する前に、エラーを調べます。 ファイル全体を自動で返送しないでください。

### 失敗したレコードだけを表示 · jq

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


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

## 進捗状況と容量を追跡する

元のコマンドが実行中に保存されたジョブを読み込みます。 CLI は、データの下にステータスをラップします。 HTTP は、ジョブの下にラップします。 429の遅延およびバックオフ、および名誉のRetry-Afterと点検して下さい。 ローカルタイムアウトまたはクローズドターミナルは、リモートワークをキャンセルしません。

| フィールド | それをとして読みます |
| --- | --- |
| input.scannedBytes / input.bytes | ファイルスキャンの進行、クエリやアップロードされたメディアが完成していません。 |
| input.complete | すべての入力が読み込まれています。 クエリと結果パッケージは実行中であってもよいです。 |
| counts.accepted / completed / failed | 提出されたIDs、成功したビデオと失敗した動画。 成功 = 受け入れられる - 完了 - 失敗しました。 |
| counts.invalid / results | 無効な入力行/これまでのレコードのパッケージ。 HTTPは、無効な行を含むファイルを受け入れることができます。 CLIは、アップロード前に入力を検証します。 |
| delivery | 顧客データ配達: uploadedParts、retryCount、storageTypeおよびcustomerStorage。 各動画のメディアアップロードから分離します。 |

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

### 待ち時間や行動時に知る

Bulk は、アカウントの maxPendingJobs 容量内で、他のジョブと共有されます。 不十分なクレジットまたは非アクティブサブスクリプションは、ジョブを一時停止することができます。 再開前にpauseReasonをチェックしてください。

| ステート | 次のアクション |
| --- | --- |
| awaiting_upload | ファイルをアップロードし、既存のジョブを開始します。 |
| running / finalizing | 待たせます。 ファイナライズは、未完成の問い合わせ、包装および保管配送を含むことができます。 |
| paused | pauseReasonを解決し、同じ仕事を再開して下さい。 |
| completed | すべての結果の部分をダウンロードし、失敗した行を調べます。 |
| failed / cancelled | job.errorと保存されたレシートを点検して下さい。 受け入れられた作品はまだfinishであり、完成したマニフェストは公開されていません。 |


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

## 中断されたワークフローを再開

ローカルタイムアウトまたは中断された結果のダウンロードの後、一括払いを回復します。 既存のリモートジョブを読み込み、データセットを再び送信しません。 新しい出力ファイル名を使用します。 partial_result エラーは、部分的なローカルファイルを残す可能性があります。 回復した結果とは別々にしてください。

同じ CLI プロファイルとステートディレクトリを全体で使用してください。 名前付きプロファイルの場合は、--profile NAME をすべてのコマンドに追加します。

| 投稿ナビゲーション | フィックス |
| --- | --- |
| awaiting_upload | runs recoverはアップロードや開始を再生しません。 保存したID、アップロード状態、元のファイルを明示的に継続して確認します。 |
| paused | 報告された原因を解決し、保存されたIDとバルク履歴書を使用して下さい。 回復は、自動的に舗装された作業を再開しません。 |
| 401 / 403 | 送信アカウントとソースへの有効なアクセスを復元します。 認証後、同じジョブをリセットします。 |
| 409 / 410 | 409: 結果は準備が整っておりません。410: 保存された結果は期限切れになります。保存されたコピーを使用してください。 |
| URLをアップロード | 新しく作成する前に、古いジョブが始まらないことを確認してください。 不確実な投稿は、保存されたIDを最初に読む理由です。 |

### 保存された実行を回復する

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

- [CLIの回復および再帰の操業](https://flashdata.dev/ja/docs/guides/cli-automation/reference.md#recover)
- [レート制限](https://flashdata.dev/ja/docs/guides/usage-and-limits/reference.md)

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

### ジョブの再利用や再開

リプレース BULK_ID と、 ID から runs show 一括優先. 新規の投稿や結果のパッケージングを停止し、承認された問い合わせは続行します。 再開前に pauseReason を解決します。 変更されたオプションやストレージの認証情報については、Bulk API を通じて既存のジョブを更新します。

#### パデュース

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

#### 原因を修正した後に再開

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

- [Bulkジョブを更新](https://flashdata.dev/ja/docs/reference/bulk-processing/reference.md#updateBulkJob)

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

### 永久にキャンセル

ジョブを放棄しようとするとキャンセルのみ。 キャンセルは、未承諾の問い合わせや返金完了作業は行いません。 カウントはまだ変更でき、完了したマニフェストは公開されていません。 パスはリバーシブルです。

#### 選択したジョブをキャンセルする

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


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

## すべての結果の部分を取得します。

CLIは既存の完成したジョブのために、そのマニフェストに従って、すべての結果が1つのNDJSONファイルに保存されます。 新しい出力パスを使用して、コンバインドファイルでインポート監査を実行します。 結果をダウンロード 配信されたメディアを記述; 彼らはMP4またはオーディオバイトではありません。

### 既存のジョブからすべての部品をフェッチする

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

- [データセットのカバレッジをチェックする](https://flashdata.dev/ja/docs/guides/bulk/reference.md#audit)
- [マニフェスト、部品および保持の参照](https://flashdata.dev/ja/docs/reference/bulk-processing/reference.md#downloadBulkJobManifest)

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

## 保管場所への配送

このコマンドを実行する前に、作業フォルダ内の storage.json としてプロバイダの認証情報を保存します。 以下にリンクされているプロバイダフィールドを使用して、ファイルをプライベートに保ちます。 CLIの--storage-configは、このJSONファイルを読み、result_storageを選択して、メディアのデータやストレージを選択します。 --optionsは、JSONをインラインではなく、ファイルパスもかかります。

- [プロバイダーの資格フィールド](https://flashdata.dev/ja/docs/sources/youtube_download/reference.md#storage)
- [貯蔵配達および目的パス](https://flashdata.dev/ja/docs/reference/bulk-processing/reference.md#storage)
- [Bulk APIリクエストの設定](https://flashdata.dev/ja/docs/reference/bulk-processing/reference.md#playground)

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

### 保存されたストレージ構成で実行する

#### メタデータワークフローにストレージを追加する

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

