सीधे सामग्री पर जाएँ
HI
API कुंजी प्राप्त करें
दस्तावेज़ देखें

गाइड

Async & बैच अनुरोध

किसी एप्लिकेशन या एजेंट के लिए पृष्ठभूमि का काम चलाएं, अपनी सहेजी गई नौकरी ID से फिर से शुरू करें और हर बैच के परिणाम को इकट्ठा करें।

इस पेज पर

अपनी प्रक्रिया बंद होने के बाद काम जारी रखें

एक queued आवेदन कार्य या एजेंट वर्कफ़्लो के लिए पृष्ठभूमि नौकरी का उपयोग करें जो बाद में finish कर सकते हैं। यह walkthrough एक Google खोज चलाता है, अपनी रसीद बचाता है और उस रसीद से दूसरी प्रक्रिया में फिर से शुरू होता है।

रखनाउद्देश्य
जॉब की रसीदsubmission.json - अपने आवेदन कार्य और मूल इनपुट के साथ स्वीकृत नौकरी ID रखें।
सहेजा गया जवाबresult.json — अपने स्रोत और परिणाम को आयात करने से पहले मान्य है।
Batch परिणामbatch-results/outcomes.json — एक प्रविष्टि प्रति इनपुट, अपनी नौकरी ID और परिणाम फ़ाइल के साथ।

शुरू करने से पहले

google_search पहुँच और उपलब्ध क्रेडिट के साथ एक API कुंजी का उपयोग करें। जमा करने, प्रतीक्षा करने और पुनर्प्राप्त करने के लिए CLI या HTTP चुनें। Bash उदाहरण jq का उपयोग करते हैं; HTTP को cURL 7.76+ की भी आवश्यकता है। एक नए काम करने वाले फ़ोल्डर में भाग लें।

अपने प्रमाणित CLI प्रोफाइल या FLASHDATA_API_KEY का पुन: उपयोग करें। की पुष्टि करें data.accessVerified true है। एक नामित प्रोफ़ाइल के लिए FLASHDATA_PROFILE सेट करें ताकि बाद में स्क्रिप्ट भी इसका उपयोग कर सकें। यदि कोई कुंजी कॉन्फ़िगर नहीं की जाती है, तो पहले CLI प्रमाणीकरण गाइड का उपयोग करें।

नि: शुल्क पहुँच और खाता चेक
flashdata auth status --json
flashdata account balance --json
flashdata account limits --json

एक पृष्ठभूमि खोज रन

यह walkthrough एक Google Search प्रस्तुत करता है। स्टेटस चेक और परिणाम पुनर्प्राप्ति अन्य क्वेरी प्रस्तुत नहीं करते हैं। इसी तरह के क्रेडेंशियल को पूरी तरह से पुन: उपयोग करें।

1. एक बार जमा करें और रसीद रखें

submission.json फ़ाइल आपकी रसीद है। HTTP एक आईडी, स्रोत, स्थिति और self/results लिंक लौटाता है; CLI जमा करने के तहत रसीद बचाता है और यह भी वापस लौटा देता है remoteId. HTTP 200 का मतलब स्वीकार किया जाता है, समाप्त नहीं होता है।

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

2. मौजूदा नौकरी के लिए प्रतीक्षा करें

जब काम पूरा हो जाता है तो जारी रखें। अगर यह विफल रहा है, तो किसी अन्य चीज़ को जमा करने से पहले अपनी त्रुटि का निरीक्षण करें।

CLI JSON में एक सफल प्रतीक्षा रिटर्न data.status: completed

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, एक परिणाम सरणी और उपयोग शामिल हैं। नीचे सत्यापन संग्रहीत परिणाम के लिए किया गया है या सफलता की स्थिति को पूरा करने के लिए स्वीकार करता है।

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

किसी अन्य प्रक्रिया में फिर से शुरू

उसी फ़ोल्डर में एक नया टर्मिनल खोलें, उसी credential/profile. के साथ इन कमांडों ने submission.json में नौकरी को पढ़ा और एक नया फाइल नाम बचा लिया। वे कभी काम नहीं करते। उसी CLI रन ID का पुन: उपयोग करने के लिए इसकी मूल राज्य निर्देशिका की आवश्यकता होती है; HTTP खुद उस स्थानीय रन ID का उपयोग करके POSTs को अलग नहीं करता है।

CLI + jq · बचाया नौकरी पुनर्प्राप्त करें
(
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
)

कई प्रश्नों को जमा करें

