Aller au contenu
FR
Obtenir une clé API
Parcourir la documentation

Premiers pas

SDK : vérifications du compte et résultats enregistrés

Vérifiez le coût, conservez un enregistrement de chaque tentative et relisez les résultats enregistrés sans nouvel appel API.

Sur cette page

Avant de commencer

Réutilisez le projet, le SDK installé et FLASHDATA_API_KEY du guide de démarrage de votre SDK. Choisissez un langage ci-dessous. Chaque nouveau répertoire d’exécution représente une recherche prévue ; si le répertoire existe déjà, le programme s’arrête avant toute requête.

1. Vérifier l’accès et le coût actuel

Enregistrez et exécutez la vérification correspondant à votre SDK. Elle lit les permissions, le solde et le tarif d’une recherche Google Search. Continuez uniquement après le message Access check passed ; ces vérifications ne soumettent aucune requête payante et ne réservent aucun crédit.

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. Exécuter avec un nouveau répertoire de sortie

Exécutez l’un de ces programmes après une vérification réussie. Il crée le répertoire avant la soumission, enregistre la requête, puis la réponse. Conservez le répertoire en cas d’échec : le supprimer ou en choisir un autre permet de soumettre une nouvelle requête facturable.

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

Fichiers attendus

En cas de réussite, le programme affiche le chemin du résultat enregistré et la consommation. result.json doit contenir status: done ; les résultats Google se trouvent dans results[].organic[]. Un tableau organic vide est valide. Toute erreur API ou de transport signalée est enregistrée dans error.json ; intent.json conserve l’enregistrement d’origine effectué avant la soumission.

Tentative réussie
runs/research-001/
  request.json   # Source, requête et paramètres
  intent.json    # Heure de début de la tentative
  result.json    # Réponse complète, résultats et consommation inclus

3. Lire le résultat enregistré

Lisez result.json pour analyser les données, rédiger des résumés ou construire votre interface. Ces commandes utilisent uniquement les fichiers locaux. Relancer la recherche avec le même répertoire arrête le programme avant tout appel réseau ; ce mécanisme ne coordonne pas plusieurs machines et ne récupère pas une réponse serveur perdue.

Lire localement
cat runs/research-001/result.json

Choisir la suite après un échec

SituationAction suivante
Répertoire existant / EEXISTInspectez ses fichiers. Cette tentative n’a envoyé aucune nouvelle requête.
result.json, status: doneLisez et traitez la réponse enregistrée. Son champ usage sert de reçu de la facturation initiale.
error.json avec 401 / 403 / 402Corrigez l’accès, les permissions des sources ou le solde avant de prévoir une nouvelle tentative.
429 / retryAfterRespectez le délai indiqué et réduisez la fréquence des requêtes. Examinez la tentative en échec avant de choisir un nouveau répertoire d’exécution.
Soumission incertaine / intention seule / échec d’écritureLa tâche a peut-être déjà été acceptée. Conservez le répertoire et consultez History ou l’identifiant d’une tâche connue avant d’envoyer une nouvelle requête.

Clients asynchrones et tâches en arrière-plan

BesoinSolution
Garder une boucle d’événements réactiveUtilisez le client asynchrone du SDK et les appels await. Une requête realtime renvoie toujours son résultat dans sa réponse HTTP.
Reprendre après l’arrêt du processus appelantSoumettez une seule fois une tâche en arrière-plan, enregistrez son identifiant distant, puis lisez son état et ses résultats.
Exécuter à intervalles réguliersUtilisez un accès propriétaire et des enregistrements d’exécution durables dans votre application, ou le journal d’exécution existant de la CLI.