公云（3322）动态域名更新API

通过公云API，您可以很容易开发出动态域名客户端，或者将动态域名功能集成到自己的设备中。

任何公云的账户，都可以使用动态域名API，如果您还没有注册公云，请点此注册。

介绍

• Client的请求应该使用HTTP/1.0以上协议，Server的响应一定为HTTP/1.0
• Client 和 Server,通过 HTTP GET 或 HTTP POST 请求进行交互。
• 需要事务处理，Client发送完整的请求，并且解析服务器端的相应，保证域名更新的成功。
• 如果请求失败，则需要延时一段时间（推荐1分钟）进行重试，直到域名更新成功。
• 更新请求的触发，有两种方式：

事件驱动，客户端侦听系统的IP请求变化事件，一旦改变了IP，立即发起更新请求，推荐这种方式，更新没有延时。

定时更新，每隔一定时间，发起更新请求，注意两次间隔时间不能短于1分钟（收费用户不能短于15秒），如果连续3次以上频繁请求，该域名会被系统自动封堵，返回 abuse 代码。

• IP的变化检测，可以采用 web 方式进行检测，客户端可以访问 http://ip.3322.net 获取自己的IP，两次请求返回的IP变化了，就发起更新请求。注意访问 http://ip.3322.net 的两次间隔时间不能短于1分钟，如果连续3次以上频繁请求，该IP会被系统自动封堵
• 使用HTTP验证作为API的用户身份验证方式。
• User-Agent, 代表客户端名称、版本，需要根据设备类型、名称、特征进行自定义，一般包括设备的厂家、型号、firmware版本号。请不要使用示范中的名称，否则可能被封堵。

动态域名更新接口

接口地址

API URL：http://members.3322.net/dyndns/update

HTTP请求

GET /dyndns/update?hostname=yourhost.ourdomain.ext&myip=ipaddress&wildcard=OFF&mx=mail.exchanger.ext&backmx=NO&offline=NO HTTP/1.1
    Host: members.3322.net
    Authorization: Basic username:password
    User-Agent: myclient/1.0 me@null.net

参数说明

参数	说明
username:password	该参数必选, 用户名和密码用来进行身份认证，必须使用 base64进行编码
hostname=host.3322.org	该参数必选, 需要更新的域名
myip=ipaddr	该参数可选, 域名对应的IP。如果不指定，则服务器将选择最佳的IP(一些Proxy会传递客户端的IP, 这会被服务器检测到)。如果传递的地址格式错误，则忽略这个参数，而用服务器检测 到的IP。
wildcard=ON|OFF	该参数可选, 该参数可选，是否支持泛域名(通配符)，缺省为OFF。ON意为着 *.host.3322.org等同于host.3322.org
mx=mailexchanger	该参数可选, 指明Mail eXchanger。必须能够解析到一个IP，否则被忽略。如果不提供该参数或者 不能解析到一个IP，mx记录会被删除。
backmx=YES|NO	该参数可选, 指明前面的mx参数会被设置成备份邮件服务器，即邮件会首先发送到你的机器上，如果 不成功，才会发送到备份邮件服务器上。
offline=YES|NO Optional: Yes	该参数可选, 使域名暂时失效。

HTTP状态返回码

HTTP状态返回码为200、4XX、5XX，其中4XX表示认证错误，500表示服务器内部出错，200表示正常请求。但是动态域名客户端 请忽略HTTP返回码，而是对下面的返回值进行解析。比如返回值“interror”表示内部出错，这时对应的HTTP状态返回码是500。

返回值

更新成功

参数	说明
good	成功，IP地址已经成功更新，good 后面会跟着所更新的IP地址
nochg	成功，IP地址和上次请求没有变化, nochg 后面会跟着所请求的IP地址

更新出错

参数	说明
badauth	身份认证出错，请检查用户名和密码, 或者编码方式出错。
badsys	该域名不是动态域名，可能是其他类型的域名（智能域名、静态域名、域名转向、子域名）。
badagent	由于发送大量垃圾数据，客户端名称被系统封杀。

参数出错

参数	说明
notfqdn	没有提供域名参数，必须提供一个在公云注册的动态域名域名。
nohost	域名不存在，请检查域名是否填写正确。
!donator	必须是收费用户，才能使用 offline 离线功能。
!yours	该域名存在，但是不是该用户所有。
!active	该域名被系统关闭，请联系公云客服人员。
abuse	该域名由于段时间大量发送更新请求，被系统禁止，请联系公云客服人员。

服务器出错

参数	说明
dnserr	DNS 服务器更新失败。
interror	服务器内部严重错误，比如数据库出错或者DNS服务器出错。

获取IP接口

客户端可以通过该接口获取自己的IP，用于客户端检测IP的变化。

注意访问 http://ip.3322.net 的两次间隔时间不能短于1分钟，如果连续3次以上频繁请求，该IP会被系统自动封堵

接口地址

API URL	参数说明	返回值
http://ip.3322.net	无	客户端的IP地址

常见问题

• 没有对请求做事务处理，没有检查服务器的返回值，没有判断域名更新是否成功
• 更新失败以后，没有记录日志，没有进行延时、重试的过程
• 请求过于频繁，导致域名被服务器封杀
• 客户端使用实例的名字，没有根据自己设备的类型、名称、特征进行自定义

设备认证

公云(3322)动态域名更新API简单易用，方便了开发者和集成商开发自己的客户端，给设备增加动态域名功能。

但是如果对客户端的理解不深入，会产生一些错误或者更新失败，导致动态域名更新失败，用户无法通过域名访问设备。

公云为了规范域名的更新流程，保障设备的正常工作，对市场上使用公云动态域名更新API的设备进行认证：

• 由公云的工程师，对设备进行认真，全面的测试，保证设备能够在各种网络条件、各种异常条件下正常更新域名
• 提供认证的设备清单，推荐公云的广大用户选用

设备认证的具体方法，请参见设备认证