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

الأدلة

Async طلبات دفعة

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

في هذه الصفحة

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

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

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

قبل أن تبدأ

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

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

حرية الدخول والفحص الحسابي
flashdata auth status --json
flashdata account balance --json
flashdata account limits --json

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

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

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

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

Bash · FlashData CLI
flashdata search "battery recycling research" --num 5 \
  --mode async --run-id async-first --output submission.json --json

2. انتظروا العمل الحالي

تابعي عندما تكتمل المهمة إذا فشلت، فتّش خطأه قبل تقديم أيّ شيء آخر.

A successful wait returns data.status: completed in CLI JSON.

Bash · FlashData CLI
(
set -euC
JOB_ID=$(jq -er '.remoteId // .id // .submission.id' submission.json)
flashdata jobs wait "$JOB_ID" --timeout 2m --json
)

3. استرجاع وإنقاذ الرد

انقذوا result.json محلياً الشغل المكتمل و جسده المُنتج هو سجل منفصل جسد هذا البحث يحتوي على المصدر: google_search, a صفيفة نتائج وإستعمال. المصادقة الواردة أدناه تقبل النتيجة المخزنة تم أو أكملت حالة النجاح.

Bash · FlashData CLI
(
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
)

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

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

مهمة التطبيقالمرحلة الانتقالية
الانتظارامتنع عن العمل المقبول ID قبل إعادة السيطرة إلى المستعمل أو الوكيل.
جاهز(مارك) جاهز بعد أن يتم إنقاذه والتحقق منه. إستخدم مهمتك ID كما import/upsert المفتاح
الحاجة إلى الاهتمامحافظ على العمل ID والخطأ ولا يُطلب تقديم وقت الاقتراع أو الفشل في الاسترجاع مرة أخرى.
اقرأ الرد المحلي؛ لا توجد مكالمات من طراز API
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

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

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

CLI + jq · recover the save job
(
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
)

Submit several queries

وتقدم شركة Batch وظائف مستقلة في طلب واحد. ويحتاج هذا المثال الثنائي المستوى إلى قدرة على ما لا يقل عن سؤالين ووظيفتين معلقتين؛ وتقتصر التجربة المؤقتة على وظيفة واحدة. احفظوا الصفوف الواردة أدناه batch.json في ملف عمل منفصل

batch.json
[
  {
    "source": "google_search",
    "query": "battery recycling research",
    "params": {
      "num": 5
    }
  },
  {
    "source": "google_search",
    "query": "lithium battery recycling methods",
    "params": {
      "num": 5
    }
  }
]
Bash · FlashData CLI
flashdata batch submit --input batch.json \
  --run-id batch-first --output batch-submission.json --json

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

تتبع كل وظيفة مقبولة

وبعد إنقاذ شركة collect-batch.py، تشغيلها من ملف عمل شركة Batch مع شركة Python 3.10+، وشركة CLI الموثقة. وهو يعمل مع أي من أسلوبي التقديم أعلاه. ويقرأ كل إيصال، وينتظر دقيقتين لكل وظيفة غير مكتملة، ويوفّر كل رد ناجح. تشغيل جامع واحد في وقت واحد؛ وإعادة تشغيله لمواصلة نفس الوظائف.

توقّع مدخلين في batch-results/outcomes.json لهذا المثال. استورد المدخلات المكتملة حسب فهرس الإدخال ومعرّف المهمة. تظل مدخلات failed وpending وread_error ظاهرة؛ ويعني رمز الخروج 2 ضرورة مراجعتها أو استئنافها. لا يرسل المجمّع استعلامات جديدة.

Bash
python3 collect-batch.py
PowerShell 7
python collect-batch.py
قراءة كل نتيجة؛ jq
jq '.[] | {index, job_id, status, result_file, error}' batch-results/outcomes.json

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

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

  1. أفسد الحدث وأرجع 2x على الفور Deduplicate delivery_id (also sent as X-Delivery-Id).
  2. هذا الحدث غير موقع. اجمعي مظهره و مصدره إلى إيصالك المنقذ، ثم توثّق على حالة قراءة باستخدام وصلة الاستلام الأصلية. لا تثق URLs مزودة بحدث غير مؤكد.
  3. عند الانتهاء، جلب وإنقاذ النتيجة. في حالة فشل، تفحص خطأ العمل. أبقوا الاقتراع كتراجع إذا لم يصل أي حدث
