تخطَّ إلى المحتوى
AR
الحصول على مفتاح API
تصفح الوثائق

الأدلة

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

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

في هذه الصفحة

Query once, use the result across tasks

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

ما ستحتفظ به
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

قبل أن تبدأ

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

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

تحقق من وصولك المنقذ
flashdata auth status --json

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

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

request.json
{
  "source": "google_search",
  "query": "battery recycling research",
  "params": {
    "num": 5
  }
}
أجري بحثاً واحداً
flashdata query --input request.json \
  --run-id saved-search --output search.json --json

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

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

Validate and read search.json
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

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

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

Save archive.py

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

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

archive.py
# 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}))

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

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

بناء محفوظات جديدة
python3 archive.py --run-id saved-search

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

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

Save reuse.py

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

reuse.py
# 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))

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

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

إقرأْ الأرشيفَ المُضَوَّلَ
python3 reuse.py archive/saved-search

Export from the CLI journal instead

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

التصدير على المدى المكتمل
flashdata runs show saved-search --result --output search-copy.json --json

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

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

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

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

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

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

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

Bash / jq · search-record.json
(
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
)

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

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

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

جهز مفتاحك إذا لزم الأمر
# 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
(
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
)

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

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

انتظر، استرجع ووفر
(
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
)

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

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

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

تحصيل العمل المنجز
flashdata bulk results BULK_ID --output bulk-results.ndjson --timeout 30m --json

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

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

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

Inspect a save download result ; jq
jq '.results[] | {file_url, file_size, md5, downloaded_bytes, output_format}' delivery.json

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

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

  1. أقدّم كلّ قطيع في الترتيب. أتبع next_offset حتى يكون null.
  2. حرر النص المنضم مرة واحدة JSONثم أكتب النتيجة الكاملة لملفك أو تخزينك
  3. أنقذ قبل أن expires_at. ويمكن أن تؤدي الاستجابات الكبيرة الجديدة إلى إجلاء النتائج الأكبر قبل الحد الأقصى للدقيقة المحددة في 10؛ ويحتفظ المخبأ بأربعة لكل مفتاح من مفاتيح API.
MCP tools/call
{
  "name": "get_result",
  "arguments": {
    "result_id": "RESULT_ID_FROM_TOOL",
    "offset": 16000
  }
}

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

المشكلة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 / 410409: إنتظار الوظيفة القائمة. 410: استخدام نسختك الموفدة؛ وقد انتهت النتيجة المؤقتة.
خطأ في النطق بعد الاستفساراستمروا بالركض ID أو وظيفة ID. تخزين واسترجاع الأعمال القائمة قبل النظر في طلب جديد.
ليس للمحفوظات أي بيان أو إخفاقات في نظام الشيكاتأعد أو نسخ الملفات الأصلية مرة أخرى. الاحتفاظ بمحفوظات غير مكتملة للتفتيش؛ وإعادة بناء المحفوظات لا تتطلب استفسارا جديدا.
MCP · result_unavailable(ج) النتيجة التي تحققت من (زكس كيزوك (ID) وقابلها مفتاح (API) و (إنتهاء) استخدام نسخة منقذة إذا انتهت فترة صلاحية المخبأ؛ لا تتردد بتكرار استفسار مدفوع الأجر.