出自Yahoo_cn_wiki

跳转到: 导航, 搜索

您在这：首页 > NCP文档中心 > NCP接口文档 > 应用回调接口

应用回调接口

目录


NCP在展现模块内容及用户对模块进行操作（如设置、浏览）时，需要开发者在注册时提供的回调地址，即“回调接口”。

视图展示

  • 标准视图：对于标准视图，NCP平台调用回调地址时，传递的参数y_view_mode的值为“box”。
  • 完整视图：应用可以有一个或者多个完整视图，开发者时可以根据应用需求确定。NCP平台调用回调地址时，传递的参数y_view_mode的值为“full”。如果应用只需要一个完整视图的话，完整视图的入口地址为：http://{添加该应用的站点域名}/apps/{注册时填写的应用路径}/?module_id=xxx，；如果应用需要多个完整视图，开发者需要根据URL规范构造其他完整视图的URL，URL构造规则可以参考回调地址映射。
  • 配置视图回调接口：
  • 接口的URL具体规则请参见回调地址映射。

回调接口的输出方式

对视图展示，NCP支持两种输出方式：框架嵌入方式和代码嵌入方式。

如果用代码嵌入方式输出，需要符合YNML规范；如果用框架嵌入方式输出，需要符合HTML规范。

注意，目前NCP对回调接口不同视图的输出方式的支持情况是不同的，具体情况请看下面的表格：

回调接口的输出方式
嵌入方式 代码嵌入 框架嵌入
标准视图 YES YES
完整视图 YES YES
配置视图 NO YES

对标准视图和完整视图而言，可以选择两者之一，开发者需要在注册应用时指明；对配置视图而言，NCP只支持框架嵌入方式；


回调接口协议

回调接口参数

NCP调用应用的回调接口时，会向应用传递两类参数：

  1. 系统参数：NCP中规定的通用参数，以y_开头，详见下表。
  2. 应用参数：应用自定义的参数。模块的表单或超链接中带有的参数。应用可以自定义参数名。

应用参数的名称，建议不要以y_开头，以免和系统参数重名。

如果发生重名，参数值将会是系统参数值。

NCP系统参数

参数名称 参数描述 是否必需 说明
y_api_key 接口密钥 Y 应用的API Key，22字节字符串。
y_module_id 模块ID Y 站长添加应用时NCP实例化一个模块对应的唯一标识。
y_module_ver 模块修订次数 Y 用户每次修改模块配置后，该数字加一。
y_session_key 会话ID N 32位字符串。唯一标识当前会话，仅对登录用户有效。
y_expires 当前会话有效时刻 N UNIX时间戳，该时刻过后当前会话失效，仅对登录用户有效。
y_user_id 当前用户ID N 用户标识符，字符串
y_user_role 当前用户角色 N 当前用户在当前站点的角色，编码方式：
1-站长
2-站点管理员
3-站点会员
4-普通用户
y_site_id 当前站点ID Y 站的标识，字符串
y_site_domain 当前站点域名 Y 站的域名，字符串，例如：example.zhan.cn.yahoo.com
y_site_mod_sig 站点和模块签名 Y 字符串
y_iframe 是否框架嵌入方式 Y 描述接口的输出类型，编码方式：
0-代码嵌入方式
1-框架嵌入方式。
y_view_mode 应用所在视图 Y 编码方式，取值说明：
conf：配置视图
box：标准视图
full：完整视图
y_view_width 应用所在容器的宽度 Y 单位为象素
y_sig 签名 Y 32字节字符串，NCP对调用参数的签名，应用可根据该参数对调用进行鉴权。

上面表格中有4个参数是针对当前用户的会话的：

  • y_user_id
  • y_expires
  • y_session_key
  • y_user_role

只有当前用户处于登录状态时，NCP才会向应用传递这些参数；对于未登录用户，NCP将省略这些参数。

如果采用框架(iframe)方式嵌入的话，应用需要检查会话的有效性。如果y_expires小于当前时间，表示用户的会话已失效，应用应该忽略y_user_id、y_user_role等用户相关参数，并提示用户重新登录。

回调请求报头

在调用应用展示接口时，请求中会包含一些HTTP报头。可能出现的报头见下表：

NCP传递给应用接口的参数列表
报头 说明
Accept 浏览器可以接受的文件类型
Accept-Language 浏览器可以接受的语言
Accept-Charset 浏览器可以接受的字符集
Content-Type 针对POST
Content-Length 针对POST
Client-ip 客户端IP地址，例如：202.106.1.196
Referer 发起该请求的原始页面URL
User-Agent 标识浏览器类型
X-Forwarded-For 客户端IP地址，例如：202.106.1.196
X-Yahoo-Crumb 表单验证串。注1
  • 注1：应用可以将X-Yahoo-Crumb的值做为表单中的hidden参数值来检验表单的确是由用户提交的。具体方法是：应用可把这个值作为表单的hidden变量提交，在接收表单的处理程序中，应用也可以从报头中得到X-Yahoo-Crumb变量，这样应用可以通过比较前后两个变量是否相等来判断是否是通过用户发起的，如果相等，说明是用户发起的，否则不是。

回调应答报头

NCP目前仅在使用的回调应答报头是Content-Type和Cache-Control。

应用通过设置Content-Type报头来通知NCP其应答的MIME类型。目前NCP中仅支持text/*的MIME类型，例如：

  • text/html
  • text/plain

Cache-Control用来控制输出结果的缓存，将在应答的缓存中介绍。

模块错误代码

NCP调用应用的回调接口时发生了错误，相应的模块将无法正常显示，这时NCP会将出错代码显示在模块中。

理解这些代码对调试应用会很有帮助。可能出现的错误代码有：

  • 400 - 417：RFC2616中规定的HTTP状态码。
  • 408：回调请求超时
  • 425：应用返回的内容超过最大长度
  • 426：应用返回了无效的MIME类型。目前仅支持text/*。
  • 428：应用要求用户登录。(注意：在标准视图中不允许应用返回428)。
  • 461：YNML语法错误
  • 500 - 506：RFC2616中规定的HTTP状态码。
  • 6xx：NCP调用应用缓存失败，6xx = 600 + CURL出错代码

HTML表单的处理

用户从浏览器中提交的表单，NCP不对参数做任何处理，直接将表单内容转发给应用。

取自"http://wiki.dev.cn.yahoo.com/index.php/NCP:API/Callback"
个人工具