طلب جثة مع ردة فعل
{
  "source": "google_search",
  "query": "battery recycling research",
  "params": {
    "num": 5
  },
  "callback_url": "https://your-app.example/webhooks/flashdata"
}
الجسم الحدثي
{
  "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"
    }
  ]
}

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

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

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

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

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

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

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

جميع الأربعة يستخدمون 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

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

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

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

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

بارامترات المصدر

إنشاء طلب

معلمات متقدمة

تبدأ في 1. كل صفحة هي طلب منفصل

Google filter, such as qdr:d for the past day.

موقع الإنجاز على الإنترنتحمولة المواقع الشبكية والتحقق منها ومخازنها

وتطبق شركة Markdown على النتائج المنجزة. وتحتفظ المقبوضات وحالة العمل بميادينها الأصلية.

POSThttps://data.flashdata.dev/v1/queries
import gzip
import json
import random
import time
import urllib.error
import urllib.request

api_key = "YOUR_API_KEY"
payload = {
    "source": "google_search",
    "query": "openai",
    "params": {
        "gl": "us",
        "hl": "en",
        "num": 10,
        "page": 1,
    },
}

def api_get(url):
    request = urllib.request.Request(url, headers={"X-API-Key": api_key})
    with urllib.request.urlopen(request, timeout=60) as response:
        return json.load(response), response.headers

class NoRedirect(urllib.request.HTTPRedirectHandler):
    def redirect_request(self, request, file_pointer, code, message, headers, new_url):
        return None

def read_result(url):
    request = urllib.request.Request(url, headers={"X-API-Key": api_key})
    try:
        with urllib.request.build_opener(NoRedirect).open(request, timeout=60):
            raise RuntimeError("Expected a result redirect")
    except urllib.error.HTTPError as response:
        if response.code != 302 or not response.headers.get("Location"):
            raise
        storage_url = response.headers["Location"]
        response.close()
    # Never forward the API key to storage.
    with urllib.request.urlopen(urllib.request.Request(storage_url, headers={"Accept-Encoding": "gzip"}), timeout=60) as response:
        content = response.read()
        if response.headers.get("Content-Encoding") == "gzip":
            content = gzip.decompress(content)
        return json.loads(content)

def link(job, relation):
    return next(item["href"] for item in job["links"] if item["rel"] == relation)

request = urllib.request.Request(
    "https://data.flashdata.dev/v1/queries",
    data=json.dumps(payload, ensure_ascii=False).encode("utf-8"),
    headers={"Content-Type": "application/json", "X-API-Key": api_key},
    method="POST",
)
with urllib.request.urlopen(request, timeout=120) as response:
    submission = json.load(response)
jobs = submission.get("queries", [submission])
for submitted in jobs:
    print("Job:", submitted["id"])
    deadline = time.monotonic() + 300
    while time.monotonic() < deadline:
        status, headers = api_get(link(submitted, "self"))
        job = status.get("job", status)
        if job["status"] == "completed":
            result = job.get("result") if submitted["source"] == "youtube_download" and job.get("result") is not None else read_result(link(submitted, "results"))
            print(json.dumps(result, ensure_ascii=False, indent=2))
            break
        if job["status"] == "failed":
            raise RuntimeError(f"{submitted['id']}: {job.get('error', 'Job failed')}")
        hint = headers.get("Retry-After", "1")
        delay = max(1, min(5, int(hint))) if hint.isdigit() else 5
        time.sleep(min(delay * random.uniform(1, 1.2), max(0, deadline - time.monotonic())))
    else:
        raise TimeoutError(f"Still running; save this job ID: {submitted['id']}")
إيصال العمل، ثم استطلاع النتائجX-API-Key authentication