Перейти к содержимому
RU
Ключ API
Обзор документации

Примеры

Поиск в Интернете и сохранение исходных ссылок

Запустите один поиск Google. Сохраняйте уникальные исходные ссылки в порядке результата вместе с запросом и использованием.

На этой странице

Прежде чем начать

Используйте ключ с разрешением google_search и доступными кредитами. Выберите Python 3.10+ с запросами или Bash с cURL 7.76+ и jq. На Windows используйте Git Bash для пути Bash.

1. Подготовьте запрос

Создайте папку веб-поиска. Сохраните request.json там, а затем откройте терминал в этой папке. В этом примере запрашивается до пяти органических результатов; один новый запуск представляет один платежный запрос.

web-search/request.json
{
  "source": "google_search",
  "query": "battery recycling research",
  "params": {
    "num": 5
  }
}

2. Сохранить и запустить сценарий

Выберите одну версию и сохраните ее сценарий рядом с request.json. Он считывает FLASHDATA_API_KEY или подсказывает ваш ключ без его отображения. Агент должен поставлять переменную окружающей среды из своего секретного магазина.

Запустите с помощью Search-001 в качестве выходной папки. Сценарий сохраняет точный запрос перед его отправкой. Запуск снова с той же папкой считывает сохраненный ответ без вызова API.

Установка в среде Python
python -m pip install requests
web-search/search.py
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")
Бег от веб-поиска /
python search.py search-001

3. Читайте сохраненные источники

Успешная печать сохраненных источников N для search-001/sources.json. Массив сохраняет первое появление каждой точной ссылки в возвращенном заказе Google. Ряды без полезной ссылки опущены; отсутствующие значения заголовка или фрагмента остаются null.

record.json содержит отправленный запрос, время запроса и возвращенное использование. Держите result.json как полный ответ. Чтение этих файлов является локальным; массив пустых источников является действительным результатом.

Прочитайте оба файла
python -m json.tool search-001/sources.json
python -m json.tool search-001/record.json

Примерный выход

Иллюстративный sources.json; живые заголовки, ссылки, фрагменты и подсчеты варьируются. Прочитайте связанные страницы, прежде чем использовать их фрагменты в качестве доказательства ответа.

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

Попробуйте более сфокусированный запрос

Чтобы сосредоточиться на домене, измените запрос в request.json на пример ниже. Выберите новую выходную папку для нового запроса; Search-001 всегда ссылается на свой первоначальный сохраненный запрос.

web-search/request.json
{
  "source": "google_search",
  "query": "site:energy.gov battery recycling research",
  "params": {
    "num": 5
  }
}
Новый запрос · еще один платежный запрос
python search.py search-002

Если поиск требует внимания

Что случилось?Что делать
401 / 403 / 402Проверьте ключ, разрешение google_search и баланс, соответственно. Сохраните эту попытку; используйте новую папку вывода только тогда, когда вы готовы отправить снова.
429Читайте Retry-After в response-headers.txt и ждите. Сценарии не повторяются автоматически.
Тайм-аут, 5xx или неполная папкаСохраняйте сохраненные файлы и проверяйте History, прежде чем создавать еще одну попытку. Перезагрузка одной и той же папки не делает нового запроса.
Недействительный JSON, неудачный статус или неожиданные поляПроверяйте result.json перед извлечением источников. Недействительный ответ не должен рассматриваться как пустой успешный поиск.
Нет полезных источниковПросмотрите сохраненный запрос. Сделайте его более конкретным или удалите слишком узкий фильтр, затем выберите новую папку для другого запроса.

Сохраните inspect_search.py в веб-поиске / перед запуском.

web-search/inspect_search.py
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")
Проверить локально
python inspect_search.py