Batch एक अनुरोध में स्वतंत्र नौकरियों को जमा करता है। इस दो-query उदाहरण के लिए कम से कम दो प्रश्नों और दो लंबित नौकरियों के लिए क्षमता की जरूरत है; एक अस्थायी परीक्षण एक तक सीमित है। एक अलग काम करने वाले फ़ोल्डर में 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

बचाओ collect-batch.py

Batch कार्य फ़ोल्डर में batch.json और batch-submission.json के बगल में collect-batch.py बनाया गया है। नीचे दिए गए कोड को कॉपी करें और इसे सहेजें।

batch.json, batch-submission.json और बैच-results/ एक साथ रखें। यदि सहेजे गए इनपुट या रसीद बदल जाती है तो स्क्रिप्ट बंद हो जाती है। यह स्थानीय फ़ाइलों को पूरा करने और पढ़ने की त्रुटि के बाद कभी प्रतिस्थापन प्रश्नों को जमा नहीं करता है।

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 में दो प्रविष्टियों का अन्वेषण करें। इनपुट इंडेक्स और जॉब ID द्वारा पूर्ण प्रविष्टियों को आयात करें। विफल, लंबित और 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

पूरा होने वाला वेबहुक प्राप्त करें

एक अनुरोध या प्रत्येक Batch प्रविष्टि में स्रोत, क्वेरी और पैराम के बगल में callback_url जोड़ें। उदाहरण बदलें URL अपने रिसीवर के साथ। घटनाओं की रिपोर्ट पूरा होने या विफलता; परिणाम को अलग से पुनर्प्राप्त करें।

  1. इस घटना पर जोर देते हैं और तुरंत 2xx वापस लौटते हैं। Deduplicate delivery_id (जिसे X-Delivery-Id भी कहा जाता है)।
  2. यह घटना असाइन नहीं की गई है। अपनी आईडी और स्रोत को अपनी सहेजी हुई रसीद से मिलान करें, फिर मूल रसीद के स्वयं लिंक का उपयोग करके एक स्टेटस को पढ़ाएं। एक एकीकृत घटना द्वारा आपूर्ति की गई URLs पर भरोसा न करें।
  3. पूरा होने पर, परिणाम प्राप्त करने और सहेजने के लिए। असफल होने पर नौकरी की त्रुटि का निरीक्षण करें। यदि कोई घटना नहीं आती है तो मतदान को एक गिरावट के रूप में रखें।
एक कॉलबैक के साथ शरीर का अनुरोध करें
{
  "source": "google_search",
  "query": "battery recycling research",
  "params": {
    "num": 5
  },
  "callback_url": "https://your-app.example/webhooks/flashdata"
}
घटना शरीर · illustrative
{
  "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 URL का उपयोग पोर्ट 443 पर, अधिकांश 2,048 वर्णों पर, बिना क्रेडेंशियल या एक खंड पर करें। हर संकल्पित IP सार्वजनिक होना चाहिए। Omit callback_url, या null या एक खाली स्ट्रिंग का उपयोग करने के लिए, अधिसूचनाओं को निष्क्रिय करने के लिए।

मौजूदा नौकरी को पुनर्प्राप्त करें

स्थितिक्या करें
प्रस्तुतीकरण समयबद्धInspect runs show async-first and account History. runs recover स्वीकार किए गए कार्य IDs को पुनः प्राप्त कर सकते हैं; यदि कोई ID को बचाया गया था, तो एक अन्य POST भेजने से पहले प्रस्तुतीकरण को फिर से कॉन्फ़िगर करें।
pending / processingमौजूदा नौकरी की जाँच करें। इन राज्यों में असफलता नहीं है।
failed / 422job.error को पढ़ें, इस कारण को सही करें और यह तय करें कि क्या नया काम प्रस्तुत करना है।
429सम्मान Retry-After यदि लंबित नौकरी की क्षमता पूरी हो तो जमा करने की क्षमता को कम करें।
404 / 409404: ID की जाँच करें और खाता जमा करें। 409: परिणाम अभी तक तैयार नहीं हैं।
410संग्रहीत परिणाम JSON समाप्ति के बाद 24 घंटे समाप्त हो जाता है। अपनी सहेजी गई प्रतिलिपि का प्रयोग करें। पहले से ही आपके भंडारण के लिए वितरित मीडिया इस प्रकार है कि भंडारण की अवधारण नीति।

एक YouTube Download नौकरी चल रहा है?

डाउनलोड async या 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 समय फ़िल्टर, जैसे कि Qdr:d पिछले दिन के लिए।

Completion webhookवेबहुक पेलोड, सत्यापन और रिट्राइज़

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 प्रमाणीकरण
Markdown