# Realtimeと非同期

応答で結果を取得するか、ジョブを送信して後でそれらを取得します。 アプリケーションやエージェントが作業を待ち合わせる方法を選択します。

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

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

## モードリクエストを選択する

Google Search と YouTube Data は両方のモードをサポートしています。 YouTube Downloadは非同期、Batch、Bulkを要求します;それは実時間を支えるしません。 ソースパラメータは、リアルタイムから非同期に切り替えるときに同じままになります。

| モード | 使用時 | 受け取るもの |
| --- | --- | --- |
| Realtime | 現在のインタラクションでは検索結果が必要になります。 | 同じ HTTP 応答の結果ボディ。 |
| Async | プロセスが切断された後、またはメディアのダウンロード後に作業を続ける必要があります。 | すぐに仕事ID;別々の状態および結果を得て下さい。 |

### ライフサイクルの要求

```text
Realtime POST data.flashdata.dev/v1/queries/realtime → 結果
Async POST data.flashdata.dev/v1/queries → ジョブ ID
          GET api.flashdata.dev/v2/jobs/{id} → ステータス
          GET api.flashdata.dev/v2/jobs/{id}/results → 結果
```

- [多数の質問を提出する?](https://flashdata.dev/ja/docs/reference/batch-and-bulk/reference.md)

<a id="submit"></a>

## リクエストを送信

FLASHDATA_API_KEYをgoogle_searchのキーに設定します。 リアルタイムまたは非同期を選択します。各投稿は1つの請求可能な検索を実行します。 スクリプト、レシート、結果は同じ新しい作業フォルダーに保持します。

Python の例には Python 3.10+ と Requests を使います。各スクリプトは独立して実行され、前の手順で保存したファイルを読み込みます。cURL の例には Bash、cURL 7.76+、jq が必要です。

### Python · 一度取付けて下さい

```bash
python3 -m pip install requests
```

- [API キーとヘッダー](https://flashdata.dev/ja/docs/guides/headers-and-authentication/reference.md)
- [Google Searchパラメータ](https://flashdata.dev/ja/docs/sources/google_search/reference.md)

<a id="realtime"></a>

### Realtime: 結果を得る

POST /v1/queries/realtime は status: done と結果の配列を返します。 result.json を読んで下さい; ポーリングは必要ではないです。

#### Python

realtime.pyとして保存し、python3 realtime.pyを実行します。

##### realtime.py

```python
import json
import os
from pathlib import Path

import requests

response = requests.post(
    "https://data.flashdata.dev/v1/queries/realtime",
    headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
    json={"source": "google_search", "query": "battery recycling research", "params": {"num": 5}},
    timeout=120, allow_redirects=False,
)
response.raise_for_status()
result = response.json()
Path("result.json").write_text(json.dumps(result, indent=2), encoding="utf-8")
print(json.dumps(result, indent=2))
```


#### cURL / Bash

##### 結果を得る · cURL/Bash

```bash
curl --fail-with-body --silent --show-error \
  'https://data.flashdata.dev/v1/queries/realtime' \
  --header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{"source":"google_search","query":"battery recycling research","params":{"num":5}}' \
  --output result.json &&
jq '{source, status, results, usage}' result.json
```



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

### Async:仕事のレシートを救いて下さい

POST /v1/queriesは、検索結果ではなく、保留ジョブレシートを返します。 submission.jsonを保存し、ステータスと結果のリクエストを続けてください。

#### Python

submit_async.pyとして保存し、python3 submit_async.pyを実行します。

##### submit_async.py

```python
import json
import os
from pathlib import Path

import requests

response = requests.post(
    "https://data.flashdata.dev/v1/queries",
    headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
    json={"source": "google_search", "query": "battery recycling research", "params": {"num": 5}},
    timeout=30, allow_redirects=False,
)
response.raise_for_status()
result = response.json()
Path("submission.json").write_text(json.dumps(result, indent=2), encoding="utf-8")
print(json.dumps(result, indent=2))
```

##### 受信フィールド・省略例

```json
{
  "id": "job_EXAMPLE",
  "source": "google_search",
  "status": "pending"
}
```


#### cURL / Bash

##### ジョブの送信と保存 ID · cURL / Bash

```bash
curl --fail-with-body --silent --show-error \
  'https://data.flashdata.dev/v1/queries' \
  --header "X-API-Key: ${FLASHDATA_API_KEY:?Set 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
```

##### 受信フィールド・省略例

```json
{
  "id": "job_EXAMPLE",
  "source": "google_search",
  "status": "pending"
}
```



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

## async ジョブをチェックする

submission.jsonのIDを使用してjob.statusを読んで下さい。 保留または処理のために、再度点検する前にRetry-Afterの遅れを待って下さい; Pythonはそれを印刷し、cURLはstatus-headers.txtでそれを救う。 ヒントが返されない場合、バックオフを使用してください。 ジョブが完了した状態のリクエストは、ジョブが終了したという意味ではありません。

| job.status | 次のアクション |
| --- | --- |
| pending / processing | その後、同じジョブIDを再度確認します。 |
| completed | 保存した結果を取得します。 |
| failed | job.error を読んで下さい。 新規作業を提出する前に原因を修正しました。 |

### Python

job_status.pyとして保存し、python3 job_status.pyを実行します。

#### job_status.py

```python
import json
import os
from pathlib import Path

import requests

job_id = json.loads(Path("submission.json").read_text(encoding="utf-8"))["id"]
response = requests.get(
    f"https://api.flashdata.dev/v2/jobs/{job_id}",
    headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
    timeout=30, allow_redirects=False,
)
response.raise_for_status()
Path("job.json").write_text(json.dumps(response.json(), indent=2), encoding="utf-8")
print(json.dumps(response.json()["job"], indent=2))
print("Retry-After:", response.headers.get("Retry-After", "not provided"))
```


### cURL / Bash

#### 読み取りステータス · cURL / Bash

```bash
JOB_ID=$(jq -er '.id' submission.json)
curl --fail-with-body --silent --show-error \
  "https://api.flashdata.dev/v2/jobs/$JOB_ID" \
  --header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
  --dump-header status-headers.txt --output job.json &&
jq '.job | {id, source, status, error}' job.json
```



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

## 完了した結果を取得する

job.statusが完成したらこれを実行します。 デフォルト結果の応答は、302: 署名されたストレージURLに位置ポイントです。 FlashData に API キーを保ち、元の JSON を result.json に保存します。 YouTube Download では、この JSON は、ストレージに配信されたメディアを記述します。それはビデオやオーディオファイルではありません。

### Python

job_result.pyとして保存し、python3 job_result.pyを実行します。

#### job_result.py

```python
import json
import os
from pathlib import Path

import requests

receipt = json.loads(Path("submission.json").read_text(encoding="utf-8"))
job_id = receipt["id"]
response = requests.get(
    f"https://api.flashdata.dev/v2/jobs/{job_id}/results",
    headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
    timeout=30, allow_redirects=False,
)
response.raise_for_status()
if response.status_code != 302:
    raise RuntimeError(f"Expected a result redirect, got {response.status_code}")
url = response.headers["Location"]
if not url.startswith("https://"):
    raise ValueError("Expected an HTTPS storage URL")

# A separate request: no FlashData key is sent to storage.
result = requests.get(url, timeout=120)
result.raise_for_status()
data = result.json()  # Requests automatically decodes Content-Encoding: gzip.
Path("result.json").write_text(json.dumps(data, indent=2), encoding="utf-8")
print(json.dumps(data, indent=2))
```


### cURL / Bash

#### フェッチオリジナル JSON · cURL / Bash

```bash
JOB_ID=$(jq -er '.id' submission.json)
RESULT_URL=$(curl --fail-with-body --silent --show-error \
  "https://api.flashdata.dev/v2/jobs/$JOB_ID/results" \
  --header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
  --output /dev/null --write-out '%{redirect_url}') &&
curl --fail-with-body --silent --show-error --compressed --proto '=https' \
  "${RESULT_URL:?Expected a signed result URL}" --output result.json &&
jq '{source, status, results, usage}' result.json
```


- [JSON、テキストとMarkdownフォーマット](https://flashdata.dev/ja/docs/guides/response-formats/reference.md#completed-results)
- [ストレージのセットアップをダウンロード](https://flashdata.dev/ja/docs/guides/youtube-download-guide/reference.md)

<a id="recovery"></a>

## ハンドルの遅延および失敗

| 投稿ナビゲーション | 対処方法 |
| --- | --- |
| 提出期限切れ | POST は既に受け付けております。 保存したレシートとアカウントの履歴を返済する前にチェックしてください。 繰り返したPOSTは、新しい請求可能なジョブを作成できます。 |
| 409 · result_not_ready | ポーリング状態を保持します。 別のジョブを作成しないでください。 |
| 422 · result_not_ready | ジョブが失敗しました。 再試行の前にjob.errorを読んで下さい。 |
| 429 | 名誉 Retry-After または retry_after; 保留容量が満たしたときに提出率を削減します。 |
| 410 · result_expired | 保存された結果は、完了後、24時間を終了します。 保存したコピーを使用してください。 |

- [エラーとステータスコード](https://flashdata.dev/ja/docs/errors/reference.md)
- [CLI, ポーリングとwebhookウォークスルー](https://flashdata.dev/ja/docs/guides/async-batch/reference.md)
