全部产品
云市场

IPv6服务调度接口

更新时间:2019-03-23 14:53:16

1. 接口能力和应用场景

为更好地提供纯IPv6服务链路,我们采用动态接口的方式来提供“IPv6服务IP列表”

本接口根据源IP,返回最优和最新的服务调度信息,并同时提供更多的容灾能力。包括以下能力:

  1. 获取IPv6服务IP列表,允许客户端动态获取服务节点IP
  2. 列出当前所有已启用的域名列表,允许客户端避免无效解析请求
  3. 当某服务节点异常后,允许动态获取最新的服务接入点列表


2. 术语介绍

  1. 调度服务: 即本服务调度接口:根据来源IP,返回服务IP及其他服务调度信息
  2. 解析服务: 即HTTPDNS解析服务接口,请参见 [解析服务接口文档]
  3. 启动IP: 用于首次启动或灾难场景下调用服务调度接口,此IP不提供 解析服务
  4. 服务IP: 常规场景下用于调用 调度服务解析服务 的IP地址


3. 接入方式

接入逻辑解释

  1. 提交工单申请启动IP列表
    • 启动IP应写死在app中,为保证服务可用性,我们会提供多个启动IP供您接入
  2. 使用启动IP调用调度服务获取服务IP列表
    • 调度服务仅支持HTTPS方式访问,同时本接口仅会提供203.107.1.1的证书(无论使用哪个IP请求),请据此验证服务器身份
  3. 使用服务IP调用解析服务
  4. 必须周期性使用服务IP调用调度服务来更新服务IP列表,保持服务IP列表的有效性
    • 建议app冷启动时进行更新
    • 建议切换网络环境时进行更新
    • 建议每小时至少更新一次
  5. 当所有服务IP不可用时,降级使用启动IP来调用调度服务,获取可用的服务IP列表
  6. 启动IP不可用时,请采用指数退避的方式来进行重试

注意事项

  1. 启动IP仅可用于调用调度服务,不提供解析服务
    • 为保证服务可用性,我们会提供多个启动IP供您接入
  2. 服务IP同时提供调度服务解析服务
  3. 解析服务返回的服务IP列表及其他调度信息,不保证长期有效,可能随时会发生改变
    • 当所有服务IP不可用时,降级使用启动IP来调用调度服务,获取可用的服务IP列表


4. 接口访问方式

GET https://{启动IP_或_服务IP}/{account_id}/ss

基本请求参数

名称 是否必须 描述
n 必选 随机字符串,[a-zA-Z0-9]{8,16}
t 必选 当前时间戳,和服务器时间偏移应<60秒,否则请根据响应头中的Date进行校准
s 必选 签名字符串,md5sum( {n}-{secret}-{timestamp} ),其中secret可在『控制台-鉴权配置-鉴权secretkey』查看


可选参数

详情请参考 [解析异常排查之 “会话追踪方案”]

名称 是否必须 描述
sid 可选 sessionId,[a-zA-Z0-9]{12},在app启动时生成,用于标记一次独立的app生命周期
net 可选 (4g|3g|2g|wifi|unknown),用于标记请求发起时刻os层提供的网络情况
bssid 可选 wifi环境的bssid,用于标记不同的wifi网络


注意事项

  • URL中的 {account_id} 需要替换为用户的 HTTPDNS Account ID,您可以在 HTTPDNS 控制台上可以获得这个 ID。
  • 本接口可以添加其他参数,是否添加其他参数及参数内容不影响签名的计算。
  • 为保证内容安全,本接口仅支持HTTPS方式访问,同时本接口仅会提供203.107.1.1的证书(无论使用哪个IP请求),请据此验证服务器身份。


5. 调用示例

  • 假设秘钥为:IAmASecret,随机数n为:2EUenAaShVfy,当前时间戳1568802250
  • sign = md5sum(“2EUenAaShVfy-IAmASecret-1568802250”) = 60c71e98b6d7fcbb366243e224eab457
  • 请求URL为:https://{启动IP_或_服务IP}/{account_id}/ss?n=2EUenAaShVfy&t=1568802250&s=2e7fb2947bb101e3b201521e8f82d9bc


6. 接口返回值

请求成功

请求成功时,HTTP响应的状态码为200,响应结果用JSON格式表示,示例如下:

  1. {
  2. "service_ipv6": [
  3. "64:ff9b::cb6b:121"
  4. ],
  5. "enabled_domains": [
  6. "www.aliyun.com"
  7. ]
  8. }

返回字段说明:

名称 描述
service_ipv6 IPv6服务接入点,请通过此IP列表接入服务。
enabled_domains 当前账号启用的域名列表。

请求失败

请求失败时,HTTP响应的状态码为4xx/5xx,同时也返回具体的错误码,响应结果用JSON格式表示。

请求失败的响应示例:

  1. {
  2. "code": "MissingArgument"
  3. }

错误码列表如下:

错误码 HTTP状态码 描述
HttpsRequired 400 请使用HTTPS协议
MissingArgument 400 缺少必要参数
TimeOutOfSync 400 时间偏差过大,请根据响应头中的Date进行校准
InvalidTimestamp 403 时间戳格式不正确
InvalidSignature 403 签名不正确
AccountNotExists 403 账户不存在或被禁用,或尚未在HTTPDNS控制台添加过域名
InternalError 500 服务端内部错误