帮助:api
差别
这里会显示出您选择的修订版和当前版本之间的差别。
| 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ç设å¤è¿è¡è®¤è¯ï¼ |
| - | * 由小辣椒的工程师，对设备进行认真，全面的测试，保证设备能够在各种网络条件、各种异常条件下正常更新域名 | + | * ç±å ¬äºçå·¥ç¨å¸ï¼å¯¹è®¾å¤è¿è¡è®¤çï¼å ¨é¢çæµè¯ï¼ä¿è¯è®¾å¤è½å¤å¨åç§ç½ç»æ¡ä»¶ãåç§å¼å¸¸æ¡ä»¶ä¸æ£å¸¸æ´æ°åå |
| - | * 提供认证的设备清单，推荐小辣椒的广大用户选用 | + | * æä¾è®¤è¯ç设å¤æ¸ åï¼æ¨èå ¬äºç广大ç¨æ·éç¨ |
| - | 设备认证的具体方法，请参见[[帮助:设备认证|设备认证]] | + | 设å¤è®¤è¯çå ·ä½æ¹æ³ï¼è¯·åè§[[帮å©:设å¤è®¤è¯|设å¤è®¤è¯]] |
帮助/api.txt · 最后更改: 2013/03/04 13:22 由 refactor
除额外注明的地方外，本维基上的内容按下列许可协议发布： CC Attribution-Noncommercial 3.0 Unported
