调度服务接口

1. 前言

调度接口是 HTTPDNS 高可用架构的核心组件，负责根据客户端地理位置和网络状况，智能分配最优的解析服务节点。通过调度接口，客户端可以获取就近、健康的服务 IP 列表，实现高性能的域名解析服务。

以下将详细介绍调度接口的使用方法，包括接口形式、参数配置、安全机制和响应处理，主要内容为：

• 接口形式：介绍调度接口的基本形式和 URL 构造方法

• 参数说明：详细说明调度接口的参数配置，包括必选参数和可选参数

• 请求加签：阐述请求签名机制，提升调度请求的安全性

• API响应说明：说明 API 响应格式和错误处理机制

• 服务 IP 更新机制：提供服务 IP 更新策略和最佳实践建议

2. 接口形式

调度接口支持通过 HTTP 或 HTTPS 进行访问，接口形式如下：

• 服务 URL：http(s)://{启动接入点}/{account_id}/ss? + {请求参数}

• 请求方式：GET

3. 参数说明

调度接口通过请求参数控制调度策略和安全机制。您可以灵活设置参数，实现基础调度、签名验证等功能。

3.1 参数列表

3.2 请求参数示例

• 指定区域调度请求

GET https://{启动IP}/{account_id}/ss?region=cn&n=abcdef2345&t=1632912372&s=de7be63a9f19cf11e9d455d7d4f23cb4 HTTP/1.1

• 按照客户端就近调度请求

GET https://{启动IP}/{account_id}/ss?region=global&n=abcdef2345&t=1632912372&s=de7be63a9f19cf11e9d455d7d4f23cb4 HTTP/1.1

4. 请求签名（可选）

为提高调度请求的安全性，建议启用请求签名功能。签名机制可以防止请求被篡改。

4.1 签名算法

• 算法：HMAC-MD5

• 密钥：加签密钥，可以在开发配置获取

• 输入：按照 {n}-{secret}-{t} 格式构造的字符串

• 输出：32 位小写十六进制字符串

4.2 签名步骤

1. 生成随机数 n：16 进制字符串，长度 8-16 位

2. 获取有效时间戳 t：当前时间 + 有效时间（秒），有效时间建议 30-300 秒

3. 构造签名字符串：按照 {n}-{secret}-{t} 格式拼接

4. 计算签名：使用 HMAC-MD5 算法计算签名值

4.3 签名示例

假设：

• 随机数 n = abcdef2345

• SecretKey = 123456

• 时间戳 t = 1632912372

• 区域 region = cn

签名计算过程：

签名字符串 = "abcdef2345-123456-1632912372"
s = HMAC-MD5("123456", "abcdef2345-123456-1632912372")
  = "de7be63a9f19cf11e9d455d7d4f23cb4"

最终请求：

GET https://{启动IP}/{account_id}/ss?region=cn&n=abcdef2345&t=1632912372&s=de7be63a9f19cf11e9d455d7d4f23cb4 HTTP/1.1

5. API 响应说明

调度接口返回的响应包含服务 IP 列表和相关元数据，下面将详细介绍成功响应的数据结构、字段含义以及各种错误情况的处理方法。

5.1 响应格式

请求成功时，HTTP 响应状态码为 200，响应结果用 JSON 格式表示：

{
  "service_ip": [
    "203.107.1.xx",
    "106.xxx.1.xx"
  ],
  "service_ipv6": [
    "64:ff9b::xxx:121",
    "64:ff9b::xxx:122"
  ]
}

5.2 响应字段说明

5.3 错误响应

请求失败时，HTTP 响应状态码为 4xx/5xx，响应结果用 JSON 格式表示：

{
  "code": "MissingArgument"
}

常见错误码：

6. 总结

本文详细介绍了 HTTPDNS 调度接口的使用方法和技术细节，包括接口形式、参数配置、安全机制和响应处理等关键环节。通过调度接口，开发者可以获取最优的解析服务 IP 列表。在获取解析服务 IP 列表后，即可进行具体的域名解析操作， 参考域名解析接口。