# Durchsuchen Sie das Web und speichern Sie Quelllinks

Führen Sie eine Google-Suche aus. Speichern Sie eindeutige Quelllinks in der Ergebnisreihenfolge zusammen mit der Abfrage und Nutzung.

Kanonische Referenz: https://flashdata.dev/de/docs/guides/web-search-recipe
Test: 2026-11-05 von FlashData

<a id="prepare"></a>

## Bevor Sie anfangen

Verwenden Sie einen Schlüssel mit google_search-Berechtigung und verfügbaren Credits. Wählen Sie Python 3.10+ mit Anfragen oder Bash mit cURL 7.76+ und jq. Verwenden Sie auf Windows Git Bash für den Bash Pfad.

- [API-Schlüssel erstellen](https://flashdata.dev/app/api-keys)
- [Zugang zu Agentenversuchen](https://flashdata.dev/de/docs/guides/agent-access/reference.md)
- [Credits und Preise](https://flashdata.dev/de/docs/guides/credits-and-billing/reference.md)

<a id="input"></a>

## 1. Bereiten Sie die Abfrage

Erstellen Sie einen Web-Suchordner. Speichern Sie request.json dort und öffnen Sie dann ein Terminal in diesem Ordner. Dieses Beispiel fordert bis zu fünf organische Ergebnisse an; ein neuer Lauf sendet eine abrechenbare Abfrage.

### web-search/request.json

```json
{
  "source": "google_search",
  "query": "battery recycling research",
  "params": {
    "num": 5
  }
}
```


<a id="run"></a>

## 2. Speichern und Ausführen des Skripts

Wählen Sie eine Version und speichern Sie das Skript neben request.json. Es liest FLASHDATA_API_KEY oder fordert Ihren Schlüssel auf, ohne ihn anzuzeigen. Ein Agent sollte die Umgebungsvariable aus seinem geheimen Speicher liefern.

Führen Sie mit search-001 als Ausgabeordner aus. Das Skript speichert die genaue Anfrage, bevor es gesendet wird. Wenn Sie erneut mit demselben Ordner ausgeführt werden, wird die gespeicherte Antwort gelesen, ohne den API aufzurufen.

### Python

#### Installieren Sie in Ihrer Python-Umgebung

```bash
python -m pip install requests
```

#### web-search/search.py

```python
import argparse
import getpass
import json
import os
from datetime import datetime, timezone
from pathlib import Path

import requests

parser = argparse.ArgumentParser()
parser.add_argument("folder", help="New output folder, or an existing saved search")
out = Path(parser.parse_args().folder)

if not out.exists():
    body = Path("request.json").read_bytes()
    request = json.loads(body)
    if not isinstance(request, dict) or request.get("source") != "google_search" or not request.get("query"):
        raise SystemExit("request.json must contain google_search and a query")
    key = os.environ.get("FLASHDATA_API_KEY") or getpass.getpass("FlashData API key: ")
    if not key.strip():
        raise SystemExit("An API key is required")
    out.mkdir()  # A concurrent run cannot submit into the same folder.
    (out / "request.json").write_bytes(body)
    (out / "requested-at.txt").write_text(
        datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"), encoding="utf-8"
    )
    try:
        response = requests.post(
            "https://data.flashdata.dev/v1/queries/realtime",
            headers={"X-API-Key": key, "Content-Type": "application/json",
                     "Accept": "application/json"},
            data=body, timeout=120, allow_redirects=False,
        )
    except requests.RequestException:
        raise SystemExit(f"Request interrupted. Keep {out} and check History before retrying.")
    (out / "result.json").write_bytes(response.content)
    (out / "response-headers.txt").write_text(
        "\n".join(f"{k}: {v}" for k, v in response.headers.items()), encoding="utf-8"
    )
    (out / "http-status.txt").write_text(str(response.status_code), encoding="utf-8")
else:
    print(f"Reading saved response from {out}; no API call.")

if not (out / "http-status.txt").exists():
    raise SystemExit("Incomplete attempt. Keep the folder and check History before retrying.")
status = (out / "http-status.txt").read_text().strip()
if status != "200":
    raise SystemExit(f"HTTP {status}: inspect {out}/result.json and response-headers.txt")

data = json.loads((out / "result.json").read_bytes())
if not isinstance(data, dict) or data.get("source") != "google_search" or data.get("status") != "done":
    raise SystemExit("Search did not finish successfully; inspect result.json")
pages = data.get("results")
if not isinstance(pages, list) or any(
    not isinstance(page, dict) or not isinstance(page.get("organic"), list) for page in pages
):
    raise SystemExit("Expected results[].organic arrays; inspect result.json")

sources, seen = [], set()
for page in pages:
    for row in page["organic"]:
        if not isinstance(row, dict):
            raise SystemExit("Expected organic result objects; inspect result.json")
        url = row.get("link")
        if isinstance(url, str) and url.strip() and url not in seen:
            seen.add(url)
            sources.append({field: row.get(field) for field in ("title", "link", "snippet")})
record = {
    "request": json.loads((out / "request.json").read_bytes()),
    "requested_at": (out / "requested-at.txt").read_text().strip(),
    "usage": data.get("usage"), "source_count": len(sources), "result_file": "result.json",
}
for filename, value in (("sources.json", sources), ("record.json", record)):
    (out / filename).write_text(json.dumps(value, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
print(f"Saved {len(sources)} sources to {out}/sources.json")
```

#### Laufen Sie von Web-Suche /

```bash
python search.py search-001
```


### Bash

#### Überprüfen Sie Ihre Tools

```bash
curl --version
jq --version
```

#### web-search/search.sh

```bash
#!/usr/bin/env bash
set -euo pipefail
out="${1:?Usage: bash search.sh OUTPUT_FOLDER}"

if [[ ! -e "$out" ]]; then
  jq -e '.source == "google_search" and (.query | type == "string" and length > 0)' \
    request.json > /dev/null
  if [[ -z "${FLASHDATA_API_KEY:-}" ]]; then
    read -r -s -p "FlashData API key: " FLASHDATA_API_KEY
    printf '\n'
  fi
  : "${FLASHDATA_API_KEY:?An API key is required}"
  mkdir -- "$out"
  cp request.json "$out/request.json"
  date -u +'%Y-%m-%dT%H:%M:%SZ' > "$out/requested-at.txt"
  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 "@$out/request.json" \
    --dump-header "$out/response-headers.txt" --output "$out/result.json" \
    --write-out '%{http_code}' > "$out/http-status.txt" || {
      printf 'Request failed. Keep %s and inspect its saved files before retrying.\n' "$out" >&2
      exit 1
    }
else
  printf 'Reading saved response from %s; no API call.\n' "$out"
fi

if [[ ! -f "$out/http-status.txt" ]] || [[ "$(cat "$out/http-status.txt")" != 200 ]]; then
  printf 'Incomplete or failed attempt. Inspect the saved files and History before retrying.\n' >&2
  exit 1
fi
sources=$(jq -e '
  if .source != "google_search" or .status != "done" or (.results | type) != "array"
  then error("Expected a successful google_search response") else . end
  | [.results[] | if (.organic | type) != "array"
      then error("Expected an organic array") else .organic[] end
      | if type != "object" then error("Expected an organic result object") else . end]
  | reduce .[] as $row ({seen: {}, sources: []};
      if ($row.link | type) != "string" then .
      elif ($row.link | test("\\S")) == false or .seen[$row.link] then .
      else .seen[$row.link] = true | .sources += [$row | {title, link, snippet}] end)
  | .sources' "$out/result.json")
printf '%s\n' "$sources" > "$out/sources.json"
jq --slurpfile request "$out/request.json" --slurpfile sources "$out/sources.json" \
  --arg requested_at "$(tr -d '\r\n' < "$out/requested-at.txt")" \
  '{request: $request[0], requested_at: $requested_at, usage,
    source_count: ($sources[0] | length), result_file: "result.json"}' \
  "$out/result.json" > "$out/record.json"
printf 'Saved %s sources to %s/sources.json\n' "$(jq length "$out/sources.json")" "$out"
```

#### Laufen Sie von Web-Suche /

```bash
bash search.sh search-001
```



<a id="output"></a>

## 3. Lesen Sie die gespeicherten Quellen

Erfolgsdrucke Speicherte N Quellen zu search-001/sources.json. Das Array behält das erste Vorkommen jedes genauen Links in der zurückgegebenen Reihenfolge von Google. Zeilen ohne nutzbaren Link werden weggelassen; fehlende Titel- oder Snippetwerte bleiben null.

record.json enthält die eingereichte Abfrage, die Anforderungszeit und die zurückgegebene Nutzung. Halten Sie result.json als vollständige Antwort. Das Lesen dieser Dateien ist lokal; ein leeres Quellen-Array ist ein gültiges Ergebnis.

### Python

#### Lesen Sie beide Dateien

```bash
python -m json.tool search-001/sources.json
python -m json.tool search-001/record.json
```


### Bash

#### Lesen Sie beide Dateien

```bash
cat search-001/sources.json
cat search-001/record.json
```



<a id="expected"></a>

### Beispielausgabe

Illustrative sources.json; Live-Titel, Links, Snippets und Zählungen variieren. Lesen Sie die verlinkten Seiten, bevor Sie ihre Snippets als Beweis für eine Antwort verwenden.

#### web-search/search-001/sources.json

```json
[
  {
    "title": "Battery recycling research",
    "link": "https://example.org/recycling",
    "snippet": "An example search excerpt."
  }
]
```


<a id="adapt"></a>

## Versuchen Sie eine fokussiertere Abfrage

Um sich auf eine Domäne zu konzentrieren, ändern Sie die Abfrage in request.json in das folgende Beispiel. Wählen Sie einen neuen Ausgabeordner für die neue Abfrage; search-001 bezieht sich immer auf die ursprünglich gespeicherte Anforderung.

### web-search/request.json

```json
{
  "source": "google_search",
  "query": "site:energy.gov battery recycling research",
  "params": {
    "num": 5
  }
}
```

### Python

#### Neue Abfrage · eine weitere abrechenbare Anfrage

```bash
python search.py search-002
```


### Bash

#### Neue Abfrage · eine weitere abrechenbare Anfrage

```bash
bash search.sh search-002
```


- [Suchparameter](https://flashdata.dev/de/docs/sources/google_search/reference.md)
- [Google Search Best Practices](https://flashdata.dev/de/docs/guides/google-search-guide/reference.md)

<a id="recover"></a>

## Wenn die Suche Aufmerksamkeit braucht

| Was passierte | Lösung |
| --- | --- |
| 401 / 403 / 402 | Überprüfen Sie den Schlüssel, google_search Berechtigung und Balance, beziehungsweise. Halten Sie diesen Versuch; Verwenden Sie einen neuen Ausgabeordner nur, wenn Sie bereit sind, erneut zu senden. |
| 429 | Lesen Sie Retry-After in response-headers.txt und warten Sie. Die Skripte werden nicht automatisch wiederholt. |
| Timeout, 5xx oder ein unvollständiger Ordner | Bewahren Sie die gespeicherten Dateien auf und überprüfen Sie History, bevor Sie einen weiteren Versuch erstellen. Das erneute Ausführen des gleichen Ordners führt zu keiner neuen Anforderung. |
| Ungültiges JSON, fehlgeschlagener Status oder unerwartete Felder | Überprüfen Sie result.json vor dem Extrahieren von Quellen. Eine ungültige Antwort darf nicht als leere erfolgreiche Suche behandelt werden. |
| Keine nützlichen Quellen | Überprüfen Sie die gespeicherte Abfrage. Machen Sie es spezifischer oder entfernen Sie einen zu engen Filter und wählen Sie dann einen neuen Ordner für eine andere Abfrage aus. |

### Python

Speichern Sie inspect_search.py in der Web-Suche / bevor Sie es ausführen.

#### web-search/inspect_search.py

```python
from pathlib import Path

for name in ("http-status.txt", "response-headers.txt", "result.json"):
    path = Path("search-001") / name
    print(f"--- {name} ---")
    print(path.read_text(encoding="utf-8", errors="replace") if path.exists() else "Not saved")
```

#### Lokale Kontrolle

```bash
python inspect_search.py
```


### Bash

#### Lokale Kontrolle

```bash
for name in http-status.txt response-headers.txt result.json; do
  printf '\n--- %s ---\n' "$name"
  if [[ -f "search-001/$name" ]]; then cat "search-001/$name"; else printf 'Not saved\n'; fi
done
```


- [Anfrageverlauf](https://flashdata.dev/app/jobs)
- [Fehler und Statuscodes](https://flashdata.dev/de/docs/errors/reference.md)
- [Erstellen Sie eine Suche in eine Anwendung](https://flashdata.dev/de/docs/guides/search-in-an-app/reference.md)
