这里会显示出您选择的修订版和当前版本之间的差别。
后一修订版 | 前一修订版 上一修订版 Both sides next revision | ||
帮助:api [2011/08/04 21:37] refactor 创建 |
帮助:api [2013/03/04 13:21] refactor [返回值] |
||
---|---|---|---|
行 1: | 行 1: | ||
- | ====== å°è¾£æ¤å¨æååæ´æ°API ====== | + | ====== 公云(3322)动态域名更新API ====== |
- | éè¿å°è¾£æ¤APIï¼æ¨å¯ä»¥å¾å®¹æå¼ååºå¨æåå客æ·ç«¯ï¼æè å°å¨æåååè½éæå°èªå·±ç设å¤ä¸ã | + | 通过公云API,您可以很容易开发出动态域名客户端,或者将动态域名功能集成到自己的设备中。 |
- | ä»»ä½å°è¾£æ¤çè´¦æ·ï¼é½å¯ä»¥ä½¿ç¨å¨æååAPIï¼å¦ææ¨è¿æ²¡ææ³¨åå°è¾£æ¤ï¼è¯·[[http://www.3322.net/accounts/signup/|ç¹æ¤]]注åã | + | 任何公云的账户,都可以使用动态域名API,如果您还没有注册公云,请[[http://www.3322.net/accounts/signup/|点此]]注册。 |
+ | ===== 介绍 ===== | ||
- | ===== ä»ç» ===== | + | * Client的请求应该使用HTTP/1.0以上协议,Server的响应一定为HTTP/1.0 |
- | * Clientç请æ±åºè¯¥ä½¿ç¨HTTP/1.0以ä¸åè®®ï¼Serverçååºä¸å®ä¸ºHTTP/1.0 | + | * Client 和 Server,通过 HTTP GET 或 HTTP POST 请求进行交互。 |
- | * Client å Server,éè¿ HTTP GET æ HTTP POST 请æ±è¿è¡äº¤äºã | + | * 需要事务处理,Client发送完整的请求,并且解析服务器端的相应,保证域名更新的成功。 |
- | * éè¦äºå¡å¤çï¼Clientåé宿´ç请æ±ï¼å¹¶ä¸è§£ææå¡å¨ç«¯çç¸åºï¼ä¿è¯ååæ´æ°çæåã | + | * 如果请求失败,则需要延时一段时间(推荐1分钟)进行重试,直到域名更新成功。 |
- | * å¦æè¯·æ±å¤±è´¥ï¼åéè¦å»¶æ¶ä¸æ®µæ¶é´ï¼æ¨è1åéï¼è¿è¡éè¯ï¼ç´å°ååæ´æ°æåã | + | * 更新请求的触发,有两种方式: |
- | * æ´æ°è¯·æ±ç触åï¼æä¸¤ç§æ¹å¼ï¼ | + | 事件驱动,客户端侦听系统的IP请求变化事件,一旦改变了IP,立即发起更新请求,推荐这种方式,更新没有延时。 |
- | äºä»¶é©±å¨ï¼å®¢æ·ç«¯ä¾¦å¬ç³»ç»çIP请æ±ååäºä»¶ï¼ä¸æ¦æ¹åäºIPï¼ç«å³åèµ·æ´æ°è¯·æ±ï¼æ¨èè¿ç§æ¹å¼ï¼æ´æ°æ²¡æå»¶æ¶ã | + | 定时更新,每隔一定时间,发起更新请求,注意两次间隔时间不能短于1分钟(收费用户不能短于15秒),如果连续3次以上频繁请求,该域名会被系统自动封堵,返回 abuse 代码。 |
- | 宿¶æ´æ°ï¼æ¯éä¸å®æ¶é´ï¼åèµ·æ´æ°è¯·æ±ï¼æ³¨æä¸¤æ¬¡é´éæ¶é´ä¸è½çäº1åéï¼æ¶è´¹ç¨æ·ä¸è½çäº15ç§ï¼ï¼å¦æè¿ç»3次以ä¸é¢ç¹è¯·æ±ï¼è¯¥ååä¼è¢«ç³»ç»èªå¨å°å µï¼è¿å abuse 代ç ã | + | * IP的变化检测,可以采用 web 方式进行检测,客户端可以访问 http://ip.3322.net 获取自己的IP,两次请求返回的IP变化了,就发起更新请求。注意访问 http://ip.3322.net 的两次间隔时间不能短于1分钟,如果连续3次以上频繁请求,该IP会被系统自动封堵 |
- | * IPçå忣æµï¼å¯ä»¥éç¨ web æ¹å¼è¿è¡æ£æµï¼å®¢æ·ç«¯å¯ä»¥è®¿é® http://ip.3322.net è·åèªå·±çIPï¼ä¸¤æ¬¡è¯·æ±è¿åçIPååäºï¼å°±åèµ·æ´æ°è¯·æ±ã注æè®¿é® http://ip.3322.net ç两次é´éæ¶é´ä¸è½çäº1åéï¼å¦æè¿ç»3次以ä¸é¢ç¹è¯·æ±ï¼è¯¥ååä¼è¢«ç³»ç»èªå¨å°å µ | + | * 使用[[http://www.ietf.org/rfc/rfc2617.txt|HTTP]]验证作为API的用户身份验证方式。 |
- | * 使ç¨[[http://www.ietf.org/rfc/rfc2617.txt|HTTP]]éªè¯ä½ä¸ºAPIçç¨æ·èº«ä»½éªè¯æ¹å¼ã | + | * User-Agent, 代表客户端名称、版本,需要根据设备类型、名称、特征进行自定义,一般包括设备的厂家、型号、firmware版本号。请不要使用示范中的名称,否则可能被封堵。 |
- | * User-Agent, 代表客æ·ç«¯åç§°ãçæ¬ï¼éè¦æ ¹æ®è®¾å¤ç±»åãåç§°ãç¹å¾è¿è¡èªå®ä¹ï¼ä¸è¦ä½¿ç¨ç¤ºèä¸çåç§°ï¼å¦åå¯è½è¢«å°å µ | ||
+ | ===== 动态域名更新接口 ===== | ||
- | ===== 卿ååæ´æ°åè®® ===== | + | ==== 接口地址 ==== |
- | ==== HTTPè¯·æ± ==== | + | **API URL** |
+ | |||
+ | <code> | ||
+ | http://members.3322.net/dyndns/update | ||
+ | </code> | ||
+ | |||
+ | **HTTP请求** | ||
<code> | <code> | ||
GET /dyndns/update?hostname=yourhost.ourdomain.ext&myip=ipaddress&wildcard=OFF&mx=mail.exchanger.ext&backmx=NO&offline=NO HTTP/1.1 | 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.org | + | Host: members.3322.net |
Authorization: Basic username:password | Authorization: Basic username:password | ||
User-Agent: myclient/1.0 me@null.net | User-Agent: myclient/1.0 me@null.net | ||
</code> | </code> | ||
- | ==== åæ°è¯´æ ==== | + | ==== 参数说明 ==== |
* username:password | * username:password | ||
- | è¯¥åæ°å¿ é, ç¨æ·ååå¯ç ç¨æ¥è¿è¡èº«ä»½è®¤è¯ï¼å¿ é¡»ä½¿ç¨ base64è¿è¡ç¼ç | + | 该参数必选, 用户名和密码用来进行身份认证,必须使用 base64进行编码 |
* hostname=host.3322.org | * hostname=host.3322.org | ||
- | è¯¥åæ°å¿ é, éè¦æ´æ°çåå | + | 该参数必选, 需要更新的域名 |
* myip=ipaddr | * myip=ipaddr | ||
- | è¯¥åæ°å¯é, åå对åºçIPã妿䏿å®ï¼åæå¡å¨å°éæ©æä½³çIP(ä¸äºProxyä¼ä¼ é客æ·ç«¯çIP, | + | 该参数可选, 域名对应的IP。如果不指定,则服务器将选择最佳的IP(一些Proxy会传递客户端的IP, |
- | è¿ä¼è¢«æå¡å¨æ£æµå°)ãå¦æä¼ éçå°åæ ¼å¼é误ï¼å忽ç¥è¿ä¸ªåæ°ï¼èç¨æå¡å¨æ£æµ | + | 这会被服务器检测到)。如果传递的地址格式错误,则忽略这个参数,而用服务器检测 |
- | å°çIPã | + | 到的IP。 |
* wildcard=ON|OFF | * wildcard=ON|OFF | ||
- | è¯¥åæ°å¯é, è¯¥åæ°å¯éï¼æ¯å¦æ¯ææ³åå(éé 符)ï¼ç¼ºç为OFFãONæä¸ºç *.host.3322.orgçåäºhost.3322.org | + | 该参数可选, 该参数可选,是否支持泛域名(通配符),缺省为OFF。ON意为着 *.host.3322.org等同于host.3322.org |
* mx=mailexchanger | * mx=mailexchanger | ||
- | è¯¥åæ°å¯é, ææMail eXchangerãå¿ é¡»è½å¤è§£æå°ä¸ä¸ªIPï¼å¦å被忽ç¥ã妿䏿ä¾è¯¥åæ°æè | + | 该参数可选, 指明Mail eXchanger。必须能够解析到一个IP,否则被忽略。如果不提供该参数或者 |
- | ä¸è½è§£æå°ä¸ä¸ªIPï¼mxè®°å½ä¼è¢«å é¤ã | + | 不能解析到一个IP,mx记录会被删除。 |
* backmx=YES|NO | * backmx=YES|NO | ||
- | è¯¥åæ°å¯é, ææåé¢çmxåæ°ä¼è¢«è®¾ç½®æå¤ä»½é®ä»¶æå¡å¨ï¼å³é®ä»¶ä¼é¦å åéå°ä½ çæºå¨ä¸ï¼å¦æ | + | 该参数可选, 指明前面的mx参数会被设置成备份邮件服务器,即邮件会首先发送到你的机器上,如果 |
- | 䏿åï¼æä¼åéå°å¤ä»½é®ä»¶æå¡å¨ä¸ã | + | 不成功,才会发送到备份邮件服务器上。 |
* offline=YES|NO Optional: Yes | * offline=YES|NO Optional: Yes | ||
- | è¯¥åæ°å¯é, 使ååææ¶å¤±æã | + | 该参数可选, 使域名暂时失效。 |
+ | ==== HTTP状态返回码 ==== | ||
+ | HTTP状态返回码为200、4XX、5XX,其中4XX表示认证错误,500表示服务器内部出错,200表示正常请求。但是动态域名客户端 | ||
+ | 请忽略HTTP返回码,而是对下面的返回值进行解析。比如返回值"interror"表示内部出错,这时对应的HTTP状态返回码是500。 | ||
- | ==== è¿åå¼ ==== | + | ==== 返回值 ==== |
- | === æ´æ°æå === | + | === 更新成功 === |
* good | * good | ||
- | æåï¼IPå°åå·²ç»æåæ´æ°ï¼good åé¢ä¼è·çææ´æ°çIPå°å | + | 成功,IP地址已经成功更新,good 后面会跟着所更新的IP地址 |
* nochg | * nochg | ||
- | æåï¼IPå°åå䏿¬¡è¯·æ±æ²¡æåå, nochg åé¢ä¼è·çæè¯·æ±çIPå°å | + | 成功,IP地址和上次请求没有变化, nochg 后面会跟着所请求的IP地址 |
- | === æ´æ°åºé === | + | === 更新出错 === |
* badauth | * badauth | ||
- | 身份认è¯åºéï¼è¯·æ£æ¥ç¨æ·ååå¯ç , æè ç¼ç æ¹å¼åºéã | + | 身份认证出错,请检查用户名和密码, 或者编码方式出错。 |
* badsys | * badsys | ||
- | 该åå䏿¯å¨æååï¼å¯è½æ¯å ¶ä»ç±»åçååï¼æºè½ååãéæååãåå转åãåååï¼ã | + | 该域名不是动态域名,可能是其他类型的域名(智能域名、静态域名、域名转向、子域名)。 |
* badagent | * badagent | ||
- | ç±äºåé大éå徿°æ®ï¼å®¢æ·ç«¯å称被系ç»å°æã | + | 由于发送大量垃圾数据,客户端名称被系统封杀。 |
- | === åæ°åºé === | + | === 参数出错 === |
* notfqdn | * notfqdn | ||
- | 没ææä¾åååæ°ï¼å¿ é¡»æä¾ä¸ä¸ªå¨å°è¾£æ¤æ³¨åç卿ååååã | + | 没有提供域名参数,必须提供一个在公云注册的动态域名域名。 |
* nohost | * nohost | ||
- | ååä¸åå¨ï¼è¯·æ£æ¥å忝å¦å¡«åæ£ç¡®ã | + | 域名不存在,请检查域名是否填写正确。 |
* !donator | * !donator | ||
- | å¿ é¡»æ¯æ¶è´¹ç¨æ·ï¼æè½ä½¿ç¨ offline 离线åè½ã | + | 必须是收费用户,才能使用 offline 离线功能。 |
* !yours | * !yours | ||
- | 该åååå¨ï¼ä½æ¯ä¸æ¯è¯¥ç¨æ·ææã | + | 该域名存在,但是不是该用户所有。 |
* !active | * !active | ||
- | 该åå被系ç»å ³éï¼è¯·èç³»å°è¾£æ¤å®¢æäººåã | + | 该域名被系统关闭,请联系公云客服人员。 |
* abuse | * abuse | ||
- | 该ååç±äºæ®µæ¶é´å¤§éåéæ´æ°è¯·æ±ï¼è¢«ç³»ç»ç¦æ¢ï¼è¯·èç³»å°è¾£æ¤å®¢æäººåã | + | 该域名由于段时间大量发送更新请求,被系统禁止,请联系公云客服人员。 |
+ | |||
+ | === 服务器出错 === | ||
* dnserr | * dnserr | ||
- | DNS æå¡å¨æ´æ°å¤±è´¥ | + | DNS 服务器更新失败。 |
+ | |||
+ | * interror | ||
+ | 服务器内部严重错误,比如数据库出错或者DNS服务器出错。 | ||
+ | |||
+ | ===== 获取IP接口 ===== | ||
+ | |||
+ | |||
+ | 客户端可以通过该接口获取自己的IP,用于客户端检测IP的变化。 | ||
+ | |||
+ | 注意访问 http://ip.3322.net 的两次间隔时间不能短于1分钟,如果连续3次以上频繁请求,该IP会被系统自动封堵 | ||
+ | |||
+ | |||
+ | ==== 接口地址 ==== | ||
+ | |||
+ | **API URL** | ||
+ | |||
+ | <code> | ||
+ | http://ip.3322.net | ||
+ | </code> | ||
+ | |||
+ | ==== 参数说明 ==== | ||
+ | 无 | ||
+ | |||
+ | ==== 返回值 ==== | ||
+ | |||
+ | 客户端的IP地址 | ||
+ | |||
+ | |||
+ | ===== 常见问题 ===== | ||
+ | |||
+ | * 没有对请求做事务处理,没有检查服务器的返回值,没有判断域名更新是否成功 | ||
+ | * 更新失败以后,没有记录日志,没有进行延时、重试的过程 | ||
+ | * 请求过于频繁,导致域名被服务器封杀 | ||
+ | * 客户端使用实例的名字,没有根据自己设备的类型、名称、特征进行自定义 | ||
+ | |||
+ | |||
+ | ===== 设备认证 ===== | ||
+ | |||
+ | |||
+ | 小辣椒动态域名更新API简单易用,方便了开发者和集成商开发自己的客户端,给设备增加动态域名功能。 | ||
+ | |||
+ | 但是如果对客户端的理解不深入,会产生一些错误或者更新失败,导致动态域名更新失败,用户无法通过域名访问设备。 | ||
+ | |||
+ | 小辣椒为了规范域名的更新流程,保障设备的正常工作,对市场上使用小辣椒动态域名更新API的设备进行认证: | ||
+ | |||
+ | * 由小辣椒的工程师,对设备进行认真,全面的测试,保证设备能够在各种网络条件、各种异常条件下正常更新域名 | ||
+ | * 提供认证的设备清单,推荐小辣椒的广大用户选用 | ||
+ | 设备认证的具体方法,请参见[[帮助:设备认证|设备认证]] |