文档

服务IP调度接口

更新时间:

针对无法使用SDK的场景,介绍如何使用服务IP调度接口。

接口能力和应用场景

重要

HTTPDNS官方SDK中已集成本接口,此文档主要针对无法使用SDK的场景。

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

  1. 获取服务IP列表,允许客户端动态获取服务节点IP。

  2. 列出当前所有已启用的域名列表,允许客户端避免无效解析请求。

  3. 当某服务节点异常后,允许动态获取最新的服务接入点列表。

术语介绍

调度服务:即本服务调度接口,根据来源IP,返回服务IP及其他服务调度信息。

解析服务:即HTTPDNS解析服务接口,请参见解析服务接口文档。

启动IP:用于首次启动或灾难场景下调用服务调度接口,此IP不提供解析服务。

服务IP:常规场景下用于调用调度服务和解析服务的IP地址。

接入方式

服务IP调度接口-new

  1. 提工单或加入钉钉群35248489申请启动IP列表。

    说明

    启动IP应写死在App中,为保证服务可用性,我们会提供多个启动IP供您接入。

  2. 使用启动IP调用调度服务获取服务IP列表。

    说明

    • 调度服务支持HTTP/HTTPS方式访问,请参考下文中验证服务器身份章节来验证服务器身份。

    • 启动IP仅可用于调用调度服务,不提供解析服务。

  3. 使用服务IP调用解析服务。

  4. 必须周期性的使用服务IP调用调度服务来更新服务IP列表,保持服务IP列表的有效性。

    说明

    服务IP同时提供调度服务和解析服务。

    • 建议App冷启动时进行更新

    • 建议切换网络环境时进行更新

    • 建议每8小时至少更新一次

  5. 当所有服务IP不可用时,降级使用启动IP来调用调度服务,获取可用的服务IP列表。

  6. 当所有启动IP不可用时,请采用指数退避的方式来进行重试。

    重要

    解析服务返回的服务IP列表,不保证长期有效,可能随时会发生改变,

接口访问方式

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

重要

{account_id}是您HTTPDNS服务的专属ID,您可以在HTTPDNS控制台上获取。

请求方式:GET

可选参数说明一

说明

可选参数用于支持调度异常的排查,详情请参考如何使用“会话追踪方案”排查解析异常

名称

是否必须

描述

sid

可选

sessionId,[a-zA-Z0-9]{12},在app启动时生成,用于标记一次独立的app生命周期。

net

可选

5g|4g|3g|2g|wifi|unknown,用于标记请求发起时刻os层提供的网络情况。

bssid

可选

WiFi环境的bssid,用于标记不同的WiFi网络。

可选参数说明二

说明

可选参数用于海外节点选择。

名称

是否必须

描述

n

可选

待加签的随机数,要求是16进制数,字符长度最小为8,最长为16,例如:abcdef2345。

t

可选

1970年1月1日以来的秒数(整型正数,固定长度10)。

重要

客户端和服务器时间偏移需小于150秒,您可以根据响应头中的Date进行校准。

s

可选

用secret(在HTTPDNS控制台查看)生成的签名, 计算方式:s=md5sum(n-secret-t), 如:n=abcdef2345,secret=123456,t=1632912372, 则对字符串 "abcdef2345-123456-1632912372"对应的ASCII码进行加签,结果为: de7be63a9f19cf11e9d455d7d4f23cb4。

region

可选

海外服务区域选择,当前仅支持hk(中国香港节点)和sg(新加坡节点),填写后返回当地的服务节点;缺省时,使用中国内地服务节点。

验证服务器身份:

  • 当您使用HTTPS请求调度服务时,我们会提供主机名为203.107.1.1的有效证书(无论使用哪个IP请求),请据此验证服务器身份;这需要您手动忽略证书错误中的主机名错误,并手动验证证书所持主机名为203.107.1.1。

  • 当您使用HTTP请求调度服务时,由于缺少TLS的安全机制,我们会基于以下参数对响应内容做签名,并将签名值放置在响应头的X-Checksum-HmacMD字段中。

调用示例

  • 假设secretKey为:IAmASecret,随机数n为:2EUenAaShVfy,当前时间戳1568802250, 响应内容为:{"service_ip":["203.107.1.33"],"service_ipv6":["64:ff9b::cb6b:121"]}

  • 请求url:http://{启动IP_或_服务IP}/{account_id}/ss?n=2EUenAaShVfy&t=1568802250

  • sign = hmacMD5("IAmASecret", "2EUenAaShVfy-{"service_ip":["203.107.1.33"],"service_ipv6":["64:ff9b::cb6b:121"]}-1568802250") = 3C74A498A00EEE6C5E7C599B3B882658

  • 则响应头中应包含:X-Checksum-HmacMD5:3C74A498A00EEE6C5E7C599B3B882658

说明

secretKey可在“HTTPDNS控制台>鉴权配置>鉴权secretkey”查看。

返回示例

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

{
  "service_ip": [
    "203.107.1.33"
  ],
  "service_ipv6": [
    "64:ff9b::cb6b:121"
  ]
}

字段

说明

service_ip

IPv4服务IP列表,请通过此IP列表接入IPv4链路服务。

service_ipv6

IPv6服务IP列表,请通过此IP列表接入IPv6链路服务。

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

{
  "code": "MissingArgument"
}

状态码说明

错误码

HTTP状态码

描述

MissingArgument

400

缺少必要参数

TimeOutOfSync

400

时间偏差过大,请根据响应头中的Date进行校准

InvalidNonce

400

随机数不合要求

InvalidTimestamp

403

时间戳格式不正确

AccountNotExists

403

账户不存在或被禁用,或尚未在HTTPDNS控制台添加过域名

InternalError

500

服务端内部错误

  • 本页导读 (0)
文档反馈