Pular para o conteúdo
PT
Obter chave API
Explorar documentação

Primeiros passos

Verificações de conta e resultados salvos com SDKs

Verifique o custo, mantenha um registro de cada tentativa e leia os resultados salvos sem outra chamada API.

Nesta página

Antes de começar

Use o projeto, instalado SDK e FLASHDATA_API_KEY de seu início rápido SDK. Escolha uma língua abaixo. Cada novo diretório de execução representa uma busca pretendida, reutilizando um diretório existente para antes de fazer qualquer pedido.

1. Verifique o acesso e o custo atual

Salve e execute a verificação para o seu SDK. Lê permissões, equilíbrio e o preço de um Google Search. Continue apenas após o controle de acesso passado, esses verificações não enviam uma consulta paga ou reserva de créditos.

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. Executar com um novo diretório de saída

Execute um desses programas depois que o verificação passar. Ele cria o diretório antes de enviar, registra o pedido, e então salva a resposta. Mantenha o diretório em falhas: deletá-lo ou escolher um novo permite outra consulta de faturamento.

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

Arquivos esperados

result.json deve ter status: done; Os resultados do Google estão em results[].organic[]. Uma matriz orgânica vazia é válida. API ou erro de transporte é salvo para error.json; intent.json continua sendo o registro original antes da submissão.

Tentativa bem sucedida
runs/research-001/
  request.json # Fonte, consulta e parâmetros
  intent.json # Tentativa de início
  result.json     Resposta completa, incluindo resultados e uso

3. Leia o resultado salvo

Leia result.json para análise, resumos e trabalho de UI. Esses comandos usam apenas arquivos locais. Repetindo a busca com o mesmo diretório para antes de uma chamada de rede, não coordena máquinas diferentes ou recupera uma resposta perdida do servidor.

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

Decida o que fazer depois de um fracasso

O que você temPróxima ação
Diretório existente / EEXISTInspecione seus arquivos. Nenhuma nova pergunta foi enviada por esta tentativa.
result.json status: doneLeia e processe a resposta salva. Reutilize seu uso como um recibo da acusação original.
error.json com 401 / 403 / 402Conserte acesso, permissões de fonte ou equilíbrio antes de planejar uma nova tentativa.
429 / retryAfterEspere como instruído e reduza a taxa de solicitação. Reveja a tentativa falhada antes de selecionar um novo diretório de execução.
Submissão desconhecida, intenção apenas, falha de escritaO trabalho já pode ser aceito. Mantenha o diretório e inspecione History ou um trabalho conhecido ID antes de enviar outra consulta.

Async clientes e trabalhos de fundo

NecessidadeUse
Mantenha um loop de eventos respondendoO SDK é um cliente sincronizado / espera ligações. Uma consulta em tempo real ainda completa em sua resposta HTTP.
Retomar após o processo de chamada sairEnvie um trabalho de fundo uma vez, salve seu ID remoto, então leia o status e os resultados.
Corra em um horárioUse o acesso do proprietário e execute registros de aplicativos duráveis, ou o CLI existente.