Überspringen zum Inhalt
DE
API-Schlüssel
Dokumentation durchsuchen

Anleitungen

Async & Batch-Anfragen

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.

BleibenZweck
Auftragsbestätigungsubmission.json - Behalten Sie den akzeptierten Job ID mit Ihrer Anwendungsaufgabe und der ursprünglichen Eingabe.
Gespeicherte Antwortresult.json - validieren Sie seine Quelle und Ergebnisse, bevor Sie es importieren.
Batch Ergebnissebatch-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.

Freier Zugang und Kontoprüfungen
flashdata auth status --json
flashdata account balance --json
flashdata account limits --json

Fü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.

Bash · FlashData CLI
flashdata search "battery recycling research" --num 5 \
  --mode async --run-id async-first --output submission.json --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.

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

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.

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. 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
WartenBeharren Sie auf dem akzeptierten Job ID, bevor Sie die Kontrolle an den Benutzer oder Agenten zurückgeben.
FertigMarkieren Sie bereit, nachdem das Ergebnis gespeichert und validiert wurde. Verwenden Sie Ihre Aufgabe ID als import/upsert Schlüssel.
braucht AufmerksamkeitBehalten Sie den Job ID und Fehler. Ein Polling Timeout oder Retrieval-Fehler ist keine erneute Anforderung.
Lesen Sie die lokale Antwort · keine API Anrufe
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

Wiederaufnahme 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.

CLI + jq · Wiederherstellen des gespeicherten Jobs
(
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.

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

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

Bash
python3 collect-batch.py
PowerShell 7
python collect-batch.py
Lesen Sie jedes Ergebnis · jq
jq '.[] | {index, job_id, status, result_file, error}' batch-results/outcomes.json

Erhalten 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.

  1. Beharren Sie auf der Veranstaltung und geben Sie 2xx umgehend zurück. Deduplizieren Sie delivery_id (auch als X-Delivery-Id gesendet).
  2. 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.
  3. 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.
Request Body mit Callback
{
  "source": "google_search",
  "query": "battery recycling research",
  "params": {
    "num": 5
  },
  "callback_url": "https://your-app.example/webhooks/flashdata"
}
Veranstaltungskörper · Veranschaulichung
{
  "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

LageLösung
Einreichungsfrist abgelaufenInspektion 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 / 422Lesen Sie job.error, korrigieren Sie die Ursache und entscheiden Sie, ob Sie neue Arbeiten einreichen möchten.
429Ehre Retry-After. Reduzieren Sie die Submission Concurrency, wenn die Kapazitäten für ausstehende Stellen voll sind.
404 / 409404: Überprüfen Sie das ID und senden Sie Konto. 409: Ergebnisse sind noch nicht fertig.
410Das 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.

BetriebEndpunkt
Einen Job einreichenPOST https://data.flashdata.dev/v1/queries
Einreichen einer ChargePOST https://data.flashdata.dev/v1/queries/batch
LesestatusGET https://api.flashdata.dev/v2/jobs/{id}
LeseergebnisseGET 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.

Quellenparameter

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 WebhookWebhook-Nutzlast, Verifizierung und Wiederholungen

Markdown gilt für abgeschlossene Ergebnisse. Quittungen und Jobstatus behalten ihre ursprünglichen Felder.

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']}")
Job-Empfang, dann Umfrage für ErgebnisseX-API-Key-Authentifizierung