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

Начало работы

Проверка аккаунта и сохранённые результаты в SDK

Проверяйте стоимость, записывайте каждую попытку и считывайте сохраненные результаты без другого звонка API.

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

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

Используйте проект, установленный SDK и FLASHDATA_API_KEY от вашего быстрого запуска SDK. Выберите один язык ниже. Каждый новый каталог запуска представляет собой один предполагаемый поиск; повторное использование существующего каталога прекращается до того, как сделать какой-либо запрос.

1. Проверить доступ и текущие расходы

Сохраните и запустите чек для вашего SDK. В нем считываются разрешения, баланс и цена одного Google Search. Продолжить только после прохождения проверки доступа; эти чеки не представляют платный запрос или резервные кредиты.

check_access.py
import os
import sys
from flashdata import FlashData, APIError

def main():
    key = os.environ.get("FLASHDATA_API_KEY", "").strip()
    if not key:
        raise RuntimeError("Set FLASHDATA_API_KEY in this terminal.")
    with FlashData(api_key=key) as client:
        access = client.account.access()
        if "google_search" not in access["sources"]:
            raise RuntimeError("This key needs google_search permission.")
        balance = client.account.balance()
        pricing = client.account.pricing(source="google_search", request_count=1)
    price = next((p for p in pricing["prices"]
                  if p["source"] == "google_search" and p["available"]), None)
    cost = price.get("estimatedCredits") if price else None
    if cost is None:
        raise RuntimeError("No current price is available; stop here.")
    available = balance["availableCredits"]
    print(f"Available credits: {available}")
    print(f"One search: {cost} credits")
    if available < cost:
        raise RuntimeError("Insufficient credits. Review Billing.")
    print("Access check passed. No paid query submitted.")

if __name__ == "__main__":
    try:
        main()
    except APIError as error:
        print(f"HTTP {error.status_code}; code={error.code}; "
              f"request_id={error.request_id}; Retry-After={error.retry_after}",
              file=sys.stderr)
        sys.exit(1)
    except Exception as error:
        print(f"{type(error).__name__}: {error}", file=sys.stderr)
        sys.exit(1)
Linux / macOS
.venv/bin/python check_access.py
Windows PowerShell
.\.venv\Scripts\python.exe check_access.py

2. Запуск с новым каталогом вывода

Запустите одну из этих программ после прохождения проверки. Он создает каталог перед отправкой, записывает запрос, а затем сохраняет ответ. Держите каталог на отказе: удаление его или выбор нового позволяет другой оплачиваемый запрос.

archive_search.py
import json
import os
import sys
from datetime import datetime, timezone
from pathlib import Path
from flashdata import FlashData, APIError, SubmissionUnknownError

def main():
    key = os.environ.get("FLASHDATA_API_KEY", "").strip()
    if not key:
        raise RuntimeError("Set FLASHDATA_API_KEY before running.")
    directory = Path(sys.argv[1] if len(sys.argv) > 1 else "runs/research-001")
    directory.mkdir(mode=0o700, parents=True, exist_ok=False)

    def save(name, value):
        with (directory / name).open("x", encoding="utf-8") as output:
            json.dump(value, output, ensure_ascii=False, indent=2)

    request = {"source": "google_search", "query": "battery recycling research",
               "params": {"num": 5}}
    save("request.json", request)
    save("intent.json", {"state": "dispatching",
                         "startedAt": datetime.now(timezone.utc).isoformat()})
    try:
        with FlashData(api_key=key) as client:
            response = client.google.search(request["query"], **request["params"])
    except (APIError, SubmissionUnknownError) as error:
        detail = {"kind": type(error).__name__}
        if isinstance(error, APIError):
            detail.update(code=error.code, httpStatus=error.status_code,
                          requestId=error.request_id, retryAfter=error.retry_after)
        save("error.json", detail)
        raise RuntimeError("Inspect the saved attempt and History before retrying.") from None
    save("result.json", response)
    if response.get("status") != "done":
        raise RuntimeError("Response saved; inspect its status before proceeding.")
    print("Saved:", directory / "result.json")
    print("Usage:", response.get("usage"))

if __name__ == "__main__":
    try:
        main()
    except Exception as error:
        print(f"{type(error).__name__}: {error}", file=sys.stderr)
        sys.exit(1)
Linux / macOS
.venv/bin/python archive_search.py runs/research-001
Windows PowerShell
.\.venv\Scripts\python.exe archive_search.py runs/research-001

Ожидаемые файлы

Успех печатает сохраненный путь результата и использование. result.json должен иметь status: done; Результаты Google находятся в results[].organic[]. Пустой органический массив действителен. Зарегистрированная ошибка API или транспортная ошибка сохраняется в error.json; intent.json остается первоначальной записью перед отправкой.

Успешная попытка
runs/research-001/
  request.json # Источник, запрос и параметры
  intent.json # Время начала попытки
  result.json # Полный ответ, включая результаты и использование

3. Читать сэкономленный выход

Прочитайте result.json для анализа, резюме и работы с пользовательским интерфейсом. Эти команды используют только локальные файлы. Перезапуск поиска с одним и тем же каталогом прекращается перед сетевым вызовом; он не координирует различные машины или не восстанавливает потерянный ответ сервера.

Читать локально
cat runs/research-001/result.json

Решите, что делать после неудачи

Что у тебя естьСледующее действие
Существующий каталог / EEXISTПроверьте его файлы. Никаких новых запросов с этой попытки не поступало.
result.json, status: doneПрочитайте и обработайте сохраненный ответ. Повторно использовать его в качестве квитанции о первоначальном взносе.
error.json с 401 / 403 / 402Исправьте доступ, разрешение источника или баланс перед планированием новой попытки.
429 / retryAfterПодождите, как указано, и уменьшите ставку запроса. Просмотрите неудачную попытку, прежде чем выбрать новый каталог запуска.
Неизвестная отправка / намерение / провал записиРабота может быть уже принята. Держите каталог и проверьте History или известную работу ID перед отправкой другого запроса.

Клиенты Async и базовые рабочие места

нуждаИспользовать
Держите цикл событий отзывчивымКлиент SDK / ждите звонков. Запрос в реальном времени все еще завершается в ответе HTTP.
Резюме после выхода процесса вызоваОтправьте фоновую работу один раз, сохраните ее удаленный ID, а затем прочитайте статус и результаты.
Беги по расписаниюИспользуйте доступ владельца и записи запуска прочного приложения или существующий журнал запуска CLI.