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

مرجع API

Realtime and async

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

في هذه الصفحة

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

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

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

أرسل طلبًا

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

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

Python · install once
python3 -m pip install requests

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

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

انقذوا realtime.py و اديروا "بيثون" realtime.py.

realtime.py
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))

Async: Provide a job receipt

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

انقذوا submit_async.py و اديروا "بيثون" submit_async.py.

submit_async.py
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))
الحقول الاستلامية - مثال مختصر
{
  "id": "job_EXAMPLE",
  "source": "google_search",
  "status": "pending"
}

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

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

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

انقذوا job_status.py و اديروا "بيثون" job_status.py.

job_status.py
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"))

استرجاع النتيجة المنجزة

تشغيل هذا بعد ذلك job.status أُنجزت. أما الرد على النتائج الافتراضية فهو 302: ويشير الموقع إلى مخزن موقع URL. ويحتفظ الطلبان الواردان أدناه بمفتاح API الخاص بك على FlashData، ويحتفظان بالرقم الأصلي JSON إلى result.json. For YouTube Downloadهذا JSON يصف وسائل الإعلام التي تم تسليمها إلى مخزنك، وليس الفيديو أو الملف الصوتي.

انقذوا job_result.py و اديروا "بيثون" job_result.py.

job_result.py
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))

حالات التأخير والفشل

الحالةالإجراء المطلوب
وقت تقديم الطلبقد يكون 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. إستخدم نسختك المنقذة