HeyRoute

学习目标

通过本教程，你将掌握如何使用 HeyRoute 平台完成以下任务：

• 快速注册并获取 API 密钥，用于身份验证
• 创建并配置一个长任务 API，支持异步处理与结果轮询
• 实现可信转发（Trusted Forwarding），确保请求来源可靠
• 排查常见配置错误，确保服务稳定运行

前置条件

开始操作前，请确保你已具备以下条件：

• 一个可用的电子邮箱地址
• 基本的 HTTP 请求知识（如 GET、POST）
• 能够访问 https://aheapi.com/ 网站

分步操作

步骤 1：注册账号并获取 API 密钥

1. 打开浏览器，访问 https://aheapi.com/。
2. 点击页面右上角的「注册」按钮。
3. 输入你的电子邮箱地址，设置密码（至少 8 位，包含字母和数字），然后点击「提交」。
4. 登录注册时使用的邮箱，查收验证邮件，点击验证链接完成激活。
5. 登录 HeyRoute 控制台，在左侧菜单栏选择「API 密钥」。
6. 点击「生成新密钥」，复制生成的密钥并妥善保存（此密钥仅在生成时显示一次）。

预期结果：你拥有一个格式为 hr_xxxxxxxxxxxxxxxx 的 API 密钥，可用于后续所有 API 调用。

步骤 2：创建并配置长任务 API

长任务适用于需要长时间处理的请求（如文件处理、数据导出），支持异步提交和结果轮询。

1. 在控制台左侧菜单点击「API 管理」→「创建新 API」。
2. 在「API 名称」字段输入你的任务名称，例如 data-export。
3. 在「API 类型」下拉菜单中选择「长任务」。
4. 在「回调 URL」字段输入你的服务端接收结果的地址，例如 https://your-server.com/callback。如果不设置回调，则需手动轮询结果。
5. 在「超时时间」字段设置任务最大执行时间，建议值：300（秒）。
6. 点击「保存」。

注意事项：

• 回调 URL 必须支持 HTTPS，且可被公网访问。
• 超时时间建议不超过 600 秒，否则任务可能被强制终止。

预期结果：系统返回一个 API ID，格式如 api_xxxxxxxx。你可以在「API 列表」中看到该记录。

步骤 3：提交长任务并获取结果

1. 使用以下示例请求提交任务（替换 {API_KEY} 和 {API_ID} 为实际值）：

POST https://aheapi.com/v1/tasks
Headers:
  Authorization: Bearer {API_KEY}
  Content-Type: application/json
Body:
{
  "api_id": "{API_ID}",
  "payload": {
    "file_url": "https://example.com/large-file.csv"
  }
}

2. 系统返回一个任务 ID，例如 task_xxxxxxxx，以及状态 pending。
3. 等待任务处理完成后，执行以下任一操作：

• 如果设置了回调 URL，你的服务端将收到 POST 请求，包含结果数据。
• 如果未设置回调，使用以下请求轮询结果：

GET https://aheapi.com/v1/tasks/{task_id}
Headers:
  Authorization: Bearer {API_KEY}

4. 当返回的 status 字段为 completed 时，result 字段包含最终数据。

常见问题：

• 如果任务状态长时间为 pending，检查超时时间是否过短，或回调 URL 是否可达。
• 如果返回 401 Unauthorized，请确认 API 密钥未过期且已正确写入请求头。

步骤 4：配置可信转发

可信转发确保只有经过授权的来源可以调用你的 API，防止恶意请求。

1. 在控制台左侧菜单点击「API 管理」→ 选择你刚创建的 API。
2. 在「安全设置」区域，找到「可信转发」选项。
3. 点击「添加来源」，输入允许的 IP 地址或 CIDR 范围，例如 203.0.113.0/24。
4. 点击「保存」。

预期结果：只有来自指定 IP 范围的请求才会被处理，其他来源的请求返回 403 Forbidden。

失败排查：

• 如果你需要允许所有来源，可输入 0.0.0.0/0，但建议仅用于测试环境。
• 如果配置后仍无法访问，检查 IP 地址是否匹配，或是否误写了 CIDR 格式（如 192.168.1.1/32 是单个 IP）。

常见问题与边界情况

下一步

• 尝试创建多个 API，分别配置不同的安全策略。
• 在控制台「日志」页面查看所有请求的详细记录，用于调试。
• 如需更高并发或定制化服务，可联系客服升级套餐。