这里会显示出您选择的修订版和当前版本之间的差别。
Both sides previous revision 前一修订版 | |||
帮助:api [2013/03/04 13:21] refactor [返回值] |
帮助:api [2013/03/04 13:22] refactor [设备认证] |
||
---|---|---|---|
行 1: | 行 1: | ||
- | ====== 公云(3322)动态域名更新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次以ä¸é¢ç¹è¯·æ±ï¼è¯¥IPä¼è¢«ç³»ç»èªå¨å°å µ |
- | * 使用[[http://www.ietf.org/rfc/rfc2617.txt|HTTP]]验证作为API的用户身份验证方式。 | + | * 使ç¨[[http://www.ietf.org/rfc/rfc2617.txt|HTTP]]éªè¯ä½ä¸ºAPIçç¨æ·èº«ä»½éªè¯æ¹å¼ã |
- | * User-Agent, 代表客户端名称、版本,需要根据设备类型、名称、特征进行自定义,一般包括设备的厂家、型号、firmware版本号。请不要使用示范中的名称,否则可能被封堵。 | + | * User-Agent, 代表客æ·ç«¯åç§°ãçæ¬ï¼éè¦æ ¹æ®è®¾å¤ç±»åãåç§°ãç¹å¾è¿è¡èªå®ä¹ï¼ä¸è¬å æ¬è®¾å¤çåå®¶ãåå·ãfirmwareçæ¬å·ã请ä¸è¦ä½¿ç¨ç¤ºèä¸çåç§°ï¼å¦åå¯è½è¢«å°å µã |
- | ===== 动态域名更新接口 ===== | + | ===== 卿ååæ´æ°æ¥å£ ===== |
- | ==== 接口地址 ==== | + | ==== æ¥å£å°å ==== |
**API URL** | **API URL** | ||
行 38: | 行 38: | ||
</code> | </code> | ||
- | **HTTP请求** | + | **HTTP请æ±** |
<code> | <code> | ||
行 47: | 行 47: | ||
</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ç¶æè¿åç ==== |
- | HTTP状态返回码为200、4XX、5XX,其中4XX表示认证错误,500表示服务器内部出错,200表示正常请求。但是动态域名客户端 | + | HTTPç¶æè¿åç 为200ã4XXã5XXï¼å ¶ä¸4XX表示认è¯é误ï¼500表示æå¡å¨å é¨åºéï¼200表示æ£å¸¸è¯·æ±ã使¯å¨æåå客æ·ç«¯ |
- | 请忽略HTTP返回码,而是对下面的返回值进行解析。比如返回值"interror"表示内部出错,这时对应的HTTP状态返回码是500。 | + | 请忽ç¥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 | * interror | ||
- | 服务器内部严重错误,比如数据库出错或者DNS服务器出错。 | + | æå¡å¨å é¨ä¸¥ééè¯¯ï¼æ¯å¦æ°æ®åºåºéæè DNSæå¡å¨åºéã |
- | ===== 获取IP接口 ===== | + | ===== è·åIPæ¥å£ ===== |
- | 客户端可以通过该接口获取自己的IP,用于客户端检测IP的变化。 | + | 客æ·ç«¯å¯ä»¥éè¿è¯¥æ¥å£è·åèªå·±çIPï¼ç¨äºå®¢æ·ç«¯æ£æµIPçååã |
- | 注意访问 http://ip.3322.net 的两次间隔时间不能短于1分钟,如果连续3次以上频繁请求,该IP会被系统自动封堵 | + | 注æè®¿é® http://ip.3322.net ç两次é´éæ¶é´ä¸è½çäº1åéï¼å¦æè¿ç»3次以ä¸é¢ç¹è¯·æ±ï¼è¯¥IPä¼è¢«ç³»ç»èªå¨å°å µ |
- | ==== 接口地址 ==== | + | ==== æ¥å£å°å ==== |
**API URL** | **API URL** | ||
行 144: | 行 144: | ||
</code> | </code> | ||
- | ==== 参数说明 ==== | + | ==== åæ°è¯´æ ==== |
- | 无 | + | æ |
- | ==== 返回值 ==== | + | ==== è¿åå¼ ==== |
- | 客户端的IP地址 | + | 客æ·ç«¯çIPå°å |
- | ===== 常见问题 ===== | + | ===== 常è§é®é¢ ===== |
- | * 没有对请求做事务处理,没有检查服务器的返回值,没有判断域名更新是否成功 | + | * 没æå¯¹è¯·æ±åäºå¡å¤çï¼æ²¡ææ£æ¥æå¡å¨çè¿åå¼ï¼æ²¡æå¤æååæ´æ°æ¯å¦æå |
- | * 更新失败以后,没有记录日志,没有进行延时、重试的过程 | + | * æ´æ°å¤±è´¥ä»¥åï¼æ²¡æè®°å½æ¥å¿ï¼æ²¡æè¿è¡å»¶æ¶ãéè¯çè¿ç¨ |
- | * 请求过于频繁,导致域名被服务器封杀 | + | * 请æ±è¿äºé¢ç¹ï¼å¯¼è´åå被æå¡å¨å°æ |
- | * 客户端使用实例的名字,没有根据自己设备的类型、名称、特征进行自定义 | + | * 客æ·ç«¯ä½¿ç¨å®ä¾çååï¼æ²¡ææ ¹æ®èªå·±è®¾å¤çç±»åãåç§°ãç¹å¾è¿è¡èªå®ä¹ |
- | ===== 设备认证 ===== | + | ===== 设å¤è®¤è¯ ===== |
- | 小辣椒动态域名更新API简单易用,方便了开发者和集成商开发自己的客户端,给设备增加动态域名功能。 | + | å ¬äº(3322)卿ååæ´æ°APIç®åæç¨ï¼æ¹ä¾¿äºå¼åè åéæåå¼åèªå·±ç客æ·ç«¯ï¼ç»è®¾å¤å¢å 卿åååè½ã |
- | 但是如果对客户端的理解不深入,会产生一些错误或者更新失败,导致动态域名更新失败,用户无法通过域名访问设备。 | + | 使¯å¦æå¯¹å®¢æ·ç«¯ççè§£ä¸æ·±å ¥ï¼ä¼äº§çä¸äºé误æè æ´æ°å¤±è´¥ï¼å¯¼è´å¨æååæ´æ°å¤±è´¥ï¼ç¨æ·æ æ³éè¿åå访é®è®¾å¤ã |
- | 小辣椒为了规范域名的更新流程,保障设备的正常工作,对市场上使用小辣椒动态域名更新API的设备进行认证: | + | å ¬äºä¸ºäºè§èååçæ´æ°æµç¨ï¼ä¿é设å¤çæ£å¸¸å·¥ä½ï¼å¯¹å¸åºä¸ä½¿ç¨å ¬äºå¨æååæ´æ°APIç设å¤è¿è¡è®¤è¯ï¼ |
- | * 由小辣椒的工程师,对设备进行认真,全面的测试,保证设备能够在各种网络条件、各种异常条件下正常更新域名 | + | * ç±å ¬äºçå·¥ç¨å¸ï¼å¯¹è®¾å¤è¿è¡è®¤çï¼å ¨é¢çæµè¯ï¼ä¿è¯è®¾å¤è½å¤å¨åç§ç½ç»æ¡ä»¶ãåç§å¼å¸¸æ¡ä»¶ä¸æ£å¸¸æ´æ°åå |
- | * 提供认证的设备清单,推荐小辣椒的广大用户选用 | + | * æä¾è®¤è¯çè®¾å¤æ¸ åï¼æ¨èå ¬äºçå¹¿å¤§ç¨æ·éç¨ |
- | 设备认证的具体方法,请参见[[帮助:设备认证|设备认证]] | + | 设å¤è®¤è¯çå ·ä½æ¹æ³ï¼è¯·åè§[[帮å©:设å¤è®¤è¯|设å¤è®¤è¯]] |