Saltar al contenido
ES
Obtener clave API
Explorar documentación

Primeros pasos

Consulta tu cuenta y reutiliza resultados con el SDK

Comprueba el coste, conserva un registro de cada intento y lee los resultados guardados sin otra llamada a la API.

En esta página

Antes de empezar

Utilice el proyecto, instalado SDK y FLASHDATA_API_KEY desde su inicio rápido SDK. Elija un idioma a continuación. Cada nuevo directorio de ejecución representa una búsqueda prevista; reutilizando un directorio existente para antes de hacer cualquier solicitud.

1. Compruebe el acceso y el costo actual

Ahorre y ejecute el cheque para su SDK. Lee permisos, saldo y el precio de una búsqueda Google. Continúe sólo después de que se haya aprobado el cheque de acceso; estos cheques no presentan una consulta pagada o créditos de reserva.

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. Corre con un nuevo directorio de salida

Ejecute uno de estos programas después de que el cheque pase. Crea el directorio antes de enviar, registra la solicitud, luego guarda la respuesta. Mantenga el directorio en el fracaso: borrarlo o elegir uno nuevo permite otra consulta 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

Archivos previstos

El éxito imprime la ruta y el uso del resultado guardados. result.json debe tener status: done; Google los resultados están en results[].organic[]. Una matriz orgánica vacía es válida. Un reportado API o error de transporte se guarda en error.json; intent.json sigue siendo el registro de pre-submission original.

Un intento exitoso
run/research-001/
  request.json Fuente, consulta y parámetros
  intent.json # Intento comenzar el tiempo
  result.json # Respuesta completa, incluyendo resultados y uso

3. Lea la salida guardada

Lea result.json para el análisis, resúmenes y trabajo UI. Estos comandos utilizan sólo archivos locales. Reaccionar la búsqueda con el mismo directorio se detiene antes de una llamada de red; no coordina diferentes máquinas o recupera una respuesta del servidor perdido.

Lea localmente
cat runs/research-001/result.json

Decidir qué hacer después de un fracaso

Lo que tienesSiguiente acción
Directorio existente / EEXISTInspeccione sus archivos. No se envió ninguna nueva consulta por este intento.
result.json, status: doneLeer y procesar la respuesta guardada. Reutilizar su uso como un recibo de la carga original.
error.json con 401 / 403 / 402Fijar el acceso, los permisos de origen o el equilibrio antes de planificar un nuevo intento.
429 / retryAfterEspere como se instruyó y reducir la tasa de solicitud. Revise el intento fallido antes de seleccionar un nuevo directorio de ejecución.
Sumisión desconocida / intención solamente / error de escrituraEl trabajo ya puede ser aceptado. Mantenga el directorio e inspeccione Historia o un trabajo conocido ID antes de enviar otra consulta.

Async clients and background jobs

NecesidadUso
Mantener un bucle de evento receptivoEl cliente async de SDK / espera llamadas. Una consulta en tiempo real todavía completa en su respuesta HTTP.
Reanuda después de las salidas del proceso de llamadaPresentar un trabajo de fondo una vez, guardar su ID remoto, luego leer estado y resultados.
Ejecutar en un horarioUtilice el acceso del propietario y los registros de ejecución de aplicaciones duraderas, o la revista de ejecución existente de CLI.