# Realtime dan async

Waisédon mendapatkan hasil dalam tanggapan, atau mengajukan pekerjaan dan mengambilnya kembali nanti. Kau harus memilih bagaimana aplikasi atau agenmu menunggu pekerjaan.

Referensi boonical: https://flashdata.dev/ms/docs/reference/realtime-and-async
Diulas: 2026-11-04 oleh FlashData

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

## Pilihlah suatu mode permintaan

Google Search dan YouTube Data mendukung kedua mode. YouTube Download membutuhkan async, Batch atau Bulk; tidak mendukung realtime. Parameter sumber tetap sama ketika beralih dari realtime ke async.

| Mode | Use when | Apa yang kau terima |
| --- | --- | --- |
| Realtime | Hasil pencarian diperlukan dalam interaksi saat ini. | Badan hasil dalam respon HTTP yang sama. |
| Async | Pekerjaan kinder harus dilanjutkan setelah proses terputus, atau Anda mengunduh media. | Pekerjaan ID segera; mengambil status dan hasil secara terpisah. |

### Permintaan lifecycle

```text
Realtime  POST data.flashdata.dev/v1/queries/realtime → hasil
Async     POST data.flashdata.dev/v1/queries          → pekerjaan ID
          GET  api.flashdata.dev/v2/jobs/{id}         status →
          GET  api.flashdata.dev/v2/jobs/{id}/results → hasil
```

- [Melepaskan banyak pertanyaan?](https://flashdata.dev/ms/docs/reference/batch-and-bulk/reference.md)

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

## Upn permintaan

FLASHDATA_API_KEY ke kunci yang memungkinkan google_search. Takwidosis memilih realtime atau async; setiap penyerahan menjalankan satu pencarian yang dapat diagihkan. ¡Keep scripts, penerimaan dan hasilkan folder kerja baru yang sama.

Contoh Python menggunakan Python 3.10+ dan Requests. Setiap skrip berjalan secara independen dan membaca file tersimpan dari langkah sebelumnya. Niavia cURL kebutuhan alternatif Bash, cURL 7.76+ dan jq.

### Python · pasang sekali

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

- [kunci dan header API](https://flashdata.dev/ms/docs/guides/headers-and-authentication/reference.md)
- [Parameter Google Search](https://flashdata.dev/ms/docs/sources/google_search/reference.md)

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

### RealtimeDapatkan hasilnya sekarang

POST /v1/queries/realtime mengembalikan status: done dan sebuah result array. Bacalah result.jsonTPS diperlukan.

#### Python

Simpan sebagai realtime.py dan jalankan 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

##### Dapatkan hasil · 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>

### THEAsync: Simpan penerimaan tugas

POST /v1/queries mengembalikan penerimaan kerja yang tertunda, bukan hasil pencarian. Simpan submission.json dan lanjutkan dengan status dan permintaan hasil di bawah.

#### Python

Simpan sebagai submit_async.py dan jalankan 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))
```

##### Medan Receipt · contoh singkatan

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


#### cURL / Bash

##### Memindahkan dan menyimpan pekerjaan 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
```

##### Medan Receipt · contoh singkatan

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



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

## Periksalah sebuah pekerjaan yang sinkron

job.status dibaca menggunakan ID dalam submission.json. Untuk tertunda atau diproses, tunggu penundaan Retry-After sebelum memeriksa lagi; Python mencetaknya dan cURL menyimpannya di status-headers.txt. Use backoff jika tidak ada petunjuk dikembalikan. Permintaan status yang sukses bukan berarti pekerjaan telah selesai.

| job.status | Tindakan berikutnya |
| --- | --- |
| pending / processing | Tunggu, lalu periksa pekerjaan yang sama ID lagi. |
| completed | Ambil hasil yang disimpan. |
| failed | Baca job.error. Fix penyebab sebelum menyerahkan pekerjaan baru. |

### Python

Simpan sebagai job_status.py dan jalankan 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

#### Status baca · 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>

## Peroleh hasil yang telah selesai

Jalankan ini setelah job.status selesai. Respon hasil bakunya adalah 302: Lokasi menunjuk ke penyimpanan yang ditandatangani URL. Dua permintaan di bawah ini menjaga kunci API pada FlashData dan menyimpan JSON asli ke result.json. Untuk YouTube Download, JSON ini menggambarkan media yang disampaikan ke penyimpanan Anda; itu bukan berkas video atau audio.

### Python

Simpan sebagai job_result.py dan jalankan 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

#### Kutip asli 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, teks dan Markdown format](https://flashdata.dev/ms/docs/guides/response-formats/reference.md#completed-results)
- [Persediaan penyimpanan unduhan Muaturun](https://flashdata.dev/ms/docs/guides/youtube-download-guide/reference.md)

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

## Keterlambatan dan kegagalan penanganan

| Situasi Orang Asing | Tindakan |
| --- | --- |
| Submission Timed out | A POST mungkin sudah diterima. Habel Cek penerimaan dan riwayat akun yang telah disimpan sebelum pengiriman kembali; POST berulang dapat membuat pekerjaan baru yang dapat diagih. |
| 409 · result_not_ready | Tetap jajak pendapat. Jangan membuat pekerjaan lain. |
| 422 · result_not_ready | Pekerjaan itu gagal. Baca job.error sebelum mencoba lagi. |
| 429 | Keunggulan Retry-After atau retry_after; mengurangi tingkat penyerahan ketika kapasitas tertunda penuh. |
| 410 · result_expired | Hasil penyimpanan kedaluwarsa 24 jam setelah selesai. Gunakan salinan disimpan Anda. |

- [Ralat dan kod status](https://flashdata.dev/ms/docs/errors/reference.md)
- [CLI, polling dan webhook walkthrough](https://flashdata.dev/ms/docs/guides/async-batch/reference.md)
