Dokumentation durchsuchen
Anleitungen
Führen Sie Hintergrundarbeit für eine Anwendung oder einen Agenten aus, setzen Sie den gespeicherten Job ID fort und sammeln Sie jedes Batch-Ergebnis.
Auf dieser Seite
Arbeiten Sie weiter, nachdem Ihr Prozess gestoppt wurde
Verwenden Sie einen Hintergrundjob für eine in die Warteschlange gestellte Anwendungsaufgabe oder einen Agenten-Workflow, der finish später ausführen kann. Dieser Durchlauf führt eine Google-Suche aus, speichert ihren Erhalt und setzt diesen in einem anderen Prozess fort.
| Bleiben | Zweck |
|---|---|
| Auftragsbestätigung | submission.json - Behalten Sie den akzeptierten Job ID mit Ihrer Anwendungsaufgabe und der ursprünglichen Eingabe. |
| Gespeicherte Antwort | result.json - validieren Sie seine Quelle und Ergebnisse, bevor Sie es importieren. |
| Batch Ergebnisse | batch-results/outcomes.json — ein Eintrag pro Eingabe, mit seinem Job ID und Ergebnisdatei. |
Bevor Sie anfangen
Verwenden Sie einen API-Schlüssel mit google_search-Zugriff und verfügbaren Credits. Wählen Sie CLI oder HTTP zum Einreichen, Warten und Abrufen. Die Bash Beispiele verwenden jq; HTTP benötigt auch cURL 7.76+. Führen Sie einen neuen Arbeitsordner aus.
Verwenden Sie Ihr authentifiziertes CLI-Profil oder FLASHDATA_API_KEY erneut. data.accessVerified ist true. Setzen Sie FLASHDATA_PROFILE für ein benanntes Profil, so dass spätere Skripte es auch verwenden. Wenn kein Schlüssel konfiguriert ist, verwenden Sie zuerst das CLI-Authentifizierungshandbuch.
flashdata auth status --json
flashdata account balance --json
flashdata account limits --jsonHalten Sie dieses Terminal für die verbleibenden Befehle offen. Agenten sollten den Schlüssel aus ihrem geheimen Speicher oder ihrer Umgebung lesen.
# 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_KEYFühren Sie eine Hintergrundsuche durch
Dieser Walkthrough sendet ein Google Search. Statuschecks und Ergebnisabruf senden keine weitere Abfrage. Verwenden Sie die gleichen Anmeldeinformationen durchweg wieder.
1. Einmal einreichen und die Quittung behalten
Die submission.json-Datei ist Ihre Quittung. HTTP gibt eine ID, Quelle, Status und self/results-Links zurück; CLI speichert die Quittung unter Einreichung und gibt auch remoteId zurück. HTTP 200 bedeutet akzeptiert, nicht fertig.
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. Warten Sie auf den bestehenden Job
Fahren Sie fort, wenn der Job abgeschlossen ist. Wenn es fehlgeschlagen ist, überprüfen Sie seinen Fehler, bevor Sie etwas anderes einreichen.
Eine erfolgreiche Wartezeit gibt data.status: completed in CLI JSON zurück.
(
set -euC
JOB_ID=$(jq -er '.remoteId // .id // .submission.id' submission.json)
flashdata jobs wait "$JOB_ID" --timeout 2m --json
)Dies überprüft einmal. Wiederholen Sie den GET nach einer kurzen Verzögerung, während job.status anhängig ist oder verarbeitet wird. Warten Sie auf 429 auf Retry-After von 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. Abrufen und Speichern der Antwort
Speichern Sie result.json lokal. Der abgeschlossene Job und sein Ergebniskörper sind separate Datensätze: Der Textkörper dieser Suche enthält die Quelle: google_search, ein Ergebnisfeld und eine Verwendung. Die unten stehende Validierung akzeptiert den Status des abgeschlossenen oder abgeschlossenen Ergebnisses.
(
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
)Das standardmäßige JSON-Ergebnis leitet zu signiertem Speicher um. Dieser Code dekomprimiert das gespeicherte Ergebnis und akzeptiert auch eine direkte JSON-Antwort. Nur der FlashData Endpunkt erhält Ihren API Schlüssel.
(
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. Verwenden Sie das Ergebnis in Ihrer Anwendung
Validieren Sie die gespeicherte Antwort und extrahieren Sie dann Titel, Link und Snippet für eine Suchansicht oder den nächsten Schritt des Agenten. Ein erfolgreiches leeres organisches Array bedeutet keine übereinstimmenden Gegenstände; ein fehlendes Feld oder ein ausgefallener Körper muss untersucht werden.
| Anwendungsaufgaben | Übergangszeit |
|---|---|
| Warten | Beharren Sie auf dem akzeptierten Job ID, bevor Sie die Kontrolle an den Benutzer oder Agenten zurückgeben. |
| Fertig | Markieren Sie bereit, nachdem das Ergebnis gespeichert und validiert wurde. Verwenden Sie Ihre Aufgabe ID als import/upsert Schlüssel. |
| braucht Aufmerksamkeit | Behalten Sie den Job ID und Fehler. Ein Polling Timeout oder Retrieval-Fehler ist keine erneute Anforderung. |
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.jsonWiederaufnahme in einem anderen Prozess
Öffnen Sie ein neues Terminal im gleichen Ordner mit dem gleichen credential/profile. Diese Befehle lesen den Job in submission.json und speichern in einen neuen Dateinamen. Sie geben niemals Arbeit ab. Die Wiederverwendung des gleichen CLI-Laufs ID erfordert sein ursprüngliches Zustandsverzeichnis; HTTP selbst dedupliziert keine POSTs mit diesem lokalen ID.
(
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
)Mehrere Abfragen einreichen
Batch reicht unabhängige Jobs in einer Anfrage ein. Dieses zwei-Abfrage-Beispiel benötigt Kapazität für mindestens zwei Abfragen und zwei ausstehende Jobs; eine temporäre Studie ist auf eine beschränkt. Speichern Sie das Array unten als batch.json in einem separaten Arbeitsordner.
[
{
"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
)Speichern Sie collect-batch.py
Erstellen Sie collect-batch.py im Arbeitsordner Batch neben batch.json und batch-submission.json. Kopieren Sie den vollständigen Code unten und speichern Sie ihn.
Halten Sie batch.json, batch-submission.json und Batch-Ergebnisse / zusammen. Das Skript stoppt, wenn sich die gespeicherten Eingaben oder Quittungen ändern. Es verwendet abgeschlossene lokale Dateien wieder und sendet nach einem Lesefehler niemals Ersatzanfragen.
# 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)Verfolgen Sie jeden angenommenen Job
Führen Sie es nach dem Speichern von collect-batch.py aus dem Arbeitsordner Batch mit Python 3.10+ und dem authentifizierten CLI aus. Es funktioniert mit beiden oben genannten einreichungsmethode. Es liest jede Quittung, wartet bis zu zwei Minuten pro unvollendetem Job und speichert jede erfolgreiche Antwort. Führen Sie einen Sammler nach dem anderen aus; Führen Sie ihn erneut aus, um die gleichen Jobs fortzusetzen.
Erwarten Sie zwei Einträge in batch-results/outcomes.json für die Probe. Importieren Sie abgeschlossene Einträge nach Eingabeindex und Job ID. Fehlgeschlagene, ausstehende und read_error-Einträge bleiben sichtbar; Exit-Code 2 bedeutet, sie zu überprüfen oder wieder aufzunehmen. Der Sammler sendet keine neuen Anfragen.
python3 collect-batch.pypython collect-batch.pyjq '.[] | {index, job_id, status, result_file, error}' batch-results/outcomes.jsonErhalten Sie einen Completement Webhook
Fügen Sie callback_url neben Quelle, Abfrage und Params in einer einzelnen Anforderung oder jedem Batch-Eintrag hinzu. Ersetzen Sie das Beispiel URL durch Ihren Empfänger. Ereignisse melden Abschluss oder Misserfolg; das Ergebnis separat abrufen.
- Beharren Sie auf der Veranstaltung und geben Sie 2xx umgehend zurück. Deduplizieren Sie delivery_id (auch als X-Delivery-Id gesendet).
- Die Veranstaltung ist nicht signiert. Passen Sie seine ID und Quelle mit Ihrer gespeicherten Quittung ab und authentifizieren Sie dann einen Status, der mit dem Selbstlink der ursprünglichen Quittung gelesen wurde. Vertrauen Sie nicht URLs, das durch ein nicht verifiziertes Ereignis bereitgestellt wird.
- Nach Abschluss holen und speichern Sie das Ergebnis. Wenn Sie fehlgeschlagen sind, überprüfen Sie den Jobfehler. Führen Sie Umfragen als Rückfall, wenn kein Ereignis eintrifft.
{
"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"
}
]
}Rückruf URL Anforderungen
Verwenden Sie ein öffentliches HTTPS URL auf Port 443, höchstens 2,048 Zeichen, ohne Anmeldeinformationen oder ein Fragment. Jede aufgelöste IP muss öffentlich sein. callback_url weglassen oder null oder einen leeren String verwenden, um Benachrichtigungen zu deaktivieren.
Wiederherstellen eines bestehenden Arbeitsplatzes
| Lage | Lösung |
|---|---|
| Einreichungsfrist abgelaufen | Inspektion runs show async-first und account History. runs recover Kann akzeptierten Job abrufen IDs; falls nein ID wurde gespeichert, versöhnen Sie die Einreichung, bevor Sie eine andere senden POST. |
| pending / processing | Überprüfen Sie weiterhin den bestehenden Job. Diese Staaten sind keine Versager. |
| failed / 422 | Lesen Sie job.error, korrigieren Sie die Ursache und entscheiden Sie, ob Sie neue Arbeiten einreichen möchten. |
| 429 | Ehre Retry-After. Reduzieren Sie die Submission Concurrency, wenn die Kapazitäten für ausstehende Stellen voll sind. |
| 404 / 409 | 404: Überprüfen Sie das ID und senden Sie Konto. 409: Ergebnisse sind noch nicht fertig. |
| 410 | Das gespeicherte Ergebnis JSON läuft Stunden nach Abschluss des 24 ab. Verwenden Sie Ihre gespeicherte Kopie. Medien, die bereits an Ihren Speicher geliefert wurden, folgen den Aufbewahrungsrichtlinien dieses Speichers. |
Einen YouTube Download Job ausführen?
Der Download verwendet async oder Batch und benötigt einen Besitzer-API-Schlüssel mit youtube_download-Zugang plus Zielspeicher. Das Ergebnis JSON beschreibt Medien, die bereits an Ihren Bucket geliefert wurden; der Ergebnisendpunkt streamt keine Videobytes. Verwenden Sie die Download-Anleitung, um den Speicher zu konfigurieren und die gelieferte Datei zu überprüfen.
Hosts und Antwortformate
Alle vier verwenden X-API-Key. Verwenden Sie den gleichen Schlüssel wie die Einreichung. Status- und Ergebnislesungen sind kostenlos, aber ratenbegrenzt. Die Beispiele verwenden JSON; Wählen Sie Accept und X-Respond-With im Builder für andere Ergebnisdarstellungen. Ein signierter Speicherdownload verwendet seinen URL, ohne den FlashData-Schlüssel.
| Betrieb | Endpunkt |
|---|---|
| Einen Job einreichen | POST https://data.flashdata.dev/v1/queries |
| Einreichen einer Charge | POST https://data.flashdata.dev/v1/queries/batch |
| Lesestatus | GET https://api.flashdata.dev/v2/jobs/{id} |
| Leseergebnisse | GET https://api.flashdata.dev/v2/jobs/{id}/results |
Unterstützte Quellen und Modi
Verwenden Sie den Builder unten für die aktuellen Parameter der Quelle. Google Search und YouTube Data unterstützen Hintergrundjobs. YouTube Download verwendet Hintergrundjobs und Zielspeicher. Für eine große Videodatei IDs mit gemeinsam genutzten Optionen verwenden Sie die Anleitung Bulk.
Erstellen Sie einen Workflow für Ihre Quelle
Wählen Sie eine Quelle aus, bearbeiten Sie deren Parameter und kopieren Sie den generierten Workflow in Ihrer Sprache. Aktivieren Sie einen Rückruf, um das Empfängerbeispiel zu offenbaren. Dieser Builder zeigt Code- und Beispielantworten an; Anfragen werden nur ausgeführt, wenn Sie den Code ausführen oder die Konsole verwenden.
Anfrage erstellen
Erweiterte Parameter
Beginnt bei 1. Jede Seite ist eine separate Anfrage.
Google-Zeitfilter, zum Beispiel qdr:d für die letzten 24 Stunden.
Ausfüllen Webhook
Webhook-Nutzlast, Verifizierung und WiederholungenMarkdown gilt für abgeschlossene Ergebnisse. Quittungen und Jobstatus behalten ihre ursprünglichen Felder.
https://data.flashdata.dev/v1/queries