# Async & バッチリクエスト

アプリケーションやエージェントのバックグラウンドワークを実行し、保存されたジョブIDから再開し、すべてのバッチ結果を収集します。

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

<a id="choose"></a>

## プロセスが停止した後の作業を続けて下さい

キュートなアプリケーションタスクや、finish を後で実現できるエージェントワークフローのバックグラウンドジョブを使用します。 このウォークスルーは、1つのGoogle検索を実行し、その領収書を保存し、別のプロセスでその領収書から再開します。

| 保存する | 目的: |
| --- | --- |
| ジョブの受付情報 | submission.json — アプリケーションタスクと元の入力で受け入れられたジョブIDを維持します。 |
| 保存された応答 | result.json — インポートする前にソースと結果を検証します。 |
| Batch 結果 | batch-results/outcomes.json — 1 回の入力につき 1 回のエントリーで、ID と result のファイルを使用します。 |

- [Realtime と非同期](https://flashdata.dev/ja/docs/reference/realtime-and-async/reference.md#choose)
- [Batch 対 Bulk](https://flashdata.dev/ja/docs/reference/batch-and-bulk/reference.md#choose)
- [ワークフロービルダーを開く](https://flashdata.dev/ja/docs/guides/async-batch/reference.md#customize)

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

## はじめる前に

google_searchアクセスと利用可能なクレジットでAPIキーを使用します。 CLI または HTTP を選択して、送信、待機、検索を行います。 Bashの例はjqを使用します; HTTP は cURL 7.76+ を必要とします。 新しい作業フォルダで実行します。

### CLI

認証されたCLIプロファイルまたはFLASHDATA_API_KEYを再利用します。 data.accessVerifiedはtrueです。 セットセット FLASHDATA_PROFILE 名前付きプロファイルのため、後でスクリプトも使用しています。 キーが設定されていない場合は、まず CLI 認証ガイドを使用してください。

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

```bash
flashdata auth status --json
flashdata account balance --json
flashdata account limits --json
```

- [CLIをインストールして認証する](https://flashdata.dev/ja/docs/guides/flashdata-cli/reference.md#existing-key)

### HTTP / cURL

残りのコマンドでこのターミナルが開きます。 エージェントは、秘密ストアや環境からキーを読み込む必要があります。

#### APIキーを設定する

```bash
# Bash: paste the key into a hidden prompt, not into this command.
read -r -s -p "FlashData API key: " FLASHDATA_API_KEY
printf '\n'
export FLASHDATA_API_KEY
```

- [APIキーを作成する](https://flashdata.dev/app/api-keys)

- [エージェントの試用とアカウント連携](https://flashdata.dev/ja/docs/guides/agent-onboarding/reference.md)
- [価格をチェックする](https://flashdata.dev/ja/docs/guides/credits-and-billing/reference.md)

<a id="job-lifecycle"></a>

## 背景検索を実行

このウォークスルーは、Google Searchを1つ提出します。 ステータスチェックと結果の検索は、別のクエリを送信しません。 全体で同じ資格を再利用します。


<a id="async-batch"></a>

## 1. 一度提出し、領収書を保管してください

submission.jsonファイルはあなたのレシートです。 HTTPは、ID、ソース、ステータス、self/resultsリンクを返します。 CLI は、投稿時にレシートを保存し、remoteId も返します。 HTTP 200は、承認されず、終了しません。

### CLI

#### Bash · FlashData CLI

```bash
flashdata search "battery recycling research" --num 5 \
  --mode async --run-id async-first --output submission.json --json
```


### HTTP / cURL

#### Bash · cURL + jq

```bash
(
set -euC
: "${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY first}"
test ! -e submission.json || { echo "Use the saved receipt or a new filename." >&2; exit 1; }
curl --fail-with-body --silent --show-error \
  --request POST 'https://data.flashdata.dev/v1/queries' \
  --header "X-API-Key: $FLASHDATA_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"source":"google_search","query":"battery recycling research","params":{"num":5}}' \
  --output submission.json
jq '{id, source, status, links}' submission.json
)
```



<a id="job-status"></a>

## 2. 既存のジョブの待ち合わせ

ジョブが完了したら続行します。 失敗した場合は、他のものを提出する前にエラーを調べます。

### CLI

成功した待機リターン data.status: completed でん CLI JSON.

#### Bash · FlashData CLI

```bash
(
set -euC
JOB_ID=$(jq -er '.remoteId // .id // .submission.id' submission.json)
flashdata jobs wait "$JOB_ID" --timeout 2m --json
)
```


### HTTP / cURL

一度チェックします。 job.statusが保留中や処理中に短時間後にGETを繰り返します。 429では、job-headers.txtからRetry-Afterを待ちます。

#### Bash · cURL + jq

```bash
(
set -euC
: "${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY first}"
JOB_ID=$(jq -er '(.remoteId // .id // .submission.id) | select(test("^[A-Za-z0-9_-]+$"))' submission.json)
STATUS_URL="https://api.flashdata.dev/v2/jobs/$JOB_ID"
curl --fail-with-body --silent --show-error \
  --header "X-API-Key: $FLASHDATA_API_KEY" \
  --max-time 30 --dump-header job-headers.txt --output job.json "$STATUS_URL"
jq -e --arg id "$JOB_ID" '.job.id == $id' job.json >/dev/null
jq '.job | {id, source, status, error}' job.json
)
```

#### 完了状態・イラスト HTTP 応答

```json
{
  "job": {
    "id": "EXAMPLE_JOB_ID",
    "source": "google_search",
    "status": "completed",
    "error": null
  }
}
```



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

## 3. 応答の取得と保存

result.jsonをローカルに保存します。 完了したジョブとその結果のボディは別のレコードです: この検索のボディにはソースが含まれています: google_search、結果の配列および使用法。 下記の検証は、保存された結果の完了または完了した成功ステータスを受け入れます。

### CLI

#### Bash · FlashData CLI

```bash
(
set -euC
JOB_ID=$(jq -er '.remoteId // .id // .submission.id' submission.json)
flashdata jobs result "$JOB_ID" --output result.json --json
jq '{source, status, results, usage}' result.json
)
```


### HTTP / cURL

デフォルトでは、JSON 結果が署名されたストレージにリダイレクトされます。 このコードは保存された結果を解凍し、また直接JSON応答を受け入れます。 FlashDataエンドポイントのみがAPIキーを受信します。

#### Bash · cURL + jq

```bash
(
set -euC
: "${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY first}"
JOB_ID=$(jq -er '(.remoteId // .id // .submission.id) | select(test("^[A-Za-z0-9_-]+$"))' submission.json)
SOURCE=$(jq -er '(.submission // .).source' submission.json)
jq -e --arg id "$JOB_ID" --arg source "$SOURCE" \
  '.job.id == $id and .job.source == $source and .job.status == "completed"' job.json >/dev/null
test ! -e result.json || { echo "Choose a new output filename." >&2; exit 1; }
RESULT_URL="https://api.flashdata.dev/v2/jobs/$JOB_ID/results"
STATUS=$(curl --silent --show-error \
  --header "X-API-Key: $FLASHDATA_API_KEY" \
  --max-time 120 --dump-header result-headers.txt --output result.pending \
  --write-out '%{http_code}' "$RESULT_URL")
case "$STATUS" in
  200) ;;
  302)
    LOCATION=$(awk 'tolower($1) == "location:" { sub(/\r$/, "", $2); print $2 }' result-headers.txt)
    # The signed storage URL is fetched WITHOUT the FlashData API key.
    curl --fail-with-body --silent --show-error --compressed --max-time 120 --proto '=https' \
      --output result.pending "$LOCATION" ;;
  *) echo "Result HTTP $STATUS; inspect result.pending and result-headers.txt." >&2; exit 1 ;;
esac
jq -e --arg source "$SOURCE" '.source == $source and (.status == "done" or .status == "completed")
  and (.results | type == "array")' result.pending >/dev/null
cat result.pending > result.json
jq '{id, source, status, results, usage}' result.json
)
```


- [検索結果を調べて保存する](https://flashdata.dev/ja/docs/guides/google-search-guide/reference.md#results)

<a id="use-result"></a>

## 4. アプリケーションで結果を使う

保存された応答を検証し、検索ビューまたはエージェントの次のステップでタイトル、リンク、スニペットを抽出します。 成功した空の有機配列は、マッチングアイテムを意味しません。 不足しているフィールドまたは失敗したボディは調査を必要とします。

| アプリケーションタスク | トランジット |
| --- | --- |
| 待ち合わせ | ユーザやエージェントにリモコンする前に、受け入れられたジョブIDを主張します。 |
| レディー | 結果が保存され、検証されるとマークが準備完了します。 import/upsertキーとしてあなたの仕事IDを使用して下さい。 |
| 注意が必要 | ID とエラーをキープします。 ポーリングタイムアウトやリトリーバル障害は、再度提出するリクエストではありません。 |

### ローカル応答を読む · API 呼び出しなし

```bash
jq -e '.source == "google_search" and (.status == "done" or .status == "completed")
  and (.results | type == "array")
  and all(.results[]; (.organic | type == "array"))' result.json > /dev/null &&
jq -c '.results[] | .organic[] | {title, link, snippet}' result.json
```

- [応答のアーカイブと再利用](https://flashdata.dev/ja/docs/guides/save-results/reference.md)

<a id="resume"></a>

## 別のプロセスで再開

同じフォルダに新しいターミナルを開き、同じcredential/profile.で これらのコマンドは、submission.json でジョブを読み、新しいファイル名に保存します。 作品の提出は絶対に行いません。 同じ再利用 CLI ログイン ID 元のステートディレクトリが必要です。 HTTP自体は、そのローカルランIDを使用してPOSTを複製しません。

### CLI + jq · 保存されたジョブを回復

```bash
(
set -eu
JOB_ID=$(jq -er '.remoteId // .id // .submission.id' submission.json)
flashdata jobs get "$JOB_ID" --json
flashdata jobs wait "$JOB_ID" --timeout 2m --json
flashdata jobs result "$JOB_ID" --output recovered-result.json --json
)
```

- [未知の投稿結果](https://flashdata.dev/ja/docs/guides/agent-recovery/reference.md#recover)

<a id="batch"></a>

## いくつかの質問を提出する

Batchは、独立したジョブを1つのリクエストで送信します。 この2つのクエリ例では、少なくとも2つのクエリと2つのバックエンドジョブの容量が必要です。一時トライアルは1つに限定されます。 別の作業フォルダ内のbatch.jsonとして下にある配列を保存します。

### batch.json

```json
[
  {
    "source": "google_search",
    "query": "battery recycling research",
    "params": {
      "num": 5
    }
  },
  {
    "source": "google_search",
    "query": "lithium battery recycling methods",
    "params": {
      "num": 5
    }
  }
]
```

### CLI

#### Bash · FlashData CLI

```bash
flashdata batch submit --input batch.json \
  --run-id batch-first --output batch-submission.json --json
```


### HTTP / cURL

#### Bash · cURL + jq

```bash
(
set -euC
: "${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY first}"
test ! -e batch-submission.json || { echo "Keep the saved batch receipt." >&2; exit 1; }
jq '{queries: .}' batch.json > batch-request.json
curl --fail-with-body --silent --show-error \
  --request POST 'https://data.flashdata.dev/v1/queries/batch' \
  --header "X-API-Key: $FLASHDATA_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-binary @batch-request.json --output batch-submission.json
jq '.queries[] | {id, source, status}' batch-submission.json
)
```



<a id="batch-collector"></a>

### 保存 collect-batch.py

作成する collect-batch.py で、 Batch 作業フォルダの横 batch.json とりあえず batch-submission.json. 下記のコードをコピーして保存します。

batch.json、batch-submission.jsonおよびバッチresults/を一緒に保って下さい。 保存された入力やレシートが変更されたらスクリプトは停止します。 ローカルファイルを再使用し、読み込まれたエラー後に置換クエリを提出しません。

#### collect-batch.py

```python
# collect-batch.py — Python 3.10+ and FlashData CLI; no new submissions.
import json
import re
import subprocess
import sys
from pathlib import Path


def read(path):
    return json.loads(Path(path).read_text(encoding='utf-8-sig'))


def cli(*args):
    result = subprocess.run(['flashdata', *args, '--json', '--non-interactive', '--timeout', '2m'],
                            check=True, capture_output=True, text=True, encoding='utf-8')
    return json.loads(result.stdout)['data']


inputs = read('batch.json')
saved = read('batch-submission.json')
receipts = saved.get('submission', saved)['queries']
if not isinstance(inputs, list) or not inputs or len(inputs) != len(receipts):
    raise ValueError('Keep the original batch input and matching receipt.')
ids = [r.get('id', '') for r in receipts]
if len(set(ids)) != len(ids) or any(not re.fullmatch(r'[A-Za-z0-9_-]+', x) for x in ids):
    raise ValueError('Invalid or duplicate job IDs.')
folder = Path('batch-results')
folder.mkdir(exist_ok=True)
binding = json.dumps({'inputs': inputs, 'receipts': receipts}, sort_keys=True)
try:
    with (folder / 'input-receipts.json').open('x', encoding='utf-8') as file:
        file.write(binding)
except FileExistsError:
    if (folder / 'input-receipts.json').read_text(encoding='utf-8') != binding:
        raise ValueError('Inputs or receipts changed. Restore the original snapshot.')

outcomes = [{'index': index, 'input': request, 'job_id': receipt['id'], 'status': 'unread'}
            for index, (request, receipt) in enumerate(zip(inputs, receipts))]
for index, (request, receipt) in enumerate(zip(inputs, receipts)):
    job_id = receipt['id']
    file = folder / (job_id + '.json')
    row = {'index': index, 'input': request, 'job_id': job_id, 'status': 'unread'}
    try:
        if not file.exists():
            try:
                job = cli('jobs', 'wait', job_id)
            except subprocess.CalledProcessError:
                job = cli('jobs', 'get', job_id)
            if job['id'] != job_id or job['source'] != request['source']:
                raise ValueError('Job does not match the saved receipt/input.')
            row.update(status=job['status'], error=job.get('error'))
            if job['status'] == 'completed':
                cli('jobs', 'result', job_id, '--output', str(file))
        if file.exists():
            result = read(file)
            if (result.get('source') != request['source']
                    or result.get('status') not in ['done', 'completed']
                    or not isinstance(result.get('results'), list)):
                raise ValueError('Inspect the saved result before importing it.')
            row.update(status='completed', result_file=str(file), error=None)
    except (OSError, ValueError, KeyError, subprocess.CalledProcessError) as error:
        row.update(status='read_error', error=getattr(error, 'stderr', None) or str(error))
    outcomes[index] = row
    pending = folder / 'outcomes.next'
    pending.write_text(json.dumps(outcomes, ensure_ascii=False, indent=2), encoding='utf-8')
    pending.replace(folder / 'outcomes.json')
    print(index, job_id, row['status'])
print('Saved batch-results/outcomes.json. No queries were submitted.')
sys.exit(0 if all(row['status'] == 'completed' for row in outcomes) else 2)
```


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

### 各応募作品の追跡

collect-batch.py を保存した後、Batch 作業フォルダーと Python 3.10+ と認証された CLI から実行します。 上記送信方法のいずれかで動作します。 領収書を全て読み、未完成ジョブにつき最大2分待って、各々の成功した応答を保存します。 1つのコレクターを一度に実行し、同じジョブを続行するように再実行します。

サンプルのbatch-results/outcomes.jsonの2つの項目を期待して下さい。 入力インデックスとジョブ ID で完了したエントリをインポートします。 失敗、保留、read_error エントリは表示されません。 終了コード 2 は、レビューまたはそれらを再開を意味します。 コレクタは、新しいクエリを送信しません。

#### Bash

```bash
python3 collect-batch.py
```

#### PowerShell 7

```powershell
python collect-batch.py
```

#### 各結果を読む · jq

```bash
jq '.[] | {index, job_id, status, result_file, error}' batch-results/outcomes.json
```

- [Batch 結果モデル](https://flashdata.dev/ja/docs/reference/batch-and-bulk/reference.md#batch-results)
- [アプリケーションレコードをキープして下さい IDs](https://flashdata.dev/ja/docs/guides/enrich-youtube-videos/reference.md)

<a id="webhooks"></a>

## 完成したwebhookを受け取る

callback_url をソース、クエリ、パラメータを単一のリクエストまたは各 Batch エントリに追加します。 受信機で例のURLを置き換えます。 イベントレポートの完了または失敗。結果は別々に取得します。

1. イベントを主張し、2xx を速やかに返します。 delivery_id(またX-Delivery-Idとして送られる)を解読して下さい。
2. イベントが無事に終了します。 保存したレシートにIDとソースを一致させ、元のレシートのセルフリンクを使用してステータスを認証します。 URLsは、統一されたイベントによって供給される信頼しないでください。
3. 完了すると、結果を取得し、保存します。 失敗した場合は、ジョブエラーを調べます。 イベントが到着しない場合は、フォールバックとしてポーリングしてください。

### コールバックでボディをリクエストする

```json
{
  "source": "google_search",
  "query": "battery recycling research",
  "params": {
    "num": 5
  },
  "callback_url": "https://your-app.example/webhooks/flashdata"
}
```

### イベントボディ・イラスト

```json
{
  "delivery_id": "completion:EXAMPLE_JOB_ID",
  "id": "EXAMPLE_JOB_ID",
  "source": "google_search",
  "status": "completed",
  "links": [
    {
      "rel": "self",
      "href": "https://api.flashdata.dev/v2/jobs/EXAMPLE_JOB_ID",
      "method": "GET"
    },
    {
      "rel": "results",
      "href": "https://api.flashdata.dev/v2/jobs/EXAMPLE_JOB_ID/results",
      "method": "GET"
    }
  ]
}
```

- [ワークフロービルダーで受信機を生成](https://flashdata.dev/ja/docs/guides/async-batch/reference.md#customize)

<a id="callbacks"></a>

### コールバック URL 要件

ポート443のパブリックHTTPS URLを使用して、資格情報やフラグメントなしで、ほとんどの2,048文字で。 解決されたIPは公開されなければなりません。 callback_url を省略するか、null または空の文字列を使用して通知を無効にします。


<a id="limits"></a>

## 既存のジョブを回復する

| 投稿ナビゲーション | 対処方法 |
| --- | --- |
| 提出期限切れ | runs showの非同期優先とアカウントHistoryを調べます。 runs recoverは、ジョブIDsを取得することができます。 IDが保存されていない場合は、別のPOSTを送信する前に、投稿を再確認します。 |
| pending / processing | 既存のジョブをチェックしてください。 これらの状態は失敗しません。 |
| failed / 422 | job.errorを読んで、原因を修正し、新しい作品を提出するかどうかを決定します。 |
| 429 | 名誉Retry-After。 保留ジョブの容量が満たしている場合、投稿の円滑性を削減します。 |
| 404 / 409 | 404:IDをチェックし、アカウントを提出する。 409:結果はまだ準備が整っていない。 |
| 410 | 保存結果 JSON は完了後 24 時間を終えます。 保存したコピーを使用してください。 すでにメディアがストレージの保持ポリシーに従って、ストレージに配信されました。 |

- [レート制限と使用量](https://flashdata.dev/ja/docs/guides/usage-and-limits/reference.md)
- [CLIは回復を実行します](https://flashdata.dev/ja/docs/guides/cli-automation/reference.md#recover)

<a id="delivery"></a>

## YouTube Downloadジョブを実行しますか?

ダウンロードは、非同期または非同期で使用 Batch そして所有者を必要として下さい API キーと youtube_download アクセスプラスの宛先ストレージ. その結果、JSONは、既にあなたのバケットに配信されたメディアを記述します。結果のエンドポイントはビデオバイトをストリームしません。 ダウンロードガイドを使用して、ストレージを設定し、配信されたファイルを検証します。

- [ストレージの設定とダウンロード](https://flashdata.dev/ja/docs/guides/youtube-download-guide/reference.md)
- [配信メディアの検証](https://flashdata.dev/ja/docs/guides/youtube-download-guide/reference.md#verify-media)

<a id="api-hosts"></a>

## ホストと応答フォーマット

X-API-Keyの4つの使用すべて。 投稿と同じキーを使用します。 ステータスと結果の読み込みは自由ですが、レート制限されます。 例では、JSON と、Accept と X-Respond-With を他の結果表現のビルダーで使用しています。 署名されたストレージのダウンロードは、FlashDataキーなしで、URLを使用しています。

| 業務内容 | エンドポイント |
| --- | --- |
| 1つのジョブを提出する | POST https://data.flashdata.dev/v1/queries |
| バッチを提出 | POST https://data.flashdata.dev/v1/queries/batch |
| ステータスを読む | GET https://api.flashdata.dev/v2/jobs/{id} |
| 結果を読む | GET https://api.flashdata.dev/v2/jobs/{id}/results |

- [Realtimeと非同期プロトコル](https://flashdata.dev/ja/docs/reference/realtime-and-async/reference.md)
- [Batch リクエストプロトコル](https://flashdata.dev/ja/docs/reference/batch-and-bulk/reference.md)
- [応答形式ルール](https://flashdata.dev/ja/docs/guides/response-formats/reference.md)

<a id="supported-sources"></a>

## サポートされているソースとモード

ソースの現在のパラメータの下のビルダーを使用してください。 Google Search と YouTube Data のサポートの背景ジョブ。 YouTube Downloadは、背景ジョブと保存先のストレージを使用します。 共有オプションでビデオIDsの大きなファイルには、Bulkガイドを使用します。

- [リクエストモード](https://flashdata.dev/ja/docs/reference/realtime-and-async/reference.md#choose)
- [Bulkファイルワークフロー](https://flashdata.dev/ja/docs/guides/bulk/reference.md)

<a id="customize"></a>

## ソースのワークフローを構築

ソースを選択し、パラメータを編集し、生成されたワークフローを言語でコピーします。 呼び出しバックを有効にして、受信機の例を明らかにします。 このビルダーはコードとサンプルのレスポンスをプレビューします。コードを実行したり、コンソールを使用するときにのみリクエストが実行されます。

- [ソースパラメータとスキーマ](https://flashdata.dev/ja/docs/reference/reference.md)
