Dokumentation durchsuchen
Anleitungen
Behalten Sie ein Ergebnis mit seiner ursprünglichen Eingabe, Quelllinks und Nutzung und geben Sie es dann ohne weitere Abfrage an einen anderen Prozess weiter.
Auf dieser Seite
Einmal abfragen, das Ergebnis über Aufgaben hinweg verwenden
Erstellen Sie einen Bericht, führen Sie Ihren Parser erneut aus oder geben Sie einem späteren Agentenschritt den gleichen Beweis. Dieser Workflow speichert eine Suche als tragbares Archiv; das Lesen dieses Archivs benötigt weder einen FlashData-Schlüssel noch den ursprünglichen CLI-Zustand.
archive/saved-search/
request.json Originalabfrage und Parameter
response.json unverändert API Antwort
citations.ndjson-Titel, Quelle URLs und Snippets
manifest.json läuft ID, Nutzung, Dateigrößen und SHA-256Bevor Sie anfangen
Verwenden Sie einen neuen Arbeitsordner, den FlashData CLI mit google_search-Berechtigung und verfügbaren Credits. Verwenden Sie ein authentifiziertes Profil oder FLASHDATA_API_KEY. Bash Inspektion verwendet jq; Windows verwendet PowerShell 7. Die lokalen Archivskripte verwenden Python 3.10+ und seine Standardbibliothek.
Fahren Sie fort, wenn data.accessVerified true ist. Für CLI-Retries behalten Sie das gleiche Profil, den OS-Benutzer und das Statusverzeichnis bei. Ein Agent sollte seine vorhandenen Anmeldeinformationen aus seinem geheimen Speicher laden.
flashdata auth status --json1. Behalten Sie den Input und speichern Sie eine Antwort
Speichern Sie request.json unten und führen Sie dann einen Befehl aus. --input verwendet genau diese Anforderung; bewahren Sie die Datei danach unverändert auf. --output speichert den API-Body in search.json; --json druckt CLI-Metadaten. saved-search ist der lokale Ablauf dieser Aufgabe ID.
{
"source": "google_search",
"query": "battery recycling research",
"params": {
"num": 5
}
}flashdata query --input request.json \
--run-id saved-search --output search.json --jsonflashdata query --input request.json `
--run-id saved-search --output search.json --json2. Validierung der gespeicherten Antwort
Erwarten Sie Quelle: google_search, status: done und ein Ergebnis-Array. Drucken Sie den Titel, den Link und das Snippet jedes organischen Ergebnisses. Die tatsächlichen Ergebnisse variieren; eine leere erfolgreiche Sammlung unterscheidet sich von einer fehlgeschlagenen Anforderung oder einem fehlenden Feld.
jq -e '.source == "google_search" and .status == "done"
and (.results | type == "array")
and all(.results[]; (.organic | type == "array"))' search.json > /dev/null &&
jq -c '.results[] | .organic[] | {title, link, snippet}' search.json$result = Get-Content -Raw -LiteralPath search.json | ConvertFrom-Json
if ($result.source -ne 'google_search' -or $result.status -ne 'done' -or
-not ($result.results -is [array])) {
throw 'Inspect search.json before treating the task as complete.'
}
foreach ($page in $result.results) {
if (-not ($page.organic -is [array])) { throw 'Missing organic results array.' }
$page.organic | Select-Object title, link, snippet
}3. Archivieren Sie die Eingaben, Antworten und Zitate
Speichern Sie archive.py unten und führen Sie es dann mit dem Ausführen von ID aus Schritt 1 aus. Es bewahrt die Rohdateien, extrahiert Quelllinks und schreibt manifest.json zuletzt mit Dateiprüfsummen und Nutzung. Erwarten Sie complete: true; Die Anzahl der Zitate hängt von den Suchergebnissen ab. Es werden keine Netzwerkanfragen gestellt.
Speichern Sie archive.py
Erstellen Sie archive.py neben request.json und search.json in Ihrem Arbeitsordner. Kopieren Sie den vollständigen Code unten und speichern Sie ihn.
Das Beispielarchiv Google Search Ergebnisse. Bestehende Archivverzeichnisse werden intakt gehalten. request.json, search.json und das Matching laufen zusammen, bis die Archivierung abgeschlossen ist.
# archive.py — Python 3.10+, standard library only; no network requests.
import argparse
import hashlib
import json
import re
from datetime import datetime, timezone
from pathlib import Path
from urllib.parse import urlsplit
parser = argparse.ArgumentParser()
parser.add_argument('--run-id', required=True)
args = parser.parse_args()
if not re.fullmatch(r'[A-Za-z0-9_-]+', args.run_id):
raise ValueError('Use the CLI run ID from this task.')
request_bytes = Path('request.json').read_bytes()
result_bytes = Path('search.json').read_bytes()
request = json.loads(request_bytes.decode('utf-8-sig'))
result = json.loads(result_bytes.decode('utf-8-sig'))
if (request.get('source') != 'google_search' or result.get('source') != request['source']
or result.get('status') not in ['done', 'completed']
or not isinstance(result.get('results'), list)):
raise ValueError('Inspect the request and result before archiving.')
citations = []
for page in result['results']:
if not isinstance(page, dict) or not isinstance(page.get('organic'), list):
raise ValueError('Expected an organic results array, including when it is empty.')
for item in page['organic']:
if not isinstance(item, dict) or not isinstance(item.get('link'), str):
raise ValueError('A result is missing its source URL.')
url = urlsplit(item['link'])
if url.scheme not in ['http', 'https'] or not url.netloc:
raise ValueError('Inspect an unexpected source URL.')
citations.append({key: item.get(key, '') for key in ['title', 'link', 'snippet']})
files = {'request.json': request_bytes, 'response.json': result_bytes,
'citations.ndjson': ''.join(json.dumps(row, ensure_ascii=False) + '\n'
for row in citations).encode('utf-8')}
manifest = {'version': 1, 'run_id': args.run_id, 'source': request['source'],
'archived_at': datetime.now(timezone.utc).isoformat(),
'usage': result.get('usage'), 'citation_count': len(citations),
'files': {name: {'bytes': len(data), 'sha256': hashlib.sha256(data).hexdigest()}
for name, data in files.items()}}
folder = Path('archive') / args.run_id
folder.mkdir(parents=True) # Existing archives are preserved. Choose a new run ID for new work.
for name, data in files.items():
with (folder / name).open('xb') as output:
output.write(data)
# Write the manifest last. Without it, the archive is incomplete.
with (folder / 'manifest.json').open('x', encoding='utf-8') as output:
json.dump(manifest, output, ensure_ascii=False, indent=2)
print(json.dumps({'archive': str(folder), 'citations': len(citations), 'complete': True}))Erstellen Sie das Archiv
Aus dem Ordner ausführen, der archive.py, request.json und search.json enthält.
python3 archive.py --run-id saved-searchpython archive.py --run-id saved-search4. Wiederverwendung des Archivs ohne Anmeldeinformationen
Speichern Sie reuse.py unten. Kopieren Sie den vollständigen archive/saved-search-Ordner in den Prozess, der ihn benötigt, und führen Sie diesen Reader aus. Es überprüft jede Datei, bevor es die ursprüngliche Abfrage, Verwendung und Zitate ausdruckt. Es funktioniert nach dem Widerruf des API-Schlüssels oder dem Ablauf des Hosted-Results, da nur Ihre gespeicherte Kopie gelesen wird.
Speichern Sie reuse.py
Erstellen von reuse.py im Arbeitsordner mit archive/. Kopieren Sie auf einem anderen Computer sowohl reuse.py als auch das vollständige archive/saved-search-Verzeichnis, wobei Sie dieses Layout beibehalten.
# reuse.py — run without a FlashData key or CLI.
import hashlib
import json
import sys
from pathlib import Path
folder = Path(sys.argv[1])
manifest = json.loads((folder / 'manifest.json').read_text(encoding='utf-8'))
expected = {'request.json', 'response.json', 'citations.ndjson'}
if manifest.get('version') != 1 or set(manifest.get('files', {})) != expected:
raise ValueError('Unknown or incomplete archive manifest.')
files = {}
for name in sorted(expected):
data = (folder / name).read_bytes()
record = manifest['files'][name]
if len(data) != record['bytes'] or hashlib.sha256(data).hexdigest() != record['sha256']:
raise ValueError('Archive changed or was not fully copied: ' + name)
files[name] = data
request = json.loads(files['request.json'].decode('utf-8-sig'))
citations = [json.loads(line) for line in files['citations.ndjson'].decode('utf-8').splitlines()]
if len(citations) != manifest['citation_count']:
raise ValueError('Citation count does not match the manifest.')
print(json.dumps({'run_id': manifest['run_id'], 'query': request['query'],
'archived_at': manifest['archived_at'], 'usage': manifest['usage'],
'citations': citations}, indent=2))Lesen Sie das gespeicherte Archiv
Speichern Sie reuse.py und führen Sie dann aus dem Ordner aus. Das letzte Argument ist der Pfad zum kopierten Archiv.
python3 reuse.py archive/saved-searchpython reuse.py archive/saved-searchExportieren Sie stattdessen aus dem CLI-Journal
Wenn Sie noch über das ursprüngliche CLI-Profil und das Statusverzeichnis verfügen, exportieren Sie den gespeicherten Lauf in einen neuen Dateinamen. Dadurch wird keine neue Abfrage erstellt, aber der Live-Zugriff wird zuerst überprüft. Eine vorhandene Ergebnisdatei oder ein Archiv kann lokal ohne diese Überprüfung gelesen werden.
flashdata runs show saved-search --result --output search-copy.json --jsonEntscheiden Sie, wann Sie wiederverwenden oder aktualisieren
archived_at zeichnet auf, wenn Sie die Dateien gespeichert haben, nicht wenn sich eine Quellseite geändert hat. Ihre Anwendung entscheidet, wie aktuell die Beweise sein müssen; das Kopieren einer Datei aktualisiert nicht ihren Inhalt.
| Aufgabe | Aktion |
|---|---|
| Führen Sie einen Parser erneut aus, regenerieren Sie einen Bericht oder setzen Sie einen Agentenschritt fort | Die gespeicherte Antwort wiederverwenden. Behalten Sie die Quelle URLs, die Abfrageparameter und die Verwendung mit. |
| Erstellen Sie ein neues tägliches Briefing oder beantworten Sie eine geänderte Abfrage | Erstellen Sie einen neuen task/run ID, Arbeitsordner und Archiv. Behalten Sie ältere Snapshots als Geschichte. |
| Nutzung über abgeleitete Dateien zählen | Zählen Sie die ursprüngliche Abfrage einmal. Das Kopieren einer Antwort oder das Erstellen eines anderen Berichts verursacht keine weitere Gebühr. |
Wissen, was abläuft
| Ergebnis | Was zu behalten | Retention |
|---|---|---|
| Realtime-Abfrage | Die Antwortdatei und die ursprüngliche Eingabe | Ihre gespeicherte Kopie folgt Ihrer Speicherrichtlinie |
| Async / Batch Job | Job ID, Einreichungsbestätigung und Ergebnis JSON | 24 Stunden nach Fertigstellung |
| Bulk | Manifest und alle NDJSON Teile | 24 Stunden nach Abschluss des gesamten Auftrags; Überprüfen Sie expiresAt |
| YouTube Download | Lieferung JSON und Medien an Ihrem Zielort | Lieferung JSON: Arbeitsplatzbindung. Medien: Ihr Bucket Lifecycle |
| MCP Chunk Cache | Das vollständig zusammengefügte Ergebnis | 10 Minuten; nur die vier neuesten großen Ergebnisse pro API Schlüssel werden beibehalten |
Halten Sie stattdessen einen kleinen Sidecar
Behalten Sie die ursprüngliche Antwort unverändert. Speichern Sie ein kleines Sidecar mit der Eingabe, Quelle, sparen Sie Zeit und Nutzung, damit ein späterer Prozess verstehen kann, was die Datei produziert hat. Behalten Sie die Quell-URLs- und Video-Zeitstempel bei der Transformation von Ergebnissen.
(
set -euC
jq --arg run_id 'saved-search' --slurpfile request request.json \
'{run_id: $run_id, source, input: $request[0],
saved_at: (now | todateiso8601), result_file: "search.json", usage}' \
search.json > search-record.json
cat search-record.json
)Sparen Sie direkt mit HTTP
Verwenden Sie diese anstelle der CLI-Abfrage in Schritt 1. Speichern Sie die gleiche request.json zuerst; dies führt eine neue Abfrage mit Bash, cURL 7.76+ und jq aus. Verwenden Sie FLASHDATA_API_KEY wieder und wählen Sie einen Ordner ohne search.json aus. Nach der Validierung arbeiten die gleichen Archivskripte mit diesem Ergebnis; Wählen Sie Ihre eigene Aufgabe ID für --run-id.
Ein cURL-Ausgang bedeutet, dass das Ergebnis nicht gebrauchsbereit ist. Überprüfen Sie die gespeicherte Antwort, bevor Sie erneut versuchen; ein Verbindungszeitüberschreitung kann passieren, nachdem eine Abfrage akzeptiert wurde. Verwenden Sie den Validierungsbefehl in Schritt 2.
# 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(
set -euC
: "${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY first}"
test -f request.json
curl --fail-with-body --silent --show-error --max-time 120 \
--request POST 'https://data.flashdata.dev/v1/queries/realtime' \
--header "X-API-Key: $FLASHDATA_API_KEY" \
--header 'Content-Type: application/json' --header 'Accept: application/json' \
--data-binary @request.json > search.json
jq . search.json
)Speichern Sie einen vorhandenen Hintergrundjob
Verwenden Sie submission.json aus der async-Anleitung und dem gleichen Konto-Anmeldeinformationen. Diese Befehle rufen vorhandene Arbeit ab; sie senden keine weitere Abfrage. Der CLI wartet auf die Fertigstellung und verarbeitet die Ergebnisumleitung. Speichern Sie das Ergebnis innerhalb von 24 Stunden nach Abschluss.
(
set -euC
JOB_ID=$(jq -er '.remoteId // .id // .submission.id' submission.json)
flashdata jobs wait "$JOB_ID" --json
flashdata jobs result "$JOB_ID" --output job-result.json --json
jq '{source, status, results, usage}' job-result.json
)Die Statusprüfung wird beendet, wenn der Job nicht abgeschlossen ist. Wenn es immer noch in der Warteschlange steht oder läuft, warten Sie und führen Sie dieses Nur-Lese-Snippet erneut aus; Überprüfen Sie stattdessen einen fehlgeschlagenen Job. Ein 302 wird heruntergeladen, ohne Ihren API-Schlüssel weiterzuleiten. Die temporäre Antwort wird validiert, bevor job-result.json erstellt wird.
(
set -euC
: "${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY first}"
test ! -e job-result.json || { echo 'Choose a new output filename.' >&2; exit 1; }
JOB_ID=$(jq -er '.remoteId // .id // .submission.id' submission.json)
printf '%s' "$JOB_ID" | grep -Eq '^[A-Za-z0-9_-]+$'
SOURCE=$(jq -er '(.submission // .).source' submission.json)
API="https://api.flashdata.dev/v2/jobs/$JOB_ID"
curl --fail-with-body --silent --show-error \
--max-time 30 --header "X-API-Key: $FLASHDATA_API_KEY" "$API" >| job-status.json
jq -e --arg id "$JOB_ID" --arg source "$SOURCE" \
'.job.id == $id and .job.source == $source and .job.status == "completed"' job-status.json >/dev/null
STATUS=$(curl --silent --show-error \
--header "X-API-Key: $FLASHDATA_API_KEY" \
--max-time 120 --dump-header result-headers.txt --output job-result.pending \
--write-out '%{http_code}' "$API/results")
case "$STATUS" in
200) ;;
302)
LOCATION=$(awk 'tolower($1) == "location:" { sub(/\r$/, "", $2); print $2 }' result-headers.txt)
# No FlashData API key on the signed storage request.
curl --fail-with-body --silent --show-error --compressed --max-time 120 \
--proto '=https' --output job-result.pending "$LOCATION" ;;
*) echo "HTTP $STATUS: inspect job-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")' job-result.pending >/dev/null
cat job-result.pending > job-result.json
jq '{source, status, results, usage}' job-result.json
)Speichern Sie jeden Bulk Ergebnisteil
Ersetzen Sie BULK_ID mit dem ID in Ihrem Einreichungsbeleg. Nach Abschluss des Auftrags folgt das CLI dem Manifest und speichert jedes Teil als eine NDJSON-Datei. Halten Sie das Manifest auch, wenn Sie Zählungen und Teil-Metadaten benötigen.
Die Datei kann sowohl erfolgreiche als auch fehlgeschlagene Zeilen enthalten. Abgleichen von Input-Indizes und Zählungen, bevor Sie die gesamte Aufgabe abschließen. Führen Sie nicht die gesamte Eingabedatei erneut aus, um eine fehlgeschlagene Zeile wiederherzustellen.
flashdata bulk results BULK_ID --output bulk-results.ndjson --timeout 30m --jsonHalten Sie die Lieferaufzeichnung und die Medien
delivery.json enthält einen Lieferdatensatz, nicht die Video- oder Audiobytes. Speichern Sie seine URL, Größe und Prüfsumme neben der Aufgabe. Das Medium lebt in Ihrem Zielspeicher und folgt dem Lebenszyklus dieses Speichers.
Verwenden Sie für ein privates Ziel die Anmeldeinformationen dieses Anbieters oder das signierte URL, um das Objekt zu inspizieren. Ein fehlendes temporäres Ergebnis JSON bedeutet nicht, dass Ihre gespeicherten Medien gelöscht wurden.
jq '.results[] | {file_url, file_size, md5, downloaded_bytes, output_format}' delivery.jsonBauen Sie MCP-Stücke vor dem Speichern zusammen
Wenn ein Tool result_id, chunk und next_offset zurückgibt, lesen Sie die verbleibenden Chunks mit get_result mit dem gleichen API-Schlüssel. Verwenden Sie den genauen next_offset, der vom Werkzeug zurückgegeben wird; die folgenden Werte sind Platzhalter.
- Fügen Sie jedes Stück in versetzter Reihenfolge hinzu. Folgen Sie next_offset, bis es null ist.
- Parse den zusammengefügten Text einmal als JSON, dann schreiben Sie das vollständige Ergebnis in Ihre eigene Datei oder Speicher.
- Speichern Sie vor expires_at. Neue große Antworten können ältere Ergebnisse vor dem 10-Minutenlimit vertreiben; der Cache behält vier pro API-Schlüssel.
{
"name": "get_result",
"arguments": {
"result_id": "RESULT_ID_FROM_TOOL",
"offset": 16000
}
}Beheben von Speicher- und Abrufproblemen
| Problem | Fixpunkt |
|---|---|
| Ausgabedatei bereits vorhanden | Überprüfen Sie es zuerst. Verwenden Sie für einen abgeschlossenen CLI-Lauf runs show mit einem neuen Ausgabedateinamen, anstatt eine weitere Abfrage einzureichen. |
| CLI kann den Lauf nicht finden | Verwenden Sie das ursprüngliche OS-Benutzer-, Profil- und Statusverzeichnis. Wenn Sie einen Remote-Job ID beibehalten haben, rufen Sie diesen Job direkt ab. |
| 401 / 403 bei Wiederverwendung | Führen Sie Flashdata auth status --json aus und stellen Sie den gültigen Zugriff wieder her. Eine bereits gespeicherte lokale Datei kann weiterhin ohne API-Zugriff gelesen werden. |
| 409 / 410 | 409: Warten auf den bestehenden Job. 410: Verwenden Sie Ihre gespeicherte Kopie; das vorläufige Ergebnis ist abgelaufen. |
| Disk-Fehler nach einer Abfrage | Führen Sie ID oder ID aus. Speichern und Wiederherstellen vorhandener Arbeiten, bevor eine neue Einreichung in Betracht gezogen wird. |
| Archiv hat kein Manifest oder eine Prüfsumme schlägt fehl | Stellen Sie die Originaldateien wieder her oder kopieren Sie sie erneut. Bewahren Sie ein unvollständiges Archiv zur Inspektion auf; das Umbauen des Archivs erfordert keine neue Abfrage. |
| MCP · result_unavailable | Prüfen Sie das Ergebnis ID, Offset, API-Schlüssel und Ablauf. Verwenden Sie eine gespeicherte Kopie, wenn der Cache abgelaufen ist; Schleifen Sie nicht, indem Sie eine bezahlte Abfrage wiederholen. |