تصفح الوثائق
مرجع API
الحصول على نتائج في الاستجابة، أو تقديم وظيفة واسترجاعها في وقت لاحق. اختر كيف أن طلبك أو وكيلك ينتظر العمل
في هذه الصفحة
اختر طريقة الطلب
وتدعم شركة 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.
python3 -m pip install requestsRealtime: الحصول على النتيجة الآن
POST /v1/queries/realtime returns status: done and a results array. اقرأ result.json؛ ولا يلزم إجراء أي اقتراع.
انقذوا 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))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.jsonAsync: Provide a job receipt
يعيد POST /v1/queries إيصال مهمة معلّقة وليس نتائج البحث. احفظ submission.json وتابع بطلبات الحالة والنتائج أدناه.
انقذوا 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"
}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{
"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.
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_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استرجاع النتيجة المنجزة
تشغيل هذا بعد ذلك job.status أُنجزت. أما الرد على النتائج الافتراضية فهو 302: ويشير الموقع إلى مخزن موقع URL. ويحتفظ الطلبان الواردان أدناه بمفتاح API الخاص بك على FlashData، ويحتفظان بالرقم الأصلي JSON إلى result.json. For YouTube Downloadهذا JSON يصف وسائل الإعلام التي تم تسليمها إلى مخزنك، وليس الفيديو أو الملف الصوتي.
انقذوا 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))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حالات التأخير والفشل
| الحالة | الإجراء المطلوب |
|---|---|
| وقت تقديم الطلب | قد يكون 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. إستخدم نسختك المنقذة |