# Async طلبات دفعة

تشغيل المعلومات الأساسية لطلب أو وكيل، استئناف من وظيفته المنقذة ID و تجمع كل حصّة

مرجع كانوني: https://flashdata.dev/ar/docs/guides/async-batch
Reviewed: 2026-11-05 by FlashData

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

## تابعي العمل بعد توقف عملية

استخدم مهمة في الخلفية لعمل تطبيقي في الطابور أو لسير عمل وكيل يمكن إكماله لاحقًا. ينفّذ هذا الدليل بحث Google واحدًا، ويحفظ إيصال الاستلام، ويستأنف من ذلك الإيصال في عملية أخرى.

| استمر | الغرض |
| --- | --- |
| إيصال المهمة | submission.json — احتفظ بمعرّف المهمة المقبولة مع مهمة تطبيقك ومدخلاتها الأصلية. |
| الاستجابة المحتفظ بها | result.json — تحقق من مصدره ونتائجه قبل استيراده. |
| نواتج Batch | batch-results/outcomes.json — سجل لكل مدخل، مع معرّف مهمته وملف النتيجة. |

- [Realtime مقابل Async](https://flashdata.dev/ar/docs/reference/realtime-and-async/reference.md#choose)
- [Batch مقابل Bulk](https://flashdata.dev/ar/docs/reference/batch-and-bulk/reference.md#choose)
- [افتحوا بناة سير العمل](https://flashdata.dev/ar/docs/guides/async-batch/reference.md#customize)

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

## قبل أن تبدأ

استخدم مفتاح API بصلاحية google_search ورصيد متاح. اختر CLI أو HTTP للإرسال والانتظار والاسترجاع. تستخدم أمثلة Bash الأداة jq؛ ويتطلب HTTP أيضًا cURL 7.76+. شغّل في مجلد عمل جديد.

### CLI

أعيدي استخدامك الموثّق CLI لمحة عامة FLASHDATA_API_KEY. Confirm data.accessVerified هو true. المجموعة FLASHDATA_PROFILE من أجل ملف مسمّى لذا في وقت لاحق يستعمله السيناريوهات أيضا وإذا لم يتم تشكيل أي مفتاح، استخدم دليل التوثيق الخاص بشركة CLI أولاً.

#### حرية الدخول والفحص الحسابي

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

- [تركيب وتوثيق CLI](https://flashdata.dev/ar/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
```

- [Create an API key](https://flashdata.dev/app/api-keys)

- [تجربة الوكيل وربط الحساب](https://flashdata.dev/ar/docs/guides/agent-onboarding/reference.md)
- [تسعير الشيك](https://flashdata.dev/ar/docs/guides/credits-and-billing/reference.md)

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

## أجري بحثاً عن خلفية

This walkthrough submit one Google Search. ولا تقدم عمليات التحقق من الوضع واسترجاع النتائج استفساراً آخر. إعادة استخدام نفس الإبداع في جميع أنحاء.


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

## 1. تقدم مرة واحدة وحافظ على الاستلام

The submission.json الملف هو إيصالك وتعيد شركة HTTP وصلات id, source, status and self/results؛ ووفرت شركة CLI الإيصال تحت الطلب، كما أعادت شركة remoteId. HTTP 200 means accepted, not completed.

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

A successful wait returns data.status: completed in 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

يفحص هذا الأمر مرة واحدة. كرر GET بعد انتظار قصير ما دامت job.status هي pending أو processing. عند 429، انتظر حسب Retry-After في job-headers.txt.

#### 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, a صفيفة نتائج وإستعمال. المصادقة الواردة أدناه تقبل النتيجة المخزنة تم أو أكملت حالة النجاح.

### 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/ar/docs/guides/google-search-guide/reference.md#results)

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

## 4. استخدم النتيجة في طلبك

نقيم الاستجابة المنقذة، ثم نستخرج اللقب والربط والقنبل من أجل مشهد بحث أو الخطوة التالية للوكيل. فالصفيفة العضوية الفارغة الناجحة لا تعني أي تطابق في البنود؛ فالميدان المفقود أو الجسم الفاشل يحتاج إلى تحقيق.

| مهمة التطبيق | المرحلة الانتقالية |
| --- | --- |
| الانتظار | امتنع عن العمل المقبول ID قبل إعادة السيطرة إلى المستعمل أو الوكيل. |
| جاهز | (مارك) جاهز بعد أن يتم إنقاذه والتحقق منه. إستخدم مهمتك ID كما import/upsert المفتاح |
| الحاجة إلى الاهتمام | حافظ على العمل 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/ar/docs/guides/save-results/reference.md)

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

## الاستهلاك في عملية أخرى

افتح طرفية جديدة في المجلد نفسه، باستخدام بيانات الاعتماد والملف الشخصي نفسيهما. تقرأ هذه الأوامر المهمة من submission.json وتحفظها باسم ملف جديد. لا ترسل عملًا جديدًا مطلقًا. تتطلب إعادة استخدام معرّف تنفيذ CLI نفسه دليل الحالة الأصلي؛ ولا يمنع HTTP تكرار POST اعتمادًا على معرّف التنفيذ المحلي.

### CLI + jq · recover the save job

```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/ar/docs/guides/agent-recovery/reference.md#recover)

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

## Submit several queries

وتقدم شركة Batch وظائف مستقلة في طلب واحد. ويحتاج هذا المثال الثنائي المستوى إلى قدرة على ما لا يقل عن سؤالين ووظيفتين معلقتين؛ وتقتصر التجربة المؤقتة على وظيفة واحدة. احفظوا الصفوف الواردة أدناه 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>

### Save collect-batch.py

أنشئ collect-batch.py في مجلد عمل Batch بجانب batch.json وbatch-submission.json. انسخ الكود الكامل أدناه إليه واحفظه.

استمر batch.json, batch-submission.json و طلقات الدفع معاً ويتوقف النص إذا تغيرت المدخلات أو الإيصالات الموفرة. It reuses completed local files and never submit replacement queries after a read error.

#### 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 الموثقة. وهو يعمل مع أي من أسلوبي التقديم أعلاه. ويقرأ كل إيصال، وينتظر دقيقتين لكل وظيفة غير مكتملة، ويوفّر كل رد ناجح. تشغيل جامع واحد في وقت واحد؛ وإعادة تشغيله لمواصلة نفس الوظائف.

توقّع مدخلين في batch-results/outcomes.json لهذا المثال. استورد المدخلات المكتملة حسب فهرس الإدخال ومعرّف المهمة. تظل مدخلات failed وpending و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/ar/docs/reference/batch-and-bulk/reference.md#batch-results)
- [سجل الطلبات رقم IDs](https://flashdata.dev/ar/docs/guides/enrich-youtube-videos/reference.md)

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

## استلام موقع الإنجاز على شبكة الإنترنت(ح)

يضاف callback_url إلى جانب المصدر والاستفسارات والبارامات في طلب واحد أو في كل من دخول Batch. يستعاض عن المثال URL بمستقبلك. وتُبلغ الأحداث عن الإنجاز أو الفشل؛ وتسترد النتيجة على حدة.

1. أفسد الحدث وأرجع 2x على الفور Deduplicate delivery_id (also sent as X-Delivery-Id).
2. هذا الحدث غير موقع. اجمعي مظهره و مصدره إلى إيصالك المنقذ، ثم توثّق على حالة قراءة باستخدام وصلة الاستلام الأصلية. لا تثق 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/ar/docs/guides/async-batch/reference.md#customize)

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

### متطلبات التردد URL

استخدم رابط HTTPS عامًا على المنفذ 443 بطول أقصاه 2,048 حرفًا، دون بيانات اعتماد أو جزء رابط. يجب أن تكون جميع عناوين IP الناتجة عامة. احذف callback_url أو استخدم null أو سلسلة فارغة لتعطيل الإشعارات.


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

## استرداد وظيفة قائمة

| الحالة | الإجراء المطلوب |
| --- | --- |
| وقت تقديم الطلب | افحص runs show async-first وسجل History للحساب. يستطيع runs recover استرجاع معرّفات المهام المقبولة؛ وإذا لم يُحفظ معرّف، فحقق في الإرسال قبل إرسال POST آخر. |
| pending / processing | استمري بتفقد العمل الحالي هذه الولايات ليست إخفاقات |
| failed / 422 | اقرأ job.errorلتصحيح القضية و تقرر ما إذا كان يجب تقديم عمل جديد |
| 429 | الشرف Retry-After. خفض تطابق الطلبات إذا كانت القدرة على العمل في انتظار التنفيذ كاملة. |
| 404 / 409 | 404: تحقق من المعرّف والحساب الذي أرسل المهمة. 409: النتائج ليست جاهزة بعد. |
| 410 | تنتهي مدة خدمة JSON بساعة 24 بعد إتمامها. إستخدم نسختك المنقذة وسائل الإعلام وصلت بالفعل إلى مخزنك تتبع سياسة التخزين |

- [الحد من المعدل واستخدامه](https://flashdata.dev/ar/docs/guides/usage-and-limits/reference.md)
- [CLI](https://flashdata.dev/ar/docs/guides/cli-automation/reference.md#recover)

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

## تشغيل وظيفة YouTube Download؟

ويستخدم الحمولة الأسينك أو Batch، ويحتاج إلى مالك مفتاح API مع وصول youtube_download زائداً مخزناً للمقصد. وتصف النتيجة التي توصلت إليها شركة JSON وسائط الإعلام التي سلمت بالفعل إلى دلك؛ أما نقطة نهاية النتائج فهي لا تبث أشرطة الفيديو. استخدم دليل التحميل لتخزين الملفات والتحقق من ملفها

- [تخزين المعلومات ونقلها](https://flashdata.dev/ar/docs/guides/youtube-download-guide/reference.md)
- [التحقق من وسائط الإعلام التي تم تسليمها](https://flashdata.dev/ar/docs/guides/youtube-download-guide/reference.md#verify-media)

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

## المستضيفون وصيغ الاستجابة

جميع الأربعة يستخدمون X-API-Key. استخدم نفس مفتاح الطلب. الوضع والنتيجة محرران ولكنهما محدودان السعر. وتستخدم الأمثلة JSON؛ واختيار Accept و X-Respond-With في البناية لتمثيل النتائج الأخرى. ويستخدم تحميل موقّع للتخزين (URL) دون مفتاح FlashData.

| العملية | نقطة النهاية |
| --- | --- |
| تقدم وظيفة واحدة | 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 and async protocol](https://flashdata.dev/ar/docs/reference/realtime-and-async/reference.md)
- [Batch](https://flashdata.dev/ar/docs/reference/batch-and-bulk/reference.md)
- [قواعد شكل الاستجابة](https://flashdata.dev/ar/docs/guides/response-formats/reference.md)

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

## المصادر والطرائق المدعومة

استخدموا البنّاء في الأسفل من أجل معايير المصدر الحالية ودعمت شركة Google Search و YouTube Data وظائف أساسية. وتستخدم شركة YouTube Download وظائف خلفية وتخزين مقصد. وللاطلاع على ملف كبير للفيديو IDs مع خيارات مشتركة، استخدم دليل Bulk.

- [أساليب الطلب](https://flashdata.dev/ar/docs/reference/realtime-and-async/reference.md#choose)
- [Bulk file workflow](https://flashdata.dev/ar/docs/guides/bulk/reference.md)

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

## بناء تدفق العمل لمصدرك

اختر مصدرًا، حرّر بارامتراته ونسخ تدفق العمل المولد في لغتك. يمكن أن نعيد الإتصال لكي نكشف عن مثال المستلم هذا البنّاءِ يَمْتحُ قبل إستجاباتَ شفرةَ وعيّنةِ؛ الطلباتِ لا تَرْكُل إلاّ عندما تَعْملُ الرمزَ أَو يَستعملُ القنينةَ.

- [بارامترات المصدر والكيميائيات](https://flashdata.dev/ar/docs/reference/reference.md)
