差别

这里会显示出您选择的修订版和当前版本之间的差别。

--- 帮助: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>
 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
 User-Agent: myclient/1.0 me@null.net
 </code>
-==== åæ°è¯´æ ====
+==== 参数说明 ====
   * username:password
-è¯¥åæ°å¿é, ç¨æ·ååå¯ç ç¨æ¥è¿è¡èº«ä»½è®¤è¯ï¼å¿é¡»ä½¿ç¨ base64è¿è¡ç¼ç
+该参数必选, 用户名和密码用来进行身份认证，必须使用 base64进行编码
   * hostname=host.3322.org
-è¯¥åæ°å¿é, éè¦æ´æ°çåå
+该参数必选, 需要更新的域名
   * myip=ipaddr
-è¯¥åæ°å¯é, ååå¯¹åºçIPãå¦æä¸æå®ï¼åæå¡å¨å°éæ©æä½³çIP(ä¸äºProxyä¼ä¼ éå®¢æ·ç«¯çIP,
+该参数可选, 域名对应的IP。如果不指定，则服务器将选择最佳的IP(一些Proxy会传递客户端的IP,
-è¿ä¼è¢«æå¡å¨æ£æµå°)ãå¦æä¼ éçå°åæ ¼å¼éè¯¯ï¼åå¿½ç¥è¿ä¸ªåæ°ï¼èç¨æå¡å¨æ£æµ
+这会被服务器检测到)。如果传递的地址格式错误，则忽略这个参数，而用服务器检测
-å°çIPã
+到的IP。
   * wildcard=ON|OFF
-è¯¥åæ°å¯é, è¯¥åæ°å¯éï¼æ¯å¦æ¯ææ³åå(ééç¬¦)ï¼ç¼ºçä¸ºOFFãONæä¸ºç *.host.3322.orgçåäºhost.3322.org
+该参数可选, 该参数可选，是否支持泛域名(通配符)，缺省为OFF。ON意为着 *.host.3322.org等同于host.3322.org
   * mx=mailexchanger
-è¯¥åæ°å¯é, ææMail eXchangerãå¿é¡»è½å¤è§£æå°ä¸ä¸ªIPï¼å¦åè¢«å¿½ç¥ãå¦æä¸æä¾è¯¥åæ°æè
+该参数可选, 指明Mail eXchanger。必须能够解析到一个IP，否则被忽略。如果不提供该参数或者
-ä¸è½è§£æå°ä¸ä¸ªIPï¼mxè®°å½ä¼è¢«å é¤ã
+不能解析到一个IP，mx记录会被删除。
   * backmx=YES|NO
-è¯¥åæ°å¯é, ææåé¢çmxåæ°ä¼è¢«è®¾ç½®æå¤ä»½é®ä»¶æå¡å¨ï¼å³é®ä»¶ä¼é¦ååéå°ä½ çæºå¨ä¸ï¼å¦æ
+该参数可选, 指明前面的mx参数会被设置成备份邮件服务器，即邮件会首先发送到你的机器上，如果
-ä¸æåï¼æä¼åéå°å¤ä»½é®ä»¶æå¡å¨ä¸ã
+不成功，才会发送到备份邮件服务器上。
   * offline=YES|NO	 Optional: Yes
-è¯¥åæ°å¯é, ä½¿ååææ¶å¤±æã
+该参数可选, 使域名暂时失效。
+==== HTTP状态返回码 ====
+HTTP状态返回码为200、4XX、5XX，其中4XX表示认证错误，500表示服务器内部出错，200表示正常请求。但是动态域名客户端
+请忽略HTTP返回码，而是对下面的返回值进行解析。比如返回值"interror"表示内部出错，这时对应的HTTP状态返回码是500。
-==== è¿åå¼ ====
+==== 返回值 ====
-=== æ´æ°æå ===
+=== 更新成功 ===
   * good
-æåï¼IPå°åå·²ç»æåæ´æ°ï¼good åé¢ä¼è·çææ´æ°çIPå°å
+成功，IP地址已经成功更新，good 后面会跟着所更新的IP地址
   * nochg
-æåï¼IPå°ååä¸æ¬¡è¯·æ±æ²¡æåå, nochg åé¢ä¼è·çæè¯·æ±çIPå°å
+成功，IP地址和上次请求没有变化, nochg 后面会跟着所请求的IP地址
-=== æ´æ°åºé ===
+=== 更新出错 ===
   * badauth
-èº«ä»½è®¤è¯åºéï¼è¯·æ£æ¥ç¨æ·ååå¯ç , æèç¼ç æ¹å¼åºéã
+身份认证出错，请检查用户名和密码, 或者编码方式出错。
   * badsys
-è¯¥ååä¸æ¯å¨æååï¼å¯è½æ¯å¶ä»ç±»åçååï¼æºè½ååãéæååãååè½¬åãåååï¼ã
+该域名不是动态域名，可能是其他类型的域名（智能域名、静态域名、域名转向、子域名）。
   * badagent
-ç±äºåéå¤§éåå¾æ°æ®ï¼å®¢æ·ç«¯åç§°è¢«ç³»ç»å°æã
+由于发送大量垃圾数据，客户端名称被系统封杀。
-=== åæ°åºé ===
+=== 参数出错 ===
   * notfqdn
-æ²¡ææä¾åååæ°ï¼å¿é¡»æä¾ä¸ä¸ªå¨å°è¾£æ¤æ³¨åçå¨æååååã
+没有提供域名参数，必须提供一个在公云注册的动态域名域名。
   * nohost
-ååä¸åå¨ï¼è¯·æ£æ¥ååæ¯å¦å¡«åæ£ç¡®ã
+域名不存在，请检查域名是否填写正确。
   * !donator
-å¿é¡»æ¯æ¶è´¹ç¨æ·ï¼æè½ä½¿ç¨ offline ç¦»çº¿åè½ã
+必须是收费用户，才能使用 offline 离线功能。
   * !yours
-è¯¥åååå¨ï¼ä½æ¯ä¸æ¯è¯¥ç¨æ·ææã
+该域名存在，但是不是该用户所有。
   * !active
-è¯¥ååè¢«ç³»ç»å³éï¼è¯·èç³»å°è¾£æ¤å®¢æäººåã
+该域名被系统关闭，请联系公云客服人员。
   * abuse
-è¯¥ååç±äºæ®µæ¶é´å¤§éåéæ´æ°è¯·æ±ï¼è¢«ç³»ç»ç¦æ¢ï¼è¯·èç³»å°è¾£æ¤å®¢æäººåã
+该域名由于段时间大量发送更新请求，被系统禁止，请联系公云客服人员。
+=== 服务器出错 ===
   * 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的设备进行认证：
+  * 由小辣椒的工程师，对设备进行认真，全面的测试，保证设备能够在各种网络条件、各种异常条件下正常更新域名
+  * 提供认证的设备清单，推荐小辣椒的广大用户选用
+设备认证的具体方法，请参见[[帮助:设备认证|设备认证]]

公云(PubYun)wiki

用户工具

站点工具

差别

页面工具