दस्तावेज़ देखें
गाइड
किसी एप्लिकेशन या एजेंट के लिए पृष्ठभूमि का काम चलाएं, अपनी सहेजी गई नौकरी 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इस टर्मिनल को शेष आदेशों के लिए खुला रखें। एजेंट को अपने गुप्त स्टोर या पर्यावरण से कुंजी पढ़ना चाहिए।
# 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एक पृष्ठभूमि खोज रन
यह walkthrough एक Google Search प्रस्तुत करता है। स्टेटस चेक और परिणाम पुनर्प्राप्ति अन्य क्वेरी प्रस्तुत नहीं करते हैं। इसी तरह के क्रेडेंशियल को पूरी तरह से पुन: उपयोग करें।
1. एक बार जमा करें और रसीद रखें
submission.json फ़ाइल आपकी रसीद है। HTTP एक आईडी, स्रोत, स्थिति और self/results लिंक लौटाता है; CLI जमा करने के तहत रसीद बचाता है और यह भी वापस लौटा देता है remoteId. HTTP 200 का मतलब स्वीकार किया जाता है, समाप्त नहीं होता है।
flashdata search "battery recycling research" --num 5 \
--mode async --run-id async-first --output submission.json --json(
set -euC
: "${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY first}"
test ! -e submission.json || { echo "Use the saved receipt or a new filename." >&2; exit 1; }
curl --fail-with-body --silent --show-error \
--request POST 'https://data.flashdata.dev/v1/queries' \
--header "X-API-Key: $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
)2. मौजूदा नौकरी के लिए प्रतीक्षा करें
जब काम पूरा हो जाता है तो जारी रखें। अगर यह विफल रहा है, तो किसी अन्य चीज़ को जमा करने से पहले अपनी त्रुटि का निरीक्षण करें।
CLI JSON में एक सफल प्रतीक्षा रिटर्न data.status: completed
(
set -euC
JOB_ID=$(jq -er '.remoteId // .id // .submission.id' submission.json)
flashdata jobs wait "$JOB_ID" --timeout 2m --json
)यह एक बार चेक करता है। एक छोटी देरी के बाद GET दोहराएं जबकि job.status लंबित या प्रसंस्करण है। 429 पर, Retry-After को job-headers.txt से प्रतीक्षा करें।
(
set -euC
: "${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY first}"
JOB_ID=$(jq -er '(.remoteId // .id // .submission.id) | select(test("^[A-Za-z0-9_-]+$"))' submission.json)
STATUS_URL="https://api.flashdata.dev/v2/jobs/$JOB_ID"
curl --fail-with-body --silent --show-error \
--header "X-API-Key: $FLASHDATA_API_KEY" \
--max-time 30 --dump-header job-headers.txt --output job.json "$STATUS_URL"
jq -e --arg id "$JOB_ID" '.job.id == $id' job.json >/dev/null
jq '.job | {id, source, status, error}' job.json
){
"job": {
"id": "EXAMPLE_JOB_ID",
"source": "google_search",
"status": "completed",
"error": null
}
}3. प्रतिक्रिया को पुनर्प्राप्त और सहेजना
स्थानीय रूप से result.json सेव करें। पूरा काम और इसके परिणाम शरीर अलग रिकॉर्ड हैं: इस खोज के शरीर में स्रोत: google_search, एक परिणाम सरणी और उपयोग शामिल हैं। नीचे सत्यापन संग्रहीत परिणाम के लिए किया गया है या सफलता की स्थिति को पूरा करने के लिए स्वीकार करता है।
(
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
)डिफ़ॉल्ट JSON परिणाम हस्ताक्षरित भंडारण के लिए पुनर्निर्देशित करता है। यह कोड संग्रहित परिणाम को डिकंप्रेस करता है और एक प्रत्यक्ष JSON प्रतिक्रिया को भी स्वीकार करता है। केवल FlashData समापन बिंदु को आपके API कुंजी प्राप्त होती है।
(
set -euC
: "${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY first}"
JOB_ID=$(jq -er '(.remoteId // .id // .submission.id) | select(test("^[A-Za-z0-9_-]+$"))' submission.json)
SOURCE=$(jq -er '(.submission // .).source' submission.json)
jq -e --arg id "$JOB_ID" --arg source "$SOURCE" \
'.job.id == $id and .job.source == $source and .job.status == "completed"' job.json >/dev/null
test ! -e result.json || { echo "Choose a new output filename." >&2; exit 1; }
RESULT_URL="https://api.flashdata.dev/v2/jobs/$JOB_ID/results"
STATUS=$(curl --silent --show-error \
--header "X-API-Key: $FLASHDATA_API_KEY" \
--max-time 120 --dump-header result-headers.txt --output result.pending \
--write-out '%{http_code}' "$RESULT_URL")
case "$STATUS" in
200) ;;
302)
LOCATION=$(awk 'tolower($1) == "location:" { sub(/\r$/, "", $2); print $2 }' result-headers.txt)
# The signed storage URL is fetched WITHOUT the FlashData API key.
curl --fail-with-body --silent --show-error --compressed --max-time 120 --proto '=https' \
--output result.pending "$LOCATION" ;;
*) echo "Result HTTP $STATUS; inspect result.pending and result-headers.txt." >&2; exit 1 ;;
esac
jq -e --arg source "$SOURCE" '.source == $source and (.status == "done" or .status == "completed")
and (.results | type == "array")' result.pending >/dev/null
cat result.pending > result.json
jq '{id, source, status, results, usage}' result.json
)4. अपने आवेदन में परिणाम का उपयोग करें
सहेजी गई प्रतिक्रिया को मान्य करें, फिर एक खोज दृष्टिकोण या एजेंट के अगले चरण के लिए शीर्षक, लिंक और स्निपेट को निकालें। एक सफल खाली कार्बनिक सरणी का मतलब कोई मिलान आइटम नहीं है; एक लापता क्षेत्र या असफल शरीर की जांच की जरूरत है।
| आवेदन कार्य | संक्रमण |
|---|---|
| प्रतीक्षा | उपयोगकर्ता या एजेंट को नियंत्रण वापस करने से पहले स्वीकार किए गए काम ID का समर्थन करता है। |
| रेडी | परिणाम सहेजे जाने और मान्य होने के बाद मार्क तैयार। अपने कार्य का उपयोग करें ID import/upsert कुंजी के रूप में। |
| ध्यान देने की आवश्यकता है | नौकरी ID और त्रुटि रखें। एक मतदान समय-बाहर या पुनर्प्राप्ति विफलता फिर से जमा करने का अनुरोध नहीं है। |
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 को अलग नहीं करता है।
(
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 के रूप में नीचे की सरणी को सहेजें।
[
{
"source": "google_search",
"query": "battery recycling research",
"params": {
"num": 5
}
},
{
"source": "google_search",
"query": "lithium battery recycling methods",
"params": {
"num": 5
}
}
]flashdata batch submit --input batch.json \
--run-id batch-first --output batch-submission.json --json(
set -euC
: "${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY first}"
test ! -e batch-submission.json || { echo "Keep the saved batch receipt." >&2; exit 1; }
jq '{queries: .}' batch.json > batch-request.json
curl --fail-with-body --silent --show-error \
--request POST 'https://data.flashdata.dev/v1/queries/batch' \
--header "X-API-Key: $FLASHDATA_API_KEY" \
--header 'Content-Type: application/json' \
--data-binary @batch-request.json --output batch-submission.json
jq '.queries[] | {id, source, status}' batch-submission.json
)बचाओ collect-batch.py
Batch कार्य फ़ोल्डर में batch.json और batch-submission.json के बगल में collect-batch.py बनाया गया है। नीचे दिए गए कोड को कॉपी करें और इसे सहेजें।
batch.json, batch-submission.json और बैच-results/ एक साथ रखें। यदि सहेजे गए इनपुट या रसीद बदल जाती है तो स्क्रिप्ट बंद हो जाती है। यह स्थानीय फ़ाइलों को पूरा करने और पढ़ने की त्रुटि के बाद कभी प्रतिस्थापन प्रश्नों को जमा नहीं करता है।
# 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 का मतलब है कि समीक्षा या उन्हें फिर से शुरू करें। कलेक्टर को कोई नया क्वेरी नहीं भेजी जाती है।
python3 collect-batch.pypython collect-batch.pyjq '.[] | {index, job_id, status, result_file, error}' batch-results/outcomes.jsonपूरा होने वाला वेबहुक प्राप्त करें
एक अनुरोध या प्रत्येक Batch प्रविष्टि में स्रोत, क्वेरी और पैराम के बगल में callback_url जोड़ें। उदाहरण बदलें URL अपने रिसीवर के साथ। घटनाओं की रिपोर्ट पूरा होने या विफलता; परिणाम को अलग से पुनर्प्राप्त करें।
- इस घटना पर जोर देते हैं और तुरंत 2xx वापस लौटते हैं। Deduplicate delivery_id (जिसे X-Delivery-Id भी कहा जाता है)।
- यह घटना असाइन नहीं की गई है। अपनी आईडी और स्रोत को अपनी सहेजी हुई रसीद से मिलान करें, फिर मूल रसीद के स्वयं लिंक का उपयोग करके एक स्टेटस को पढ़ाएं। एक एकीकृत घटना द्वारा आपूर्ति की गई URLs पर भरोसा न करें।
- पूरा होने पर, परिणाम प्राप्त करने और सहेजने के लिए। असफल होने पर नौकरी की त्रुटि का निरीक्षण करें। यदि कोई घटना नहीं आती है तो मतदान को एक गिरावट के रूप में रखें।
{
"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 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 / 422 | job.error को पढ़ें, इस कारण को सही करें और यह तय करें कि क्या नया काम प्रस्तुत करना है। |
| 429 | सम्मान Retry-After यदि लंबित नौकरी की क्षमता पूरी हो तो जमा करने की क्षमता को कम करें। |
| 404 / 409 | 404: 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 पूरा परिणाम पर लागू होता है। प्राप्तियों और नौकरी की स्थिति उनके मूल क्षेत्रों को रखती है।
https://data.flashdata.dev/v1/queries