有道云笔记OpenAPI说明文档.pdf

有道有道云云笔记笔记 Open API 说明说明文档文档 版本 作者 概要 日期 0.1 李崇欣 起始版本，网易内部 API 说明 2011-9-13 0.2 李崇欣 反馈修订并添加 API 使用示例 2011-9-16 0.3 陈超 修改安全机制模块，添加 OAuth 认证 2011-11-17 0.4 李崇欣 API 接口修改 2011-12-7 0.4.4 李崇欣 添加User接口及每个应用的默认笔记本 2012-5-29 1.0 李崇欣 文档整理及接口更新 2012-7-27 概述概述 有道云笔记旨在以云存储技术帮助用户建立一个可以轻松访问、 安全存储的云笔记空间， 解决了个人资料和信息跨平台跨地点的管理问题，目前已经提供了桌面版、网页版以及部分型号的版本 但是用户对笔记的需求不仅仅局限于这几种情形，对于很多非笔记应用，用户仍然可能有跨平台跨设备的存储需求通过开放的 API，第三方应用只需要进行简单的开发，就可以通过标准的 web 协议对有道云笔记的数据进行安全的访问与修改，而不需要搭设和维护运存储服务， 这大大降低了第三方的开发与运营成本， 从而将更多的精力专注于应用本身。

本文档从技术角度对有道云笔记的开放 API 进行说明， 从而方便开发者的理解和使用 数据模型数据模型 目前有道云笔记的数据模型包括用户、笔记本、笔记以及附件四部分，下面对它们分别进行说明： 用户用户 每一个有道云笔记的账号（目前我们主要使用网易通行证作为账号，但是同时也支持用户使用新浪微博账号进行登录， 以后也将允许用户使用 账号进行登录）都在系统中对应着一份用户信息以及相应的配置，包括该用户邮箱、笔记总空间大小、当前使用空间大小、默认笔记本、时间以及注册时间、上次修改时间等一系列信息 笔记本笔记本 用户通过笔记本对所有笔记进行组织管理， 每一篇笔记必须属于某一个笔记本，同时为了方便用户的区分与定位，每个笔记本也必须具有唯一的名字目前有道云笔记已经支持将多个笔记本归类为一个笔记组，但是尚未对 OpenAPI 开放 对于同一篇笔记， 可以在两个笔记本之间进行转移，但是却不允许出现在两个笔记本中此外，每个用户在任何时候都有一个笔记本被标记为默认笔记本，如果一个笔记在创建时没有特别指明笔记本，它将被放入默认笔记本中删除一个笔记本将删除该笔记本下的所有笔记 虽然有道云笔记的客户端同时提供了同步笔记本与本地笔记本两种类型， 但是由于本地笔记本仅存储在用户的本机而没有上传至服务器， 因此 OpenAPI 只能创建或者访问用户同步笔记本中的笔记。

笔记笔记 一篇笔记由一段超文本以及相关联的附件（例如图片、文本、PPT、PDF 等）所组成，其中超文本的内容按照一种标记语言的格式进行存储， 每个附件所在的位置都对应着一个 tag，包含着该附件路径，从而可以根据该信息找到对应附件的数据同时，每个笔记还包含一些属性信息，例如题目、作者、来源 URL 以及创建修改时间等，这些信息可以用来对笔记进行查找、过滤以及排序 当一个笔记被删除时，它将被放入回收站，回收站中的笔记在一定的时间内仍然可以访问（Open API 不可以访问删除的笔记） ，但是不可以进行编辑，如果没有进行恢复，回收站的笔记将在一定的时间后（目前为两个月）被清除 笔记标记语言格式的详细说明见附录 A 附件附件 笔记附件是附属于笔记的二进制数据，无法脱离笔记单独存在， 因此如果仅上传附件而不添加相应的笔记，则该附件会被定期的空间回收所删除笔记附件类似于邮件的附件，但是与邮件的附件不同的是，笔记的附件没有与笔记的内容进行整体编码，而只是在笔记内容超文本的对应位置放置了一个 tag 对其进行引用， 附件的数据则单独进行存储 因此如果将附件 tag 在两个笔记之间进行拷贝，这两个笔记将共享同一个附件，而对附件的修改也将同时反映在两个笔记之中。

不过目前我们尚不提供附件修改的 API，每次上传的附件都是一个全新的附件，因此还不存在这样的问题随着 API 的完善，以后将提供类似的 API，因此如果第三方应用希望避免这种情况，需要自行对附件拷贝进行处理另一方面，如果共享附件的两篇笔记中有一篇笔记被删除， 不会对另外一篇笔记及其附件造成影响 目前笔记的附件支持除了 exe、com、cmd、bat、sys 以外的所有文件格式，大小限制为 100MB 授权授权机机制制 为了对用户的数据进行保护， 大部分API的访问都需要获得用户的身份信息，我们采用 OAuth 的方式对第三方应用进行授权，只有经过用户授权的应用才可以对用户的数据进行访问目前我们支持的 OAuth 版本为 1.0a，OAuth 的官方技术说明可参看 申请申请 Consumer Key 对于所有需要使用 Open API 的应用，在使用 Open API 之前首先要在系统内申请一个应用程序，申请者需要提交申请人姓名、email、应用名称、应用主页、callback URL 以及是否限制 callbackURL 等信息，我们会生成相应的 Consumer Key和 Consumer Secret，作为每个应用的身份标识。

