# تحقيق النتائج وإعادة استخدامها

الحفاظ على نتيجة بمدخلاته الأصلية، وصلات المصدر، وإستخدامه، ثم تسليمه إلى عملية أخرى دون أي استفسار آخر.

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

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

## Query once, use the result across tasks

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

### ما ستحتفظ به

```text
archive/saved-search/
  الاستفسارات والبارامترات الأصلية من request.json
  response.json       بدون تغيير API الرد
  citations.ndjson titles, source URLs and snippets
  manifest.json run ID, usage, file size and SHA-256
```

- [هل لديكِ بالفعل نتيجة مُلحّة؟](https://flashdata.dev/ar/docs/guides/save-results/reference.md#jobs)
- [Provide a Bulk dataset](https://flashdata.dev/ar/docs/guides/save-results/reference.md#bulk)
- [أبقوا وسائل الإعلام المحملة](https://flashdata.dev/ar/docs/guides/save-results/reference.md#media)

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

## قبل أن تبدأ

استخدم مجلد عمل جديدًا وFlashData CLI بصلاحية google_search ورصيد متاح. أعد استخدام ملف شخصي موثَّق أو FLASHDATA_API_KEY. تستخدم فحوص Bash الأداة jq؛ ويستخدم Windows برنامج PowerShell 7. تستخدم سكربتات الأرشيف المحلي Python 3.10+ ومكتبتها القياسية.

تابعي data.accessVerified هو true. وبالنسبة لوحدات CLI، حافظ على نفس النبذة، ومستعمل OS ودليل الدولة. على العميل أن يحمّل إبداعه الحالي من متجره السري.

### تحقق من وصولك المنقذ

```bash
flashdata auth status --json
```

- [Install the CLI](https://flashdata.dev/ar/docs/guides/flashdata-cli/reference.md#install)
- [Create an API key](https://flashdata.dev/app/api-keys)
- [استخدام HTTP بدلا من ذلك](https://flashdata.dev/ar/docs/guides/save-results/reference.md#http)

<a id="save"></a>

## 1. احتفظ بالمدخلات ووفر استجابة واحدة

انقذوا request.json أسفل، ثمّ يَدْخلُ قيادة واحدة. --input ويستخدم هذا الطلب الدقيق؛ ويبقي الملف دون تغيير بعد ذلك. --output ينقذ API في الجسد search.json; --json البصمات CLI البيانات الوصفية، البحث المنقذ هذه المهمة على الصعيد المحلي ID.

### request.json

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

### Bash

#### أجري بحثاً واحداً

```bash
flashdata query --input request.json \
  --run-id saved-search --output search.json --json
```


### PowerShell

#### أجري بحثاً واحداً

```powershell
flashdata query --input request.json `
  --run-id saved-search --output search.json --json
```



<a id="inspect"></a>

## 2. تقييم الاستجابة الموفرة

المصدر المتوقع: google_search, status: done and a results array. طباعة كلّ نتيجة عضوية لقب، وربط وقنبلة. وتتباين النتائج الفعلية؛ وتختلف مجموعة ناجحة فارغة عن طلب فاشل أو عن ميدان مفقود.

### Bash / jq

#### Validate and read search.json

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


### PowerShell

#### Validate and read search.json

```powershell
$result = Get-Content -Raw -LiteralPath search.json | ConvertFrom-Json
if ($result.source -ne 'google_search' -or $result.status -ne 'done' -or
    -not ($result.results -is [array])) {
  throw 'Inspect search.json before treating the task as complete.'
}
foreach ($page in $result.results) {
  if (-not ($page.organic -is [array])) { throw 'Missing organic results array.' }
  $page.organic | Select-Object title, link, snippet
}
```



<a id="record"></a>

## 3. حفظ المدخلات والاستجابة والاستشهاد

انقذوا archive.py أسفل، ثم تشغيله مع تشغيل ID خطوة 1. ويحفظ الملفات الخام، ويستخرج وصلات المصدر ويكتب manifest.json آخر مرة مع فحوصات وإستخدام الملفات. (ج) توقع (زكس كيزوك (complete: true؛ ويتوقف حساب الاستشهاد على نتائج البحث. ولا تقدم طلبات للشبكة.


<a id="archive-script"></a>

### Save archive.py

Create archive.py beside request.json and search.json in your working folder. عُلِمْ الرمز الكامل أسفل إليه ويُوفّرُه.

وينتج عن ذلك على سبيل المثال محفوظات Google Search. وتُبقي أدلة المحفوظات القائمة سليمة. استمر request.json, search.json و المباراة تجري معاً حتى يكتمل حفظها

#### archive.py

```python
# archive.py — Python 3.10+, standard library only; no network requests.
import argparse
import hashlib
import json
import re
from datetime import datetime, timezone
from pathlib import Path
from urllib.parse import urlsplit

parser = argparse.ArgumentParser()
parser.add_argument('--run-id', required=True)
args = parser.parse_args()
if not re.fullmatch(r'[A-Za-z0-9_-]+', args.run_id):
    raise ValueError('Use the CLI run ID from this task.')
request_bytes = Path('request.json').read_bytes()
result_bytes = Path('search.json').read_bytes()
request = json.loads(request_bytes.decode('utf-8-sig'))
result = json.loads(result_bytes.decode('utf-8-sig'))
if (request.get('source') != 'google_search' or result.get('source') != request['source']
        or result.get('status') not in ['done', 'completed']
        or not isinstance(result.get('results'), list)):
    raise ValueError('Inspect the request and result before archiving.')
citations = []
for page in result['results']:
    if not isinstance(page, dict) or not isinstance(page.get('organic'), list):
        raise ValueError('Expected an organic results array, including when it is empty.')
    for item in page['organic']:
        if not isinstance(item, dict) or not isinstance(item.get('link'), str):
            raise ValueError('A result is missing its source URL.')
        url = urlsplit(item['link'])
        if url.scheme not in ['http', 'https'] or not url.netloc:
            raise ValueError('Inspect an unexpected source URL.')
        citations.append({key: item.get(key, '') for key in ['title', 'link', 'snippet']})
files = {'request.json': request_bytes, 'response.json': result_bytes,
         'citations.ndjson': ''.join(json.dumps(row, ensure_ascii=False) + '\n'
                                    for row in citations).encode('utf-8')}
manifest = {'version': 1, 'run_id': args.run_id, 'source': request['source'],
            'archived_at': datetime.now(timezone.utc).isoformat(),
            'usage': result.get('usage'), 'citation_count': len(citations),
            'files': {name: {'bytes': len(data), 'sha256': hashlib.sha256(data).hexdigest()}
                      for name, data in files.items()}}
folder = Path('archive') / args.run_id
folder.mkdir(parents=True)  # Existing archives are preserved. Choose a new run ID for new work.
for name, data in files.items():
    with (folder / name).open('xb') as output:
        output.write(data)
# Write the manifest last. Without it, the archive is incomplete.
with (folder / 'manifest.json').open('x', encoding='utf-8') as output:
    json.dump(manifest, output, ensure_ascii=False, indent=2)
print(json.dumps({'archive': str(folder), 'citations': len(citations), 'complete': True}))
```


<a id="run-archive"></a>

### إنشاء المحفوظات

اهرب من الملف الذي يحتوي على archive.py و request.json و search.json.

#### Bash

##### بناء محفوظات جديدة

```bash
python3 archive.py --run-id saved-search
```


#### PowerShell 7

##### بناء محفوظات جديدة

```powershell
python archive.py --run-id saved-search
```



<a id="reuse"></a>

## 4. إعادة استخدام المحفوظات بدون وثائق تفويض

انقذوا reuse.py أسفل. عُلم archive/saved-search مطوّر إلى العملية التي تحتاجها، ثمّ يُدير هذا القارئ. وهي تحقق من كل ملف قبل طبع الاستفسارات والاستعمالات والاستشهادات الأصلية. يعمل بعد ذلك API-الإستفزاز أو الإنفجار الإستضافي لأنه لا يقرأ سوى نسختك المحفوظة


<a id="reuse-script"></a>

### Save reuse.py

أنشئ reuse.py في مجلد العمل الذي يحتوي archive/. على جهاز آخر، انسخ reuse.py ودليل archive/saved-search كاملًا مع الحفاظ على هذا الترتيب.

#### reuse.py

```python
# reuse.py — run without a FlashData key or CLI.
import hashlib
import json
import sys
from pathlib import Path

folder = Path(sys.argv[1])
manifest = json.loads((folder / 'manifest.json').read_text(encoding='utf-8'))
expected = {'request.json', 'response.json', 'citations.ndjson'}
if manifest.get('version') != 1 or set(manifest.get('files', {})) != expected:
    raise ValueError('Unknown or incomplete archive manifest.')
files = {}
for name in sorted(expected):
    data = (folder / name).read_bytes()
    record = manifest['files'][name]
    if len(data) != record['bytes'] or hashlib.sha256(data).hexdigest() != record['sha256']:
        raise ValueError('Archive changed or was not fully copied: ' + name)
    files[name] = data
request = json.loads(files['request.json'].decode('utf-8-sig'))
citations = [json.loads(line) for line in files['citations.ndjson'].decode('utf-8').splitlines()]
if len(citations) != manifest['citation_count']:
    raise ValueError('Citation count does not match the manifest.')
print(json.dumps({'run_id': manifest['run_id'], 'query': request['query'],
                  'archived_at': manifest['archived_at'], 'usage': manifest['usage'],
                  'citations': citations}, indent=2))
```


<a id="read-archive"></a>

### اقرأ المحفوظات المنقذة

انقذوا reuse.pyثم اهرب من ملفه الحجة الأخيرة هي الطريق إلى المحفوظات المنسخة.

#### Bash

##### إقرأْ الأرشيفَ المُضَوَّلَ

```bash
python3 reuse.py archive/saved-search
```


#### PowerShell 7

##### إقرأْ الأرشيفَ المُضَوَّلَ

```powershell
python reuse.py archive/saved-search
```



<a id="cli-cache"></a>

### Export from the CLI journal instead

إذا كنت لا تزال لديك الأصلي CLI ملف ودليل الدولة، تصدير الركض المنقذ إلى اسم ملف جديد. هذا لا يجعل أي استفسار جديد، لكنه يتحقق من الوصول المباشر أولا. ويمكن قراءة ملف أو محفوظات النتائج القائمة محلياً بدون ذلك الشيك.

#### التصدير على المدى المكتمل

```bash
flashdata runs show saved-search --result --output search-copy.json --json
```


<a id="freshness"></a>

## يقرر متى يعاد استخدامه أو يعاد تنشيطه

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

| المهام | الإجراء |
| --- | --- |
| إعادة تشغيل صالون، أو تجديد تقرير أو مواصلة خطوة وكيل | إعادة استخدام الاستجابة الموفرة. حافظ على المصدر URLs، بارامترات الاستفسارات والإستخدام بها. |
| تقديم إحاطة يومية جديدة أو الرد على استفسار متغير | أنشئ معرّف مهمة/تشغيل ومجلد عمل وأرشيفًا جديدًا. احتفظ باللقطات القديمة كسجل تاريخي. |
| استخدام الكون عبر الملفات المشتقة | أعد السؤال الأصلي ذات مرة ولا يوجّه تأليف آخر لرد أو تقديم تقرير آخر. |

- [المهام المتكررة وإدارة IDs](https://flashdata.dev/ar/docs/guides/recurring-tasks/reference.md)
- [النتائج الحالية](https://flashdata.dev/ar/docs/guides/response-formats/reference.md#completed-results)

<a id="retention"></a>

## تعرف ما الذي ينتهي

| النتيجة | ماذا يَستمرُّ | الاستبقاء |
| --- | --- | --- |
| Realtime query | ملف الردود والمدخلات الأصلية | نسختك المحفوظة تتبع سياسة التخزين |
| Async / Batch | Job ID, submission receipt and result JSON | 24 بعد ساعات من الانتهاء |
| Bulk | Manifest and all NDJSON parts | بعد 24 ساعة من اكتمال المهمة بالكامل؛ تحقق من expiresAt |
| YouTube Download | التوصيل JSON ووسائط الإعلام في وجهتك | Delivery JSON: job retain. وسائط الإعلام: الدلو دورة الحياة |
| MCP chunk cache | النتيجة المجمعة بالكامل | دقائق 10؛ ولا يحتفظ إلا بأربعة أكبر النتائج لكل مفتاح API. |


<a id="sidecar"></a>

## احتفظ بسيارة جانبية صغيرة بدلاً من ذلك

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

### Bash / jq · search-record.json

```bash
(
set -euC
jq --arg run_id 'saved-search' --slurpfile request request.json \
  '{run_id: $run_id, source, input: $request[0],
    saved_at: (now | todateiso8601), result_file: "search.json", usage}' \
  search.json > search-record.json
cat search-record.json
)
```


<a id="http"></a>

## وفّر مباشرة مع HTTP

استخدم هذا بدل استعلام CLI في الخطوة 1. احفظ request.json نفسه أولًا؛ ويشغّل هذا استعلامًا جديدًا واحدًا باستخدام Bash وcURL 7.76+ وjq. أعد استخدام FLASHDATA_API_KEY واختر مجلدًا لا يحتوي search.json. بعد التحقق، تعمل سكربتات الأرشيف نفسها بهذه النتيجة؛ واختر معرّف مهمة خاصًا بك لـ --run-id.

يعني رمز خروج cURL غير الصفري أن النتيجة غير جاهزة للاستخدام. افحص الاستجابة المحفوظة قبل إعادة المحاولة؛ فقد تنتهي مهلة الاتصال بعد قبول الاستعلام. استخدم أمر التحقق في الخطوة 2.

### جهز مفتاحك إذا لزم الأمر

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

### Save the API response

```bash
(
set -euC
: "${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY first}"
test -f request.json
curl --fail-with-body --silent --show-error --max-time 120 \
  --request POST 'https://data.flashdata.dev/v1/queries/realtime' \
  --header "X-API-Key: $FLASHDATA_API_KEY" \
  --header 'Content-Type: application/json' --header 'Accept: application/json' \
  --data-binary @request.json > search.json
jq . search.json
)
```


<a id="jobs"></a>

## توفير وظيفة خلفية قائمة

الاستخدام submission.json من دليل الأسينك ونفس الحساب وتسترجع هذه الأوامر العمل القائم؛ ولا تقدم أي استفسار آخر. وتنتظر شركة CLI إنجازها وتعالج إعادة توجيه النتائج. وفّر النتيجة في غضون ساعات الإنجاز المحددة برقم 24.

### CLI + jq

#### انتظر، استرجع ووفر

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


### HTTP / cURL

ويتوقف التحقق من الوضع إذا لم يكتمل العمل. وإذا كان لا يزال يُستَحل أو يُدير، فانتظر وتُدير هذا اللقاح القراء فقط مرة أخرى؛ وتفتيش على وظيفة فاشلة بدلاً من ذلك. ألف 302 يتم تحميلها بدون إرسالك API المفتاح ويتم التحقق من الاستجابة المؤقتة قبل إنشاء job-result.json.

#### Bash · cURL + jq

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


- [Resume an existing async job](https://flashdata.dev/ar/docs/guides/async-batch/reference.md#resume)
- [عقد الرد على النتائج](https://flashdata.dev/ar/docs/reference/realtime-and-async/reference.md#results)
- [Retrieve as Markdown](https://flashdata.dev/ar/docs/guides/response-formats/reference.md#completed-results)

<a id="bulk"></a>

## انقذوا كل صواريخ Bulk

يستعاض عن BULK_ID ب ID in your submission receipt. وبعد إتمام العمل، تتبع شركة CLI البيان وتحتفظ بكل جزء من ملف شركة NDJSON. احتفظ بالبيان أيضاً عندما تحتاج للإحصاء وجزء من البيانات الوصفية

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

### تحصيل العمل المنجز

```bash
flashdata bulk results BULK_ID --output bulk-results.ndjson --timeout 30m --json
```

- [تحقق من كل مدخلات قبل الاستيراد](https://flashdata.dev/ar/docs/guides/bulk/reference.md#audit)
- [Manifest, counts and NDJSON](https://flashdata.dev/ar/docs/reference/bulk-processing/reference.md#downloadBulkJobManifest)

<a id="media"></a>

## حفظ سجل التسليم ووسائط الإعلام

delivery.json يحتوي على سجل تسليم، وليس الفيديو أو اللوحات الصوتية. وفّر مقاسه من طراز URL وحجمه وفحصه إلى جانب المهمة. وسائل الإعلام تعيش في مخزن مقصدك وتتبع دورة حياة ذلك المخزن

من أجل مقصد خاص، استخدم وثائق تفويض المزود أو موقعة URL لتفتيش الجسم. نتيجة مؤقتة مفقودة JSON لا يعني أن وسائل الإعلام المخزنة قد حذفت

### Inspect a save download result ; jq

```bash
jq '.results[] | {file_url, file_size, md5, downloaded_bytes, output_format}' delivery.json
```

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

<a id="mcp"></a>

## المجموع MCP الاغبياء قبل انقاذ

وعندما تعود أداة من طراز result_id، تشاك، و next_offset، تقرأ الأجزاء المتبقية مع get_result باستخدام نفس مفتاح API. (ب) استخدام الـ (زكس كيزوك (next_offset) التي أعيدت بواسطة الأداة؛ والقيم الواردة أدناه هي أصحاب الأماكن.

1. أقدّم كلّ قطيع في الترتيب. أتبع next_offset حتى يكون null.
2. حرر النص المنضم مرة واحدة JSONثم أكتب النتيجة الكاملة لملفك أو تخزينك
3. أنقذ قبل أن expires_at. ويمكن أن تؤدي الاستجابات الكبيرة الجديدة إلى إجلاء النتائج الأكبر قبل الحد الأقصى للدقيقة المحددة في 10؛ ويحتفظ المخبأ بأربعة لكل مفتاح من مفاتيح API.

### MCP tools/call

```json
{
  "name": "get_result",
  "arguments": {
    "result_id": "RESULT_ID_FROM_TOOL",
    "offset": 16000
  }
}
```

- [موكّل من طراز MCP يملك مجموعة من الشيكات](https://flashdata.dev/ar/docs/guides/mcp-custom-client/reference.md)

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

## مشاكل الادخار والاسترجاع

| المشكلة | Fix |
| --- | --- |
| ملف النواتج موجود بالفعل | افحصه أولاً (ج) استخدام CLI، في تشغيل مكتمل، runs show مع اسم ملف جديد للنواتج بدلاً من تقديم استفسار آخر. |
| CLI لا يمكن العثور على تشغيل | إستعملْ الأصلَ OS مستعمل، ملف ودليل الولاية. إذا احتفظت بعمل عن بعد IDاسترجعي تلك الوظيفة مباشرة |
| 401 / 403 on reuse | تشغيل الوميضات auth status --json واستعادة إمكانية الوصول الصحيحة. A local file already save can still be read without API access. |
| 409 / 410 | 409: إنتظار الوظيفة القائمة. 410: استخدام نسختك الموفدة؛ وقد انتهت النتيجة المؤقتة. |
| خطأ في النطق بعد الاستفسار | استمروا بالركض ID أو وظيفة ID. تخزين واسترجاع الأعمال القائمة قبل النظر في طلب جديد. |
| ليس للمحفوظات أي بيان أو إخفاقات في نظام الشيكات | أعد أو نسخ الملفات الأصلية مرة أخرى. الاحتفاظ بمحفوظات غير مكتملة للتفتيش؛ وإعادة بناء المحفوظات لا تتطلب استفسارا جديدا. |
| MCP · result_unavailable | (ج) النتيجة التي تحققت من (زكس كيزوك (ID) وقابلها مفتاح (API) و (إنتهاء) استخدام نسخة منقذة إذا انتهت فترة صلاحية المخبأ؛ لا تتردد بتكرار استفسار مدفوع الأجر. |

- [أوامر الاسترداد من شركة CLI](https://flashdata.dev/ar/docs/guides/cli-automation/reference.md#recover)
- [طلب التشويش](https://flashdata.dev/ar/docs/guides/troubleshooting/reference.md)
