完成第一次 API 调用

适用场景与准备

适合已经选定接口、希望从后端完成第一次调用的开发者。下面以 全球天气预报信息 为例：接口路径是 /weather/weatherinfo，请求方式为 GET，可使用 location 指定城市，days 指定天数。运行前确认账号已拥有相应权限，并从开发者中心取得该产品的 AppKey。

若只想先理解响应结构，可先使用详情页提供的 Demo 或预览入口。Demo 数据不能用来证明正式账号已开通，也不能代替实时结果。

第一步：在服务端准备凭据

从安全的环境配置或凭据管理工具注入 GUGUDATA_APPKEY。以下命令适用于 Bash / Zsh（macOS、Linux 或 Windows Git Bash），仅展示变量名和占位值；实际部署应由运行环境提供密钥，避免将其保存到脚本或版本库。

export GUGUDATA_APPKEY='YOUR_APPKEY'

第二步：发送最小请求

curl --get 'https://api.gugudata.com/weather/weatherinfo' \
  --header "X-GUGUDATA-APPKEY: ${GUGUDATA_APPKEY}" \
  --data-urlencode 'location=苏州' \
  --data-urlencode 'days=1' \
  --connect-timeout 10 \
  --max-time 30 \
  --output weather-response.json \
  --write-out 'HTTP %{http_code}\n'

--data-urlencode 避免中文和保留字符被错误编码。这里的 30 秒是示例客户端超时，并非接口响应时限承诺；耗时接口应按详情说明设置超时。正式调用可能消耗产品额度。

第三步：检查两层结果

先检查 HTTP 状态，再查看 weather-response.json。天气接口正常业务状态为 DataStatus.StatusCode = 100，业务数据位于 Data。HTTP 200 表示 HTTP 层请求成功，但不代表接口业务成功；其他接口的成功业务状态可能不同。

import json
from pathlib import Path

result = json.loads(Path("weather-response.json").read_text(encoding="utf-8"))
if not isinstance(result, dict):
    raise RuntimeError("响应不是预期的 JSON 对象")
status = result.get("DataStatus")
if not isinstance(status, dict) or str(status.get("StatusCode")) != "100":
    raise RuntimeError("请根据天气接口文档排查业务错误")
if "Data" not in result:
    raise RuntimeError("响应缺少 Data，请检查接口返回结构")
print("业务状态正常，请继续核对 Data 中的城市、日期和所需字段")

核对返回城市、日期和你实际需要的字段，不要只检查字段是否存在。缺失值、空数组和 null 的含义应按该接口说明处理。

失败时从哪里开始

凭据错误先确认是否复制了目标产品的 AppKey；参数错误先检查请求方式和编码；频率受限先降低并发。权限和参数错误不应靠重试解决。超时意味着结果未知，不代表服务器未处理请求，具体策略见 错误、限流与重试。

完成最小调用后，再加入结果映射、有限重试、脱敏日志和测试替身。不要直接把 AppKey 搬进网页或移动客户端。