应用名称和 Consumer Key 在系统中均是唯一的，在进行请求时，第三方应用需要将 Consumer Key 等验证信息加入请求中，而系统收到请求后，便可以根据 Consumer Key 和 Consumer Secret对请求进行验证与记录，具体请求方式参见授权请求说明 请求请求用户授权用户授权 授权流程授权流程 在获取 Consumer Key 和 Consumer Secret 后，应用程序便可以通过 OAuth 授权访问用户数据，一个完整的 OAuth 授权流程如下图所示： 请求请求 Request Token生成生成 Request Token及及 Request Secret(A)将用户重定向至登将用户重定向至登 陆授权页面陆授权页面询问用户是否对应询问用户是否对应 用授权用授权重定向至应用的重定向至应用的 callback携带携带verifier请求请求Access Token生成生成 Access Token和和 Access Secret利用利用Access Token 及及Secret获取用户获取用户 数据数据(B)(C)(D)(E)(F)第三方应用第三方应用有道云笔记有道云笔记获取获取 Request Token用户授权用户授权获取获取 Access Token使用使用 Access Token 访问用户数访问用户数 据据(G)第三方应用与服务器的步骤第三方应用与服务器的步骤用户浏览器可见的步骤用户浏览器可见的步骤用户接受或者拒绝用户接受或者拒绝 授权授权用户用户图图 1 OAuth 授权流程 应用程序首先利用 Consumer Key 与 Consumer Secret 从有道云笔记 Server 端获取 Request Token 及 Request Secret。

获取 Request Token 及 Secret 后，应用程序便可以将用户重定向至有道云笔记的用户登录授权页面，此时用户登录并选择接受或者拒绝对应用程序的授权，如果用户选择接受授权有道云笔记会重定向至应用程序提供的 callback 页面，并且将 verifier 作为参数一同传递过去；如果用户选择拒绝授权则终止整个授权过程 应用程序利用 Request Token 以及刚刚得到的 verifier 应用程序便可以请求Access Token， 而有道云笔记在验证过 Request Token 及 verifier 后便会生成 Access Token 及 Secret 返回给应用程序， 之后应用程序便可以使用 Access Token 及 Secret访问用户的数据通常 Access Token 具有一定的有效期，在有效期内应用程序可以一直访问该用户的数据，而当 Access Token 过期后，应用程序则需要再次走一遍授权流程 在上述过程中，如果发生了任何异常，有道云笔记都会返回对应的错误码及错误信息，详细的错误信息说明见附录 B 授权请求授权请求说明说明 在进行 OAuth 授权请求时， OAuth 相关的参数可以放置在 query string 和 http header 中，这里我们推荐使用 http header 的方式，这样可以将 OAuth 相关的参数与接口非 OAuth 参数区别对待， 其中 Header name 为 Authorization， 而 Header value 则为 OAuth 相关参数组成的值，格式如下： OAuth[空格空格][parameterName=”value”],[空格空格][ parameterName=”value”]… 此外在发送时还有以下几点需要注意： 1. parameterName 和 value 必须进行 Percent Encoding (做法为先进行 URL Encoding 后再要将”+”替换为”%20”,将”*”替换为”%2A”，将”%7E”替换为”~”) 2. value 的引号为必须 3. 发送请求时参数可以是无序的，但是在签名时这些参数有一定的顺序要求，详见附录 D 4. 请求的 baseURL 为有道云笔记的 domain，对于线上环境该 baseURL 为，而测试环境为 ，下同 一个包含 OAuth 参数的 Header 示例如下所示： 请求请求 Request Token  URL：：http://[baseURL]/oauth/request_token  请求方式：请求方式：GET  OAuth 参数：参数： 参数名 参数说明 oauth_callback 回调 url，该 url 可以为 oob,代表不回调，另外 url 还可以跟其他参数 oauth_consumer_key 申请应用时拿到的 Consumer Key oauth_signature_method 签名方法，支持 HMAC-SHA1 oauth_timestamp 时间戳，当前时间，单位毫秒 Authorization: OAuth oauth_token=“64e4f0c25029dd6687ea74cd64e9640a“, oauth_consumer_key=“2456f9dd37e162ffe237c8b88739925f“, oauth_signature_method=“HMAC-SHA1“, oauth_timestamp=“1343381467“, oauth_nonce=“952606576956129“, oauth_version=“1.0“, oauth_signature=“%2FLQhn0OCf3lCMPSAAMVW35aUka0%3D“ oauth_nonce 随机串，为了防止重放攻击，5 分钟内同一用户同一应用同一时间发来的请求中 oauth_nonce 应不同 oauth_version 1.0 oauth_signature 签名，使用 Consumer Secret +’&’作为签名的 key， 而签名的内容是除 oath_signature 以外的请求 url 内容，计算签名完毕后，使用 base64 编码，具体签名方法见附录D  返回结果：返回结果：请求成功时返回 oauth_token 和 oauth_token_secret，即 Request Token 与 Secret，结果示例： 请求失败时返回 http status code 500 以及 error message 请求请求用户登录用户登录授权授权  URL：： http://[baseURL]/oauth/authorize  请求方式请求方式：：GET  OAuth 参数。