# Realtime and async

الحصول على نتائج في الاستجابة، أو تقديم وظيفة واسترجاعها في وقت لاحق. اختر كيف أن طلبك أو وكيلك ينتظر العمل

مرجع كانوني: https://flashdata.dev/ar/docs/reference/realtime-and-async
Reviewed: 2026-11-04 by FlashData

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

## اختر طريقة الطلب

وتدعم شركة Google Search و YouTube Data كلا الأسلوبين. وتحتاج YouTube Download إلى الأسينك أو Batch أو Bulk؛ وهي لا تدعم الوقت الحقيقي. معايير المصدر تبقى كما هي عندما تتحول من الزمن الحقيقي إلى (أسينك)

| Mode | الاستخدام | ما تحصل عليه |
| --- | --- | --- |
| Realtime | وثمة حاجة إلى نتيجة بحثية في التفاعل الحالي. | The result body in the same HTTP response. |
| Async | العمل يجب أن يستمر بعد عملية قطع الاتصالات الخاصة بك، أو كنت تحميل وسائل الإعلام. | معرّف المهمة فورًا؛ استرجع الحالة والنتائج بشكل منفصل. |

### طلب دورة حياة

```text
Realtime  POST data.flashdata.dev/v1/queries/realtime → النتائج
Async     POST data.flashdata.dev/v1/queries          → معرّف المهمة
          GET  api.flashdata.dev/v2/jobs/{id}         → الحالة
          GET  api.flashdata.dev/v2/jobs/{id}/results → النتائج
```

- [تقديم الكثير من الاستفسارات؟](https://flashdata.dev/ar/docs/reference/batch-and-bulk/reference.md)

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

## أرسل طلبًا

المجموعة FLASHDATA_API_KEY إلى المفتاح الذي يسمح google_search. اختيار الوقت الحقيقي أو الأسينك؛ ويُجرى كل طلب بحثاً واحداً قابلاً للابتداء. احتفظ بالكتابات و الإيصالات و النتائج في نفس ملف العمل الجديد

Python أمثلة Python 3.10و طلبات ويدير كل نص بشكل مستقل ويقرأ الملفات المحتفظ بها من الخطوات السابقة. The cURL الاحتياجات البديلة Bash, cURL 7.76+ jq.

### Python · install once

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

- [API المفتاح والراسخ](https://flashdata.dev/ar/docs/guides/headers-and-authentication/reference.md)
- [مقياس Google Search](https://flashdata.dev/ar/docs/sources/google_search/reference.md)

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

### Realtime: الحصول على النتيجة الآن

POST /v1/queries/realtime returns status: done and a results array. اقرأ result.json؛ ولا يلزم إجراء أي اقتراع.

#### Python

انقذوا realtime.py و اديروا "بيثون" 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: Provide a job receipt

يعيد POST /v1/queries إيصال مهمة معلّقة وليس نتائج البحث. احفظ submission.json وتابع بطلبات الحالة والنتائج أدناه.

#### Python

انقذوا submit_async.py و اديروا "بيثون" 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

##### Submit and save the job 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>

## تحقق من وظيفة الأسينك

اقرأ job.status باستخدام ID في submission.json. في انتظار أو تجهيز، في انتظار Retry-After (أ) التأخير قبل التدقيق مرة أخرى؛ Python يطبعه و cURL يوفره في status-headers.txt. استعمل التراجع إذا لم يُعاد أي تلميحات. ولا يعني نجاح طلب المركز أن المهمة قد اكتملت.

| job.status | الإجراء التالي: |
| --- | --- |
| pending / processing | انتظر، ثم تحقق من نفس العمل ID مرة أخرى. |
| completed | إسترجع النتيجة المنقذة |
| failed | إقرأْ job.error. اصلح القضية قبل تقديم عمل جديد |

### Python

انقذوا job_status.py و اديروا "بيثون" 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. ويحتفظ الطلبان الواردان أدناه بمفتاح API الخاص بك على FlashData، ويحتفظان بالرقم الأصلي JSON إلى result.json. For YouTube Downloadهذا JSON يصف وسائل الإعلام التي تم تسليمها إلى مخزنك، وليس الفيديو أو الملف الصوتي.

### Python

انقذوا job_result.py و اديروا "بيثون" 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, text and Markdown formats](https://flashdata.dev/ar/docs/guides/response-formats/reference.md#completed-results)
- [مجموعة تخزين الحمولة](https://flashdata.dev/ar/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; Reduc submission rate when pending capacity is full. |
| 410 · result_expired | وتنتهي النتائج المخزنة بعد انتهاء ساعات العمل المحددة برقم 24. إستخدم نسختك المنقذة |

- [الأخطاء ورموز الحالة](https://flashdata.dev/ar/docs/errors/reference.md)
- [CLI, polling and webhook walk](https://flashdata.dev/ar/docs/guides/async-batch/reference.md)
