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

API-Referenz

Realtime und async

Holen Sie sich Ergebnisse in der Antwort, oder senden Sie einen Job und holen Sie sie später ab. Wählen Sie aus, wie Ihre Anwendung oder Ihr Agent auf die Arbeit wartet.

Auf dieser Seite

Wählen Sie einen Anforderungsmodus

Google Search und YouTube Data unterstützen beide Modi. YouTube Download erfordert async, Batch oder Bulk; es unterstützt keine Echtzeit. Die Quellparameter bleiben beim Wechsel von Echtzeit zu async gleich.

ModusVerwendung beiWas Sie erhalten
RealtimeEin Suchergebnis wird in der aktuellen Interaktion benötigt.Der Ergebniskörper in der gleichen HTTP Antwort.
AsyncDie Arbeit sollte fortgesetzt werden, nachdem sich Ihr Prozess getrennt hat oder Sie Medien herunterladen.Ein Job ID sofort; Status abrufen und Ergebnisse separat.
Anforderungslebensdauer
Realtime POST data.flashdata.dev/v1/queries/realtime
Async POST data.flashdata.dev/v1/queries → Job ID
          GET api.flashdata.dev/v2/jobs/{id} → Status
          GET api.flashdata.dev/v2/jobs/{id}/results → Ergebnisse

Senden Sie eine Anfrage

Setzen Sie FLASHDATA_API_KEY auf einen Schlüssel, der google_search erlaubt. Wählen sie echtzeit oder async; jede einreichung führt eine abrechenbare suche aus. Bewahren Sie Skripte, Quittungen und Ergebnisse im gleichen neuen Arbeitsordner auf.

Python-Beispiele verwenden Python 3.10+ und Requests. Jedes Skript läuft unabhängig voneinander und liest gespeicherte Dateien aus früheren Schritten. Die cURL-Alternative benötigt Bash, cURL 7.76+ und jq.

Python · einmal installieren
python3 -m pip install requests

Realtime: Holen Sie sich das Ergebnis jetzt

POST /v1/queries/realtime gibt status: done und ein Ergebnis-Array zurück. Lesen Sie result.json; es ist keine Umfrage erforderlich.

Speichern Sie als realtime.py und führen Sie python3 realtime.py aus.

realtime.py
import json
import os
from pathlib import Path

import requests

response = requests.post(
    "https://data.flashdata.dev/v1/queries/realtime",
    headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
    json={"source": "google_search", "query": "battery recycling research", "params": {"num": 5}},
    timeout=120, allow_redirects=False,
)
response.raise_for_status()
result = response.json()
Path("result.json").write_text(json.dumps(result, indent=2), encoding="utf-8")
print(json.dumps(result, indent=2))

Async: Speichern Sie einen Jobbeleg

POST /v1/queries gibt eine ausstehende Auftragsbestätigung zurück, nicht die Suchergebnisse. Speichern Sie submission.json und fahren Sie mit den Status- und Ergebnisanforderungen unten fort.

Speichern Sie als submit_async.py und führen Sie python3 submit_async.py aus.

submit_async.py
import json
import os
from pathlib import Path

import requests

response = requests.post(
    "https://data.flashdata.dev/v1/queries",
    headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
    json={"source": "google_search", "query": "battery recycling research", "params": {"num": 5}},
    timeout=30, allow_redirects=False,
)
response.raise_for_status()
result = response.json()
Path("submission.json").write_text(json.dumps(result, indent=2), encoding="utf-8")
print(json.dumps(result, indent=2))
Empfangsfelder · abgekürztes Beispiel
{
  "id": "job_EXAMPLE",
  "source": "google_search",
  "status": "pending"
}

Überprüfen Sie einen Async-Job

Lesen Sie job.status mit dem ID in submission.json. Warten Sie für das Anwarten oder die Verarbeitung auf die Retry-After-Verzögerung, bevor Sie erneut prüfen; Python druckt es und cURL speichert es in status-headers.txt. Verwenden Sie Backoff, wenn kein Hinweis zurückgegeben wird. Eine erfolgreiche Statusanfrage bedeutet nicht, dass der Job abgeschlossen ist.

job.statusNächste Maßnahme
pending / processingWarten Sie, dann überprüfen Sie den gleichen Job ID erneut.
completedHolen Sie das gespeicherte Ergebnis ab.
failedLesen Sie job.error. Beheben Sie die Ursache, bevor Sie neue Arbeiten einreichen.

Speichern Sie als job_status.py und führen Sie python3 job_status.py aus.

job_status.py
import json
import os
from pathlib import Path

import requests

job_id = json.loads(Path("submission.json").read_text(encoding="utf-8"))["id"]
response = requests.get(
    f"https://api.flashdata.dev/v2/jobs/{job_id}",
    headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
    timeout=30, allow_redirects=False,
)
response.raise_for_status()
Path("job.json").write_text(json.dumps(response.json(), indent=2), encoding="utf-8")
print(json.dumps(response.json()["job"], indent=2))
print("Retry-After:", response.headers.get("Retry-After", "not provided"))

Abrufen des abgeschlossenen Ergebnisses

Führen Sie dies aus, nachdem job.status abgeschlossen ist. Die Standardergebnisantwort lautet 302: Standort verweist auf einen signierten Speicher URL. Die beiden folgenden Anforderungen behalten Ihren API-Schlüssel auf FlashData und speichern den ursprünglichen JSON in result.json. Für YouTube Download beschreibt dieses JSON Medien, die an Ihren Speicher geliefert werden; es ist nicht die Video- oder Audiodatei.

Speichern Sie als job_result.py und führen Sie python3 job_result.py aus.

job_result.py
import json
import os
from pathlib import Path

import requests

receipt = json.loads(Path("submission.json").read_text(encoding="utf-8"))
job_id = receipt["id"]
response = requests.get(
    f"https://api.flashdata.dev/v2/jobs/{job_id}/results",
    headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
    timeout=30, allow_redirects=False,
)
response.raise_for_status()
if response.status_code != 302:
    raise RuntimeError(f"Expected a result redirect, got {response.status_code}")
url = response.headers["Location"]
if not url.startswith("https://"):
    raise ValueError("Expected an HTTPS storage URL")

# A separate request: no FlashData key is sent to storage.
result = requests.get(url, timeout=120)
result.raise_for_status()
data = result.json()  # Requests automatically decodes Content-Encoding: gzip.
Path("result.json").write_text(json.dumps(data, indent=2), encoding="utf-8")
print(json.dumps(data, indent=2))

Handhabung von Verzögerungen und Ausfällen

LageLösung
Einreichungsfrist abgelaufenEin POST wurde möglicherweise bereits akzeptiert. Überprüfen Sie Ihre gespeicherte Quittung und den Kontoverlauf, bevor Sie erneut einreichen; wiederholte POSTs können neue abrechenbare Jobs erstellen.
409 · result_not_readyBehalten Sie den Wahlstatus. Schaffen Sie sich keinen anderen Job.
422 · result_not_readyDer Job ist gescheitert. Lesen Sie job.error, bevor Sie es erneut versuchen.
429Ehre Retry-After oder retry_after; Reduzieren Sie die Einreichungsrate, wenn die ausstehende Kapazität voll ist.
410 · result_expiredGespeicherte Ergebnisse verfallen 24 Stunden nach Abschluss. Verwenden Sie Ihre gespeicherte Kopie.