跳转到正文
中文
获取 API 密钥
浏览文档

开始使用

SDK 账户检查与结果保存

检查成本、记录每次尝试,并读取保存的结果而不再次调用 API。

本页内容

开始前准备

使用 SDK 入门指南中的项目、已安装 SDK 及 FLASHDATA_API_KEY。选择下方一种语言。每个新运行目录代表一次预期搜索;复用现有目录时,在发起请求前停止。

1. 检查权限与当前成本

保存并运行对应 SDK 的检查。它读取权限、余额及一次 Google 搜索的价格。仅在输出 Access check passed 后继续;这些检查不提交付费查询,也不预留 Credits。

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[]。organic 空数组有效。报告的 API 或传输错误保存到 error.json;intent.json 保留提交前的原记录。

成功尝试
runs/research-001/
  request.json   # Source, query and parameters
  intent.json    # Attempt start time
  result.json    # Full response, including results and usage

3. 读取保存的输出

读取 result.json 进行解析、摘要及 UI 开发。这些命令仅读取本地文件。以相同目录重运行搜索会在网络请求前停止;此保护不协调不同机器,也不恢复丢失的服务器响应。

本地读取
cat runs/research-001/result.json

失败后决定下一步

已有信息后续操作
目录已存在 / EEXIST检查其中的文件。此次尝试没有发送新查询。
result.json,status: done读取并处理保存的响应;其中 usage 是原始扣费回执。
error.json 包含 401 / 403 / 402规划新的尝试前,先修复访问、来源权限或余额。
429 / retryAfter按提示等待并降低请求速率。选择新的运行目录前检查失败尝试。
提交结果未知 / 仅有 intent / 写入失败工作可能已被接纳。保留目录并检查历史或已知任务 ID,再决定是否发送新查询。

异步客户端与后台任务

需求方式
保持事件循环可响应SDK 异步客户端 / await 调用。realtime 查询仍在其 HTTP 响应中完成。
调用进程退出后恢复提交一次后台任务,保存远程 ID,再读取状态及结果。
定时运行使用所有者访问及持久应用运行记录,或 CLI 已有运行日志。