# 完成第一次 API 调用

以天气接口为例，配置凭据、发送请求，并分别检查 HTTP 状态和业务响应。

## 核心步骤

- 在详情页核对路径、必填参数与权限。
- 在后端设置 GUGUDATA_APPKEY 环境变量。
- 运行请求并同时校验 HTTP 与业务状态。

## 适用场景与准备

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

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

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

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

```bash
export GUGUDATA_APPKEY='YOUR_APPKEY'
```

## 第二步：发送最小请求

```bash
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 层请求成功，但不代表接口业务成功；其他接口的成功业务状态可能不同。

```python
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；参数错误先检查请求方式和编码；频率受限先降低并发。权限和参数错误不应靠重试解决。超时意味着结果未知，不代表服务器未处理请求，具体策略见 [错误、限流与重试](https://www.gugudata.com/developers/errors-and-retries)。

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