Przejdź do treści
PL
Uzyskaj klucz API
Przeglądaj dokumentację

Pierwsze kroki

Kontrola konta i zapisane wyniki w SDK

Sprawdź koszt, zachowaj zapis każdej próby i przeczytaj zapisane wyniki bez kolejnego wywołania API.

Na tej stronie

Zanim zaczniesz

Użyj projektu, zainstalowany SDK i FLASHDATA_API_KEY ze swojego szybkiego startu SDK. Wybierz jeden język poniżej. Każdy nowy katalog startowy reprezentuje jeden zamierzony wyszukiwanie; ponowne użycie istniejącego katalogu zatrzymuje się przed złożeniem jakiegokolwiek wniosku.

1. Sprawdź dostęp i bieżące koszty

Zapisz i uruchom czek na SDK. Odczytuje uprawnienia, balans i cena jednego Google Search. Kontynuuj tylko po przejściu kontroli dostępu; te kontrole nie składają płatnego zapytania lub rezerwowych kredytów.

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. Uruchom z nowym katalogiem wyjściowym

Uruchom jeden z tych programów po przejściu czeku. Tworzy katalog przed przesłaniem, zapisuje żądanie, a następnie zapisuje odpowiedź. Zachowanie katalogu na nieudanej pozycji: usunięcie go lub wybranie nowego pozwala na kolejne billable query.

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

Oczekiwane pliki

Sukces drukuje zapisaną ścieżkę wyników i ich wykorzystanie. result.json powinien mieć status: done; Wyniki Google są w results[].organic[]. Pusta tablica organiczna jest poprawna. Zgłoszony błąd API lub transportu jest zapisywany do error.json; intent.json pozostaje oryginalnym rekordem przedskładania.

Udana próba
runs/research-001/
  request.json # Źródło, zapytanie i parametry
  intent.json # Próba rozpoczęcia czasu
  result.json # Pełna odpowiedź, w tym wyniki i wykorzystanie

3. Odczyt zapisanego wyjścia

Przeczytaj result.json na parsowanie, streszczenia i interfejs użytkownika. Polecenia te używają tylko lokalnych plików. Przekierowywanie wyszukiwania z tym samym katalogiem zatrzymuje się przed wywołaniem sieciowym; nie koordynuje on różnych maszyn ani nie odzyskuje utraconej odpowiedzi serwera.

Czytaj lokalnie
cat runs/research-001/result.json

Decyduj, co robić po niepowodzeniu

Co masz?Następna akcja
Istniejący katalog / EEXISTSprawdź jego akta. Ta próba nie przyniosła żadnego nowego pytania.
result.json, status: doneOdczyt i przetwarzanie zapisanej odpowiedzi. Ponowne wykorzystanie go jako potwierdzenia oryginalnej opłaty.
error.json z 401 / 403 / 402Przed planowaniem nowej próby należy naprawić dostęp, uprawnienia źródłowe lub równowagę.
429 / retryAfterPoczekać zgodnie z instrukcją i zmniejszyć dawkę wniosku. Przejrzyj nieudaną próbę przed wybraniem nowego katalogu uruchomień.
Nieznany błąd w przekazywaniu / tylko intencji / zapisuPraca może być już zaakceptowana. Przed wysłaniem kolejnego zapytania należy zachować katalog i sprawdzić History lub znane zadanie ID.

Klienci Async i praca w tle

KoniecznośćStosowanie
Utrzymuje reagującą pętlę zdarzeńKlient Async SDK / oczekuj połączeń. Zapytanie w czasie rzeczywistym nadal kończy się w odpowiedzi HTTP.
Wznowienie po zakończeniu procesu wywoływaniaPrześlij zadanie w tle raz, zapisać jego zdalny ID, a następnie przeczytać status i wyniki.
Uruchom według harmonogramuKorzystaj z dostępu właściciela i trwałych rekordów uruchamiania aplikacji lub istniejącego dziennika operacyjnego CLI.