Open APInote.youdao.com/open/download/apidoc_0.4.4.pdf有道云笔记Open API 说明文档 版本...
Transcript of Open APInote.youdao.com/open/download/apidoc_0.4.4.pdf有道云笔记Open API 说明文档 版本...
有道云笔记 Open API说明文档
版本 作者 概要 日期
01 李崇欣 起始版本网易内部 API说明 2011-9-13
02 李崇欣 反馈修订并添加 API使用示例 2011-9-16
03 陈超 修改安全机制模块添加 OAuth认证 2011-11-17
04 李崇欣 API接口修改 2011-12-7
044 李崇欣 添加User接口及每个应用的默认笔记本 2012-5-29
概述
有道云笔记旨在以云存储技术帮助用户建立一个可以轻松访问安全存储的
云笔记空间解决了个人资料和信息跨平台跨地点的管理问题目前已经提供了
桌面版网页版以及部分手机型号的版本但是用户对笔记的需求不仅仅局限于
这几种情形对于很多非笔记应用用户仍然可能有跨平台跨设备的存储需求
通过开放的 API第三方应用只需要进行简单的开发就可以通过标准的 web协
议对有道云笔记的数据进行安全的访问与修改而不需要搭设和维护运存储服
务这大大降低了第三方的开发与运营成本从而将更多的精力专注于应用本身
本文档从技术角度对有道云笔记的开放 API进行说明从而方便开发者的理
解和使用
数据模型
目前有道云笔记的数据模型包括用户笔记本笔记以及附件四部分下面
将对它们分别进行说明
用户
每一个有道云笔记的账号(目前我们使用网易通行证作为账号但是以后将
允许使用其它网站的开放认证账号例如新浪微博账号人人网账号)都在系统
中对应着一份用户信息包括该用户邮箱笔记总空间当前使用空间默认笔
记本在线时间以及注册时间上次修改时间等一系列信息
笔记本
用户通过笔记本对所有笔记进行组织管理每一篇笔记必须属于某一个笔记
本同时为了方便用户的区分与定位每个笔记本也必须具有唯一的名字目前
有道云笔记仅支持一层笔记本结构而不支持笔记本的多层嵌套
对于同一篇笔记可以在两个笔记本之间进行转移但是却不允许出现在两
个笔记本中此外每个用户在任何时候都有一个笔记本被标记为默认笔记本
如果一个笔记在创建时没有特别指明笔记本它将被放入默认笔记本中删除一
个笔记本将删除该笔记本下的所有笔记
虽然有道云笔记的客户端同时提供了同步笔记本与本地笔记本两种类型但
是由于本地笔记本仅存储在用户的本机而没有上传至服务器因此开放 API只能
创建或者访问用户同步笔记本中的笔记
笔记
一篇笔记由一段超文本以及相关联的附件(例如图片文本PPTPDF等)
所组成其中超文本的内容按照一种标记语言的格式进行存储每个附件所在的
位置都对应着一个 tag包含着该附件路径从而可以根据该信息找到对应附件
的数据同时每个笔记还包含一些属性信息例如题目作者来源 URL以及
创建修改时间等这些信息可以用来对笔记进行查找过滤以及排序
当一个笔记被删除时它将被放入回收站回收站中的笔记在一定的时间内
仍然可以访问(Open API不可以访问删除的笔记)但是不可以进行编辑如果
没有进行恢复回收站的笔记将在一定的时间后(目前为两个月)被清除
笔记标记语言格式的详细说明见附录 A
附件
笔记附件是附属于笔记的二进制数据无法脱离笔记单独存在因此如果仅
上传附件而不添加相应的笔记则该附件会被定期的空间回收所删除笔记附件
类似于邮件的附件但是与邮件的附件不同的是笔记的附件没有与笔记的内容
进行整体编码而只是在笔记内容超文本的对应位置放置了一个 tag附件的数
据则单独进行存储因此如果将附件 tag在两个笔记之间进行拷贝这两个笔记
将共享同一个附件而对附件的修改也将同时反映在两个笔记之中不过目前我
们尚不提供附件修改的 API还不存在这样的问题随着 API的晚上以后将提
供类似的 API因此如果第三方应用希望避免这种情况需要自行对附件拷贝进
行处理另一方面如果共享附件的两篇笔记中有一篇笔记被删除不会对另外
一篇笔记及其附件造成影响
目前笔记的附件支持除了 execomcmdbatsys以外的所有文件格式
大小限制为 25MB
授权机制
为了对用户的数据进行保护大部分API的访问都需要获得用户的身份信息
我们采用 OAuth 的方式对第三方应用进行授权只有经过用户授权的应用才可
以对用户的数据进行访问目前我们支持 OAuth 10aOAuth的官方技术说明可
参看 httpoauthnet
申请 Consumer Key
对于所有需要使用 Open API的应用在使用 Open API之前首先要在系统内
申请一个应用程序申请者需要提交申请人姓名应用名称callback URL以及
是否限制 callbackURL 等信息我们会生成相应 的 ConsumerKey 和
ConsumerSecret作为每个应用的身份标识应用名称和 ConsumerKey在系统中
均是唯一的在进行请求时第三方应用需要将 ConsumerKey加入请求中而系
统收到请求后便可以根据 ConsumerKey 和 ConsumerSecret 对请求进行验证与
记录
目前我们采用网站申请的方式申请网址httpnoteyoudaocomopen
也可以采用邮件申请的方式申请人可直接发送邮件至 noteapirdneteasecom
邮件内容示例如下
App名称pYNote
组织类型个人公司
姓名张三XX科技有限公司
email XXX163com
homelinkhttpwwwyoudaocom
应用类型浏览器插件(应用)IOS appAndroid appWindows appMac os app
其它请在详细描述中说明
详细描述Linux下基于 Python的有道云笔记客户端
另外还需要 2种规格的 LOGO6060177177JPG格式即可
请求用户授权
授权流程
在拿到 ConsumerKey 和 ConsumerSecret 以后应用程序便可以结合
ConsumerKey 申请一个 request_token 和 request_secret发送的内容应该有
ConsumerSecret的签名
应用程序再次用 request_token 和 ConsumerKey 来申请用户授权该请求内
容应该由 ConsumerSecret 和 request_secret 共同签名授权时需要用户在
OauthServer 提供的页面中输入用户名密码等信息进行授权操作已经登录过的
用户可以直接进行授权操作用户授权之后会返回 request_token和 verifier 此
时的 request_token在 OauthServer中已经授权
授权之后应用程序就可以使用 request_token 申请 access_token 和
access_secret该请求内容同样要使用 ConsumerSecret 和 request_secret 共同签
名
如果以上步骤中可能会因为超时或者发送内容不符造成错误OAuth会返回
错误信息给应用程序
详细流程见图 211
开始
结束
请求是否合法
请求requst_token
返回错误信息
生成request_token
Y
返回授权的request_tokensecr
et verifier等信息
请求授权
对request_token授权生成
verifier(PIN码)
request_token
是否存在
Y
请求是否合法
N
请求access_token
生成access_token
Y
图 211 授权流程图
授权请求参数方法和返回值
下面将介绍如何使用 OauthServer服务得到 access_token和 access_secret下
面的文字中[baseURL]指代 OauthServer 的 URL对于线上环境该 baseURL
即为 httpnoteyoudaocom而对于 sandbox 测试环境该 baseURL 为
httpsandboxnoteyoudaocom这里使用 HTTP Header设置参数 Header
name 设 为 Authorization Header value 设 为 OAuth[ 空
格][parameterName=rdquovaluerdquo][空格][ parameterName=rdquovaluerdquo]hellip 值得注意
的是 parameterName 和 value 必须进行 URL 编码并且在 URL 编码后还要
将 rdquo+rdquo替换为 rdquo20rdquo将rdquordquo替换为 rdquo2Ardquo将 rdquo7Erdquo替换为 rdquo~rdquo例如请求
authorized token时 HTTP header中的 value是
OAuth[ 空 格 ]oauth_token=29cc36314495ee1cf55ebf26ca9711bc[ 空 格 ]
oauth_consumer_key=407d014e17ad5cd02f3e0a55fcb198af [ 空
格 ]oauth_signature_method=HMAC-SHA1[ 空
格 ]oauth_timestamp=1323325710[ 空
格 ]oauth_nonce=278825208972307[ 空 格 ]oauth_version=10[ 空 格 ]
oauth_signature=x8E7wrAmn6GyHv4aldWSo1M2ShU3D 注意其中双引
号rdquordquo是必须的 发送请求时这些参数可以是无序的但是签名时这些参
数有一定的顺序详见附录 D
以下各个请求正确时返回值 content-type 为 textplain 返回
key=value[空格]key=value
以下各个请求错误时会返回错误信息该信息包含 error message等
error是错误码message包含更详尽的错误信息另外特殊错误时还可能返
回更多信息详见附录 B
请求 request_token
URL[baseURL]oauthrequest_token
请求方式GET
请求参数
参数名 参数说明
oauth_callback 回调 url该 url可以为 oob代表不回调另外 url还可
以跟其他参数
oauth_consumer_key 申请应用时拿到的 consumerKey
oauth_signature_method 签名方法支持 HMAC-SHA1
oauth_timestamp 时间戳当前时间单位毫秒
oauth_nonce 随机串为了防止重放攻击5分钟内同一用户同一应用同
一时间发来的请求中 oauth_nonce应不同
oauth_version 10
oauth_signature 签名使用 consumerSecret +rsquoamprsquo作为签名的 key 而
签名的内容是除 oath_signature以外的请求 url内容
计算签名完毕后使用 base64编码
正确时返回oauth_token_secret(授权流程中的 request_secret 用于申请
access_token 时签名) oauth_token(授权流程中的 requset_token 用于
authorize请求和 access_token请求)和 oauth_callback_confirmed(boolean
值)
错误时返回 error message error是 error code message是错误信息以 json
串形式返回
发送示例
用 curl来举例 请求信息类似于
curl ndashH ldquoAuthorization OAuth oauth_callback=rdquooobrdquo
oauth_consumer_key=rdquo7a23b1eaf487060deaa5660b323c341brdquo
oauth_signature_method=rdquoHMAC-SHA1rdquo oauth_timestamp=rdquo1321847131rdquo
oauth_nonce=rdquo439563436203139rdquo oauth_version=rdquo10rdquordquo
ldquohttpsandboxnoteyoudaocomoauthrequest_tokenrdquo
但是需要注意的是各个 key-value对都需要使用 OAuth编码 详见附录 D
备注
示例中的签名内容大致为(参数顺序可能有变化详见附录 D的签名过程)
GETamp
httpsandboxnoteyoudaocomoauthrequest_tokenampoauth_callback=oobampo
auth_consumer_key=7a23b1eaf487060deaa5660b323c341bampoauth_signature_
method=HMAC-SHA1ampoauth_timestamp=1321847131ampoauth_nonce=4395634
36203139ampoauth_version=10
具体签名方法详见附录 D
请求授权
URL [baseURL]oauthauthorize
请求方式GET
请求参数该处的参数必须以 query string的形式发送
参数名 参数说明
oauth_token 请求 request_token时返回的 oauth_token
正确时返回oauth_token(授权后的 request_token) 和 oauth_verifier
错误时返回error message
发送示例
GET http
sandboxnoteyoudaocomoauthauthorizeoauth_token=5420db084cc41d768d885
a53f7b2c1a6
备注如果 oauth_callback为 oob则不会回调用户会在 Oauth Server页面上
看到 pin 码用户需要手工将 pin 码粘帖到 application 中才能申请到
AccessToken应用请求 authorize时如果请求携带了网易或者有道的 cookie
则将直接询问用户是否授权否则会重新定向到网易的通行证页面
请求 access_token
URL[baseURL]oauthaccess_token
请求方式GET
请求参数
参数名 参数说明
oauth_consumer_key 回调 url
oauth_token request_token时返回的 oauth_token
oauth_verifier Authorize请求时发送回来的 oauth_verifier或者是
OauthServer页面显示的 Pin码
oauth_signature_method 签名方法支持 HMAC-SHA1
oauth_timestamp 时间戳当前时间单位毫秒
oauth_nonce 随机串为了防止重放攻击5分钟内同一用户同一应用同
一时间发来的请求中 oauth_nonce应不同
oauth_version 10
oauth_signature 使用 consumerSecret + rsquoamprsquo + oauth_token_secret
字串作为key 而签名的内容是除oauth_signature以外
的请求 url内容计算签名完毕后使用 base64编码
正确时返回oauth_token_secret (授权流程中的 access_secret)oauth_token
(授权流程中的 access_token)
错误时返回error message
发送示例 http header的例子
curl ndashH ldquoAuthorization OAuth
oauth_verifier=rdquo8714fb943a28d7faffec3265e96d85cdrdquo
oauth_token=rdquob348d10a0f45a4cf6936381d6c9fb00frdquo
oauth_consumer_key=rdquo7a23b1eaf487060deaa5660b323c341brdquo
oauth_signature_method=rdquoHMAC-SHA1rdquo oauth_timestamp=rdquo1321857128rdquo
oauth_nonce=rdquo449560105422526rdquo oauth_version=rdquo10rdquo
oauth_signature=rdquoS8yxdpLIA7MiFVDE4OzSDoo2F62FI3Drdquordquo
ldquohttpsandboxnoteyoudaocomoauthaccess_tokenrdquo
访问 OpenAPI
由 223 返回的 oauth_token 将用于 OpenAPI 的请求 consumerSecret + rsquoamprsquo +
oauth_token_secret 将 用 作 签 名 例 如 请 求 创 建 笔 记 本
http[baseURL]ywsopennotebookcreatejson则应在请求创建笔记中添加各
种参数(创建笔记本的其他参数按文档要求不变)如果没有则会返回 error
和 message(此处的 error和 message会放入到 json串中error是错误码 message
是具体错误信息)不会执行任何 OpenAPI操作
例如执行创建笔记本操作参数 name需和 oauth 的其他值一起进行签名
但是不应该将 name 放入 header 中并且发送 post 请求的 Content-Type 为
applicationx-www-form-urlencoded其他参数填入 http content 域Oauth 参数
放入 Authorization Header域否则可能会出现错误
对于上传笔记或者附件图片的 open API 中post 请求的 Content-Type 为
multipartform-data非 oauth参数均不参与签名非 oauth参数填入 http content
域Oauth参数放入 Authorization Header域否则可能会出现错误
对于使用 GET请求 http[baseURL]ywsopenusergetjson需要将 oauth参
数和非 oauth参数一起放入 url参数中签名时需注意参数顺序发送请求时参
数可以无序
POST
httpnoteyoudaocomywsopennotecreatejson
Header 中 Authorization的值为
OAuth[ 空 格 ]oauth_token=29cc36314495ee1cf55ebf26ca9711bc
oauth_consumer_key=407d014e17ad5cd02f3e0a55fcb198af
oauth_signature_method=HMAC-SHA1 oauth_timestamp=1323327110
oauth_nonce=280224628487931 oauth_version=10
oauth_signature=rXpd0apk82wMAZLun2FDSUt1wbQE3D
最终 Header类似于
Authorization=OAuth20oauth_token3D2229cc36314495ee1cf55ebf26ca
9711bc222C20oauth_consumer_key3D22407d014e17ad5cd02f3e0a55fcb198
af222C20oauth_signature_method3D22HMAC-SHA1222C20oauth_timest
amp3D221323327041222C20oauth_nonce3D22280155519121203222C20
oauth_version3D2210222C20oauth_signature3D22E252F8dFmTFGTmdC
FE2rnJ8f252Bkzw9c253D22
签名的具体方法详见附录 D访问 Oauth的类库包详见附录 C
用户操作 API
查看用户信息
URLhttp[baseURL]ywsopenusergetjson
请求方式GET
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数无
返回结果操作成功时 http 状态为 200并用户信息失败时 http 状态为
500并返回错误码和错误信息详见附录 B
结果示例
ldquouserrdquo ldquotest163comrdquo 用户 ID
ldquototal_sizerdquo ldquo10293736383rdquo 用户总的空间大小单位字节
ldquoused_sizerdquo ldquo1024rdquo 用户已经使用了的空间大小单位字节
ldquoregister_timerdquo ldquo1323310917650rdquo 用户注册时间单位毫秒
ldquolast_login_timerdquo ldquo1323310949120rdquo 用户最后登录时间单位毫秒
ldquolast_modify_timerdquo ldquo1323310978120rdquo 用户最后修改时间单位毫秒
ldquodefault_notebookrdquo ldquoAB384D734rdquo 该应用的默认笔记本
注对于每个第三方应用都分别在用户的笔记空间中对应一个默认笔记本
笔记本名在申请应用时指定在使用 OpenAPI创建笔记时如果第三方应用
不指定笔记本则自动创建在该默认笔记本中
笔记本操作 API
查看用户全部笔记本
URLhttp[baseURL]ywsopennotebookalljson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数无
返回结果操作成功时 http状态为 200并返回笔记本列表失败时 http状
态为 500并返回错误码和错误信息详见附录 B
结果示例
[
ldquopathrdquo ldquo4AF64012E9864Crdquo 笔记本的路径
ldquonamerdquo ldquo笔记本 1rdquo 笔记本的名称
ldquonotes_numrdquo ldquo3rdquo 该笔记本中笔记的数目
ldquocreate_timerdquo ldquo1323310917rdquo 笔记本的创建时间单位秒
ldquomodify_timerdquo ldquo1323310949rdquo 笔记本的最后修改时间单位秒
ldquopathrdquo ldquo5AB0C6B33BD1162rdquo
ldquonamerdquo ldquo笔记本 2rdquo
ldquonotes_numrdquo ldquo10rdquo
ldquocreate_timerdquo ldquo1323311244rdquo
ldquomodify_timerdquo ldquo1323310349rdquo
]
列出笔记本下的笔记
URLhttp[baseURL]ywsopennotebooklistjson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
notebook 笔记本路径 是 String
返回结果操作成功时 http状态为 200并返回该笔记本下的笔记列表(只
有笔记路径笔记内容需要通过笔记接口获取)失败时 http状态 500并返
回错误码和错误信息详见附录 B
结果示例
[
ldquo4AF64012E9864C123TDE3DCrdquo 笔记路径
ldquo4AF64012E9864CDC12FTDE3rdquo
ldquo4AF64012E9864CFE23TDE3Crdquo
]
创建笔记本
URL http[baseURL]ywsopennotebookcreatejson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
name 笔记本名称 是 String
返回结果操作成功时 http状态 200并返回新创建笔记本的路径失败时
http状态 500并返回错误码和错误信息详见附录 B
结果示例
ldquopathrdquo ldquo4AF64012E9864Crdquo
删除笔记本
URL http[baseURL]ywsopennotebookdeletejson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
notebook 笔记本路径 是 String
返回结果操作成功时 http状态 200无返回数据失败时 http状态 500并
返回错误码和错误信息详见附录 B
笔记操作 API
创建笔记
URL http[baseURL]ywsopennotecreatejson
请求方式POST
Content-Typemultipartform-data
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
source 笔记来源 URL 否 String
author 笔记作者 否 String
title 笔记标题 否 String
content 笔记正文(笔记格式见附录 A) 是 String
notebook 该新建笔记所属的笔记本路径 否 String
返回结果操作成功时 http状态为 200并返回新建笔记的路径失败时 http
状态为 500并返回错误码和错误信息详见附录 B
结果示例
ldquopathrdquo ldquo4AF64012E9864CFE89D12134Erdquo
注如果第三方应用没有指定 notebook则在该第三方应用对应的默认笔记
本中创建该笔记
查看笔记
URL http[baseURL]ywsopennotegetjson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
path 笔记路径 是 String
返回结果操作成功时 http状态为 200并返回该笔记的相关信息失败时
http状态为 500并返回错误码和错误信息详见附录 B
结果示例
ldquotitlerdquo ldquo工作记录rdquo 笔记标题
ldquoauthorrdquo ldquoTomrdquo 笔记作者
ldquosourcerdquo ldquohttpnoteyoudaocomrdquo 笔记来源 URL
ldquosizerdquo ldquo1024rdquo 笔记大小包括笔记正文及附件
ldquocreate_timerdquo ldquo1323310917rdquo 笔记的创建时间单位秒
ldquomodify_timerdquo ldquo1323310949rdquo 笔记的最后修改时间单位秒
ldquocontentrdquo ldquoltpgtThis is a test noteltpgt 笔记正文
修改笔记
URL http[baseURL]ywsopennoteupdatejson
请求方式POST
Content-Typemultipartform-data
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
path 修改笔记的路径 是 String
source 修改后的笔记来源 URL 否 String
author 修改后的笔记作者 否 String
title 修改后的笔记标题 否 String
content 修改后的笔记正文(笔记格式见
附录 A)
是 String
返回结果操作成功时 http 状态为 200无返回结果失败时 http 状态为
500并返回错误码和错误信息详见附录 B
移动笔记
URL http[baseURL]ywsopennotemovejson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
path 想要移动的笔记原路径 是 String
notebook 目标笔记本的路径 是 String
返回结果操作成功时 http状态为 200返回移动后的笔记路径失败时 http
状态为 500并返回错误码和错误信息详见附录 B
结果示例
ldquopathrdquo ldquo5AB0C6B33BD1162FE89D12134Erdquo
删除笔记
URL http[baseURL]ywsopennotedeletejson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
path 想要删除的笔记原路径 是 String
返回结果操作成功时 http 状态为 200无返回结果失败时 http 状态为
500并返回错误码和错误信息详见附录 B
附件操作 API
上传附件或图片
URLhttp[baseURL]ywsopenresourceuploadjson
请求方式POST
Content-Typemultipartform-data
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
file 上传的附件文件(包括附件的文
件名类型大小数据等)
是 Multipart File附件大
小限制 25M
返回结果操作成功时 http状态为 200对于图片返回该图片的链接 URL
对于普通附件服务器会为该附件生成一个图标文件因此返回结果包括该
附件对应的链接 URL以及图标的 URL失败时 http状态为 500并返回错误码
和错误信息详见附录 B
示例
图片附件
url httpbaseURLywsopenresource28d83f547f3055
普通附件
url httpbaseURLywsopenresource28d83f547f3055 附件 URL
src httpbaseURLywsopenresource297f2bd6fa2795 图标 URL
需要注意的是在附件上传完成后使用者应该紧接着更新对应的笔记否
则不被任何笔记引用的附件将被定期的空间回收所删除
下载附件图片图标
URLhttp[baseURL]ywsopenresourcedownload
请求方式GET
是否需要用户认证是 (关于登录授权参见请求用户授权)
返回结果操作成功时response返回附件及图片的二进制流失败时 http
状态为 500并返回错误码和错误信息详见附录 B
备注
1 当打开笔记时对于笔记中的附件及图片链接只需要添加用户的 OAuth
认证信息即可以获取对应的附件及图片同理在上传附件后返回的附
件及图片链接也可以通过这种方式进行访问
2 附件及图片的下载支持断点续传
附录 A有道云笔记内容格式
笔记内容的格式采用类 HTML的标记语言绝大部分格式相关 tag均采用标
准的 HTML Tag唯一需要不同的是附件及图片 Tag在格式上图片 Tag与标准的
img tag相同一个图片资源的标记如下
ltimg src=httpnoteyoudaocomywsopenresource227f2bd6fa2795441cgt
但是由于对应的接口需要用户认证因此在获取图片资源时需要加入 OAuth
的用户认证信息
附件通常以图标在笔记中进行显示因此我们扩展了图片 Tag ltimggt除了
img 本身的 src 属性额外加入了一个属性 path其中 src 对应着该附件的图标
URL而 path则为该附件的 URL如下所示
ltimg path=httpnoteyoudaocomywsopenresource219fe604c7c90642fd8f
src=httpnoteyoudaocomywsopenresource227f2bd6fa2795441cgt
同理也需要加入 OAuth的用户认证信息才可以正常访问附件资源及其图标
附录 B错误码及错误信息说明
同理当 Open API的请求在执行时出现任何异常或错误时系统将返回 Http
500应用程序可以根据此判断请求是否成功执行当应用程序在进行 OAuth认
证或者未经认证便调用 Open API时系统会返回 OAuth错误信息OAuth的
错误码与错误信息将以 json的格式进行返回各个错误码及错误信息说明如下
错误码 错误描述及可能原因
1001 token_rejectedconsumer没有找到consumerKey错误 consumer
没有创建或者 request token或者 access token 不存在于 server中
或者没有获得授权的 token或者 token过期
1002 parameter_rejected这个会返回具体原因 key是
oauth_parameters_rejected value是一个 parameter列表
1003 version_rejectedOAuth版本号不是 10
1004 timestamp_refusedtimestamp 非 5分钟内
1005 nonce_used5分钟内该 nonce被使用
1006 parameter_absent有些参数没有发送给 server
1007 signature_invalidoauth签名异常可能原因没有签名签名方法和
签名不一致等
1008 signature_method_rejectedoauth server没有提供该签名方法
1009 access_state_error获取 token时状态混乱详细的信息会告知当前的
状态 [AUTHORIZED | REQUEST | ACCESS | INVALID]
1010 consumer_rejected该 consumer在 server中不存在或者被禁掉
或者 consumerKey改变但是还没有反应到 server的数据库中
1011 accessor_rejected由 token得到的 accessor构造异常或者 accessor
中缺失某些属性或者转换失败
1012 callback_errorrequest token传来的 callback和以后的 callback不一致
1013 callback_domain_error当限定 callback后发来的 callback与原设置
的 callback的域不相同
1014 verifier_errorVerifier不一致错误
1015 permission_denied无授权的 token或者授权后没有获取过 access
token
同理当 Open API的请求在后台执行出现异常或错误时系统也将同时错
误码与错误信息以 json 的格式一同返回应用程序可以根据错误码得到相应的
原因常见的错误码说明如下
错误码 错误描述及可能原因
206 UNKNOWN_URI错误的 URI请求
207 AUTHENTICATION_FAILURE用户认证错误
209 RESOURCE_NOT_EXIST请求的资源(笔记本笔记附件等)不存在
210 USER_SPACE_FULL用户空间已满
214 INVALID_PARAMETER错误的传入参数必须的参数为空等
220 USER_NOT_EXISTS用户不存在
221 USER_ALREADY_EXISTS用户已经存在不能重复注册
225 PARENT_NOT_EXIST笔记本尚不存在不能在该笔记本下创建笔记
231 RESOURCE_ALREADY_EXIST该笔记或者附件已经存在不能重复创建
304 NOTE_ALREADY_DELETED笔记已经被删除
307 INVALID_APPLICATION无效的第三方应用未经过用户授权或者授权
失败便通过 OpenAPI访问用户数据这个一般是使用测试环境得到了
access_token利用该 access_token访问了线上环境这两套环境是独
立的Access_token不能共用
但是如果第三方应用未经过用户授权
示例当查看笔记路径错误时
error 209
message Required note does not exist path=5AB0C6B33BD12FE89D12134E
附录 C 访问 OAuth Server的类库与包
ActionScriptFlash
oauth-as3 httpcodegooglecompoauth-as3
A flex oauth client
httpwwwarcgiscomhomeitemhtmlid=ff6ffa302ad04a7194999f2ad08250d7
CC++
QTweetLib httpgithubcomminimoogQTweetLib
libOAuth httpliboauthsourceforgenet
clojure
clj-oauth httpgithubcommattreplclj-oauth
net
oauth-dot-net httpcodegooglecompoauth-dot-net
DotNetOpenAuth httpwwwdotnetopenauthnet
Erlang
erlang-oauth httpgithubcomtimerlang-oauth
java
Scrible httpgithubcomfernandezpablo85scribe-java
oauth-signpost httpcodegooglecompoauth-signpost
javascript
oauth in js httpoauthgooglecodecomsvncodejavascript
Objective-CCocoa amp iPhone programming
OAuthCore httpbitbucketorgatebitsoauthcore
MPOAuthConnection httpcodegooglecompmpoauthconnection
Objective-C OAuth httpoauthgooglecodecomsvncodeobj-c
Perl
NetOAuth httpoauthgooglecodecomsvncodeperl
PHP
tmhOAuth httpgithubcomthemattharristmhOAuth
oauth-php httpcodegooglecompoauth-php
Python
python-oauth2 httpgithubcombrosnerpython-oauth2
Qt
qOauth httpgithubcomayoyqoauth
Ruby
Oauth ruby gem httpoauthrubyforgeorg
Scala
DataBinder Dispatch httpdispatchdatabindernetAbout
附录 D Oauth签名加密 oauth_signature
1 加密内容是
a 请求方法名例如 GET POST等 加密时方法名大写并进行特殊替换
(详见 3)
b url (query param之前的部分不包括 )Http或者 https需要全部小
写 http如果带有 80端口或者 https带有 443端口需要将其省略
其他端口则不能省略例如
Httplocal9999requestToken
httplocal9999requestToken
Httplocal80requestToken
httplocalrequestToken
Httpslocal443requestToken
httpslocal requestToken
c 参数(query param中的或者 header中的 key-value对) 首先将这些参数
进行特殊替换后按字典序排序升序排列如果两个 key相同则以
value特殊替换后字典序为准key与 value之间使用rdquo=rdquo连接如果
value==null则使用rdquordquo替代两个参数对之间使用rdquoamprdquo连接连接后形成
的最终字符串的开头和结尾没有rdquoamprdquo
d 字典序字符串比较大小伪代码
Int compare(string a string b)
Int min_len = min(len(a) len(b))
For I to min_len
If (a[i] = b[i])
Return a[i] ndash b[i]
Return len(a) ndash len(b)
将以上 abc三部分进行特殊替换后使用amp连接最终形成的字符串的
开头和结尾都没有rdquoamprdquo这就是加密内容
2 加密的 key是 consumerSecret + amp + TokenSecret 如果 TokenSecret还没有
得到则使用rdquordquo consumerSecret和 TokenSecret需先做特殊替换然后
再进行签名
3 特殊替换是将 String进行 URL编码后将rdquo+rdquo替换为rdquo20rdquo将rdquordquo替换
为rdquo2Ardquo将rdquo7Erdquo替换为rdquo~rdquo
4 签名方法可以使用 HMAC-SHA1PLAINTEXT RSA_SHA1三种其中
PLAINTEXT为 2中的 key 该方法不提倡使用
得到签名内容后使用 Base64进行编码编码后的字符串即为 oauth_signature
概述
有道云笔记旨在以云存储技术帮助用户建立一个可以轻松访问安全存储的
云笔记空间解决了个人资料和信息跨平台跨地点的管理问题目前已经提供了
桌面版网页版以及部分手机型号的版本但是用户对笔记的需求不仅仅局限于
这几种情形对于很多非笔记应用用户仍然可能有跨平台跨设备的存储需求
通过开放的 API第三方应用只需要进行简单的开发就可以通过标准的 web协
议对有道云笔记的数据进行安全的访问与修改而不需要搭设和维护运存储服
务这大大降低了第三方的开发与运营成本从而将更多的精力专注于应用本身
本文档从技术角度对有道云笔记的开放 API进行说明从而方便开发者的理
解和使用
数据模型
目前有道云笔记的数据模型包括用户笔记本笔记以及附件四部分下面
将对它们分别进行说明
用户
每一个有道云笔记的账号(目前我们使用网易通行证作为账号但是以后将
允许使用其它网站的开放认证账号例如新浪微博账号人人网账号)都在系统
中对应着一份用户信息包括该用户邮箱笔记总空间当前使用空间默认笔
记本在线时间以及注册时间上次修改时间等一系列信息
笔记本
用户通过笔记本对所有笔记进行组织管理每一篇笔记必须属于某一个笔记
本同时为了方便用户的区分与定位每个笔记本也必须具有唯一的名字目前
有道云笔记仅支持一层笔记本结构而不支持笔记本的多层嵌套
对于同一篇笔记可以在两个笔记本之间进行转移但是却不允许出现在两
个笔记本中此外每个用户在任何时候都有一个笔记本被标记为默认笔记本
如果一个笔记在创建时没有特别指明笔记本它将被放入默认笔记本中删除一
个笔记本将删除该笔记本下的所有笔记
虽然有道云笔记的客户端同时提供了同步笔记本与本地笔记本两种类型但
是由于本地笔记本仅存储在用户的本机而没有上传至服务器因此开放 API只能
创建或者访问用户同步笔记本中的笔记
笔记
一篇笔记由一段超文本以及相关联的附件(例如图片文本PPTPDF等)
所组成其中超文本的内容按照一种标记语言的格式进行存储每个附件所在的
位置都对应着一个 tag包含着该附件路径从而可以根据该信息找到对应附件
的数据同时每个笔记还包含一些属性信息例如题目作者来源 URL以及
创建修改时间等这些信息可以用来对笔记进行查找过滤以及排序
当一个笔记被删除时它将被放入回收站回收站中的笔记在一定的时间内
仍然可以访问(Open API不可以访问删除的笔记)但是不可以进行编辑如果
没有进行恢复回收站的笔记将在一定的时间后(目前为两个月)被清除
笔记标记语言格式的详细说明见附录 A
附件
笔记附件是附属于笔记的二进制数据无法脱离笔记单独存在因此如果仅
上传附件而不添加相应的笔记则该附件会被定期的空间回收所删除笔记附件
类似于邮件的附件但是与邮件的附件不同的是笔记的附件没有与笔记的内容
进行整体编码而只是在笔记内容超文本的对应位置放置了一个 tag附件的数
据则单独进行存储因此如果将附件 tag在两个笔记之间进行拷贝这两个笔记
将共享同一个附件而对附件的修改也将同时反映在两个笔记之中不过目前我
们尚不提供附件修改的 API还不存在这样的问题随着 API的晚上以后将提
供类似的 API因此如果第三方应用希望避免这种情况需要自行对附件拷贝进
行处理另一方面如果共享附件的两篇笔记中有一篇笔记被删除不会对另外
一篇笔记及其附件造成影响
目前笔记的附件支持除了 execomcmdbatsys以外的所有文件格式
大小限制为 25MB
授权机制
为了对用户的数据进行保护大部分API的访问都需要获得用户的身份信息
我们采用 OAuth 的方式对第三方应用进行授权只有经过用户授权的应用才可
以对用户的数据进行访问目前我们支持 OAuth 10aOAuth的官方技术说明可
参看 httpoauthnet
申请 Consumer Key
对于所有需要使用 Open API的应用在使用 Open API之前首先要在系统内
申请一个应用程序申请者需要提交申请人姓名应用名称callback URL以及
是否限制 callbackURL 等信息我们会生成相应 的 ConsumerKey 和
ConsumerSecret作为每个应用的身份标识应用名称和 ConsumerKey在系统中
均是唯一的在进行请求时第三方应用需要将 ConsumerKey加入请求中而系
统收到请求后便可以根据 ConsumerKey 和 ConsumerSecret 对请求进行验证与
记录
目前我们采用网站申请的方式申请网址httpnoteyoudaocomopen
也可以采用邮件申请的方式申请人可直接发送邮件至 noteapirdneteasecom
邮件内容示例如下
App名称pYNote
组织类型个人公司
姓名张三XX科技有限公司
email XXX163com
homelinkhttpwwwyoudaocom
应用类型浏览器插件(应用)IOS appAndroid appWindows appMac os app
其它请在详细描述中说明
详细描述Linux下基于 Python的有道云笔记客户端
另外还需要 2种规格的 LOGO6060177177JPG格式即可
请求用户授权
授权流程
在拿到 ConsumerKey 和 ConsumerSecret 以后应用程序便可以结合
ConsumerKey 申请一个 request_token 和 request_secret发送的内容应该有
ConsumerSecret的签名
应用程序再次用 request_token 和 ConsumerKey 来申请用户授权该请求内
容应该由 ConsumerSecret 和 request_secret 共同签名授权时需要用户在
OauthServer 提供的页面中输入用户名密码等信息进行授权操作已经登录过的
用户可以直接进行授权操作用户授权之后会返回 request_token和 verifier 此
时的 request_token在 OauthServer中已经授权
授权之后应用程序就可以使用 request_token 申请 access_token 和
access_secret该请求内容同样要使用 ConsumerSecret 和 request_secret 共同签
名
如果以上步骤中可能会因为超时或者发送内容不符造成错误OAuth会返回
错误信息给应用程序
详细流程见图 211
开始
结束
请求是否合法
请求requst_token
返回错误信息
生成request_token
Y
返回授权的request_tokensecr
et verifier等信息
请求授权
对request_token授权生成
verifier(PIN码)
request_token
是否存在
Y
请求是否合法
N
请求access_token
生成access_token
Y
图 211 授权流程图
授权请求参数方法和返回值
下面将介绍如何使用 OauthServer服务得到 access_token和 access_secret下
面的文字中[baseURL]指代 OauthServer 的 URL对于线上环境该 baseURL
即为 httpnoteyoudaocom而对于 sandbox 测试环境该 baseURL 为
httpsandboxnoteyoudaocom这里使用 HTTP Header设置参数 Header
name 设 为 Authorization Header value 设 为 OAuth[ 空
格][parameterName=rdquovaluerdquo][空格][ parameterName=rdquovaluerdquo]hellip 值得注意
的是 parameterName 和 value 必须进行 URL 编码并且在 URL 编码后还要
将 rdquo+rdquo替换为 rdquo20rdquo将rdquordquo替换为 rdquo2Ardquo将 rdquo7Erdquo替换为 rdquo~rdquo例如请求
authorized token时 HTTP header中的 value是
OAuth[ 空 格 ]oauth_token=29cc36314495ee1cf55ebf26ca9711bc[ 空 格 ]
oauth_consumer_key=407d014e17ad5cd02f3e0a55fcb198af [ 空
格 ]oauth_signature_method=HMAC-SHA1[ 空
格 ]oauth_timestamp=1323325710[ 空
格 ]oauth_nonce=278825208972307[ 空 格 ]oauth_version=10[ 空 格 ]
oauth_signature=x8E7wrAmn6GyHv4aldWSo1M2ShU3D 注意其中双引
号rdquordquo是必须的 发送请求时这些参数可以是无序的但是签名时这些参
数有一定的顺序详见附录 D
以下各个请求正确时返回值 content-type 为 textplain 返回
key=value[空格]key=value
以下各个请求错误时会返回错误信息该信息包含 error message等
error是错误码message包含更详尽的错误信息另外特殊错误时还可能返
回更多信息详见附录 B
请求 request_token
URL[baseURL]oauthrequest_token
请求方式GET
请求参数
参数名 参数说明
oauth_callback 回调 url该 url可以为 oob代表不回调另外 url还可
以跟其他参数
oauth_consumer_key 申请应用时拿到的 consumerKey
oauth_signature_method 签名方法支持 HMAC-SHA1
oauth_timestamp 时间戳当前时间单位毫秒
oauth_nonce 随机串为了防止重放攻击5分钟内同一用户同一应用同
一时间发来的请求中 oauth_nonce应不同
oauth_version 10
oauth_signature 签名使用 consumerSecret +rsquoamprsquo作为签名的 key 而
签名的内容是除 oath_signature以外的请求 url内容
计算签名完毕后使用 base64编码
正确时返回oauth_token_secret(授权流程中的 request_secret 用于申请
access_token 时签名) oauth_token(授权流程中的 requset_token 用于
authorize请求和 access_token请求)和 oauth_callback_confirmed(boolean
值)
错误时返回 error message error是 error code message是错误信息以 json
串形式返回
发送示例
用 curl来举例 请求信息类似于
curl ndashH ldquoAuthorization OAuth oauth_callback=rdquooobrdquo
oauth_consumer_key=rdquo7a23b1eaf487060deaa5660b323c341brdquo
oauth_signature_method=rdquoHMAC-SHA1rdquo oauth_timestamp=rdquo1321847131rdquo
oauth_nonce=rdquo439563436203139rdquo oauth_version=rdquo10rdquordquo
ldquohttpsandboxnoteyoudaocomoauthrequest_tokenrdquo
但是需要注意的是各个 key-value对都需要使用 OAuth编码 详见附录 D
备注
示例中的签名内容大致为(参数顺序可能有变化详见附录 D的签名过程)
GETamp
httpsandboxnoteyoudaocomoauthrequest_tokenampoauth_callback=oobampo
auth_consumer_key=7a23b1eaf487060deaa5660b323c341bampoauth_signature_
method=HMAC-SHA1ampoauth_timestamp=1321847131ampoauth_nonce=4395634
36203139ampoauth_version=10
具体签名方法详见附录 D
请求授权
URL [baseURL]oauthauthorize
请求方式GET
请求参数该处的参数必须以 query string的形式发送
参数名 参数说明
oauth_token 请求 request_token时返回的 oauth_token
正确时返回oauth_token(授权后的 request_token) 和 oauth_verifier
错误时返回error message
发送示例
GET http
sandboxnoteyoudaocomoauthauthorizeoauth_token=5420db084cc41d768d885
a53f7b2c1a6
备注如果 oauth_callback为 oob则不会回调用户会在 Oauth Server页面上
看到 pin 码用户需要手工将 pin 码粘帖到 application 中才能申请到
AccessToken应用请求 authorize时如果请求携带了网易或者有道的 cookie
则将直接询问用户是否授权否则会重新定向到网易的通行证页面
请求 access_token
URL[baseURL]oauthaccess_token
请求方式GET
请求参数
参数名 参数说明
oauth_consumer_key 回调 url
oauth_token request_token时返回的 oauth_token
oauth_verifier Authorize请求时发送回来的 oauth_verifier或者是
OauthServer页面显示的 Pin码
oauth_signature_method 签名方法支持 HMAC-SHA1
oauth_timestamp 时间戳当前时间单位毫秒
oauth_nonce 随机串为了防止重放攻击5分钟内同一用户同一应用同
一时间发来的请求中 oauth_nonce应不同
oauth_version 10
oauth_signature 使用 consumerSecret + rsquoamprsquo + oauth_token_secret
字串作为key 而签名的内容是除oauth_signature以外
的请求 url内容计算签名完毕后使用 base64编码
正确时返回oauth_token_secret (授权流程中的 access_secret)oauth_token
(授权流程中的 access_token)
错误时返回error message
发送示例 http header的例子
curl ndashH ldquoAuthorization OAuth
oauth_verifier=rdquo8714fb943a28d7faffec3265e96d85cdrdquo
oauth_token=rdquob348d10a0f45a4cf6936381d6c9fb00frdquo
oauth_consumer_key=rdquo7a23b1eaf487060deaa5660b323c341brdquo
oauth_signature_method=rdquoHMAC-SHA1rdquo oauth_timestamp=rdquo1321857128rdquo
oauth_nonce=rdquo449560105422526rdquo oauth_version=rdquo10rdquo
oauth_signature=rdquoS8yxdpLIA7MiFVDE4OzSDoo2F62FI3Drdquordquo
ldquohttpsandboxnoteyoudaocomoauthaccess_tokenrdquo
访问 OpenAPI
由 223 返回的 oauth_token 将用于 OpenAPI 的请求 consumerSecret + rsquoamprsquo +
oauth_token_secret 将 用 作 签 名 例 如 请 求 创 建 笔 记 本
http[baseURL]ywsopennotebookcreatejson则应在请求创建笔记中添加各
种参数(创建笔记本的其他参数按文档要求不变)如果没有则会返回 error
和 message(此处的 error和 message会放入到 json串中error是错误码 message
是具体错误信息)不会执行任何 OpenAPI操作
例如执行创建笔记本操作参数 name需和 oauth 的其他值一起进行签名
但是不应该将 name 放入 header 中并且发送 post 请求的 Content-Type 为
applicationx-www-form-urlencoded其他参数填入 http content 域Oauth 参数
放入 Authorization Header域否则可能会出现错误
对于上传笔记或者附件图片的 open API 中post 请求的 Content-Type 为
multipartform-data非 oauth参数均不参与签名非 oauth参数填入 http content
域Oauth参数放入 Authorization Header域否则可能会出现错误
对于使用 GET请求 http[baseURL]ywsopenusergetjson需要将 oauth参
数和非 oauth参数一起放入 url参数中签名时需注意参数顺序发送请求时参
数可以无序
POST
httpnoteyoudaocomywsopennotecreatejson
Header 中 Authorization的值为
OAuth[ 空 格 ]oauth_token=29cc36314495ee1cf55ebf26ca9711bc
oauth_consumer_key=407d014e17ad5cd02f3e0a55fcb198af
oauth_signature_method=HMAC-SHA1 oauth_timestamp=1323327110
oauth_nonce=280224628487931 oauth_version=10
oauth_signature=rXpd0apk82wMAZLun2FDSUt1wbQE3D
最终 Header类似于
Authorization=OAuth20oauth_token3D2229cc36314495ee1cf55ebf26ca
9711bc222C20oauth_consumer_key3D22407d014e17ad5cd02f3e0a55fcb198
af222C20oauth_signature_method3D22HMAC-SHA1222C20oauth_timest
amp3D221323327041222C20oauth_nonce3D22280155519121203222C20
oauth_version3D2210222C20oauth_signature3D22E252F8dFmTFGTmdC
FE2rnJ8f252Bkzw9c253D22
签名的具体方法详见附录 D访问 Oauth的类库包详见附录 C
用户操作 API
查看用户信息
URLhttp[baseURL]ywsopenusergetjson
请求方式GET
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数无
返回结果操作成功时 http 状态为 200并用户信息失败时 http 状态为
500并返回错误码和错误信息详见附录 B
结果示例
ldquouserrdquo ldquotest163comrdquo 用户 ID
ldquototal_sizerdquo ldquo10293736383rdquo 用户总的空间大小单位字节
ldquoused_sizerdquo ldquo1024rdquo 用户已经使用了的空间大小单位字节
ldquoregister_timerdquo ldquo1323310917650rdquo 用户注册时间单位毫秒
ldquolast_login_timerdquo ldquo1323310949120rdquo 用户最后登录时间单位毫秒
ldquolast_modify_timerdquo ldquo1323310978120rdquo 用户最后修改时间单位毫秒
ldquodefault_notebookrdquo ldquoAB384D734rdquo 该应用的默认笔记本
注对于每个第三方应用都分别在用户的笔记空间中对应一个默认笔记本
笔记本名在申请应用时指定在使用 OpenAPI创建笔记时如果第三方应用
不指定笔记本则自动创建在该默认笔记本中
笔记本操作 API
查看用户全部笔记本
URLhttp[baseURL]ywsopennotebookalljson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数无
返回结果操作成功时 http状态为 200并返回笔记本列表失败时 http状
态为 500并返回错误码和错误信息详见附录 B
结果示例
[
ldquopathrdquo ldquo4AF64012E9864Crdquo 笔记本的路径
ldquonamerdquo ldquo笔记本 1rdquo 笔记本的名称
ldquonotes_numrdquo ldquo3rdquo 该笔记本中笔记的数目
ldquocreate_timerdquo ldquo1323310917rdquo 笔记本的创建时间单位秒
ldquomodify_timerdquo ldquo1323310949rdquo 笔记本的最后修改时间单位秒
ldquopathrdquo ldquo5AB0C6B33BD1162rdquo
ldquonamerdquo ldquo笔记本 2rdquo
ldquonotes_numrdquo ldquo10rdquo
ldquocreate_timerdquo ldquo1323311244rdquo
ldquomodify_timerdquo ldquo1323310349rdquo
]
列出笔记本下的笔记
URLhttp[baseURL]ywsopennotebooklistjson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
notebook 笔记本路径 是 String
返回结果操作成功时 http状态为 200并返回该笔记本下的笔记列表(只
有笔记路径笔记内容需要通过笔记接口获取)失败时 http状态 500并返
回错误码和错误信息详见附录 B
结果示例
[
ldquo4AF64012E9864C123TDE3DCrdquo 笔记路径
ldquo4AF64012E9864CDC12FTDE3rdquo
ldquo4AF64012E9864CFE23TDE3Crdquo
]
创建笔记本
URL http[baseURL]ywsopennotebookcreatejson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
name 笔记本名称 是 String
返回结果操作成功时 http状态 200并返回新创建笔记本的路径失败时
http状态 500并返回错误码和错误信息详见附录 B
结果示例
ldquopathrdquo ldquo4AF64012E9864Crdquo
删除笔记本
URL http[baseURL]ywsopennotebookdeletejson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
notebook 笔记本路径 是 String
返回结果操作成功时 http状态 200无返回数据失败时 http状态 500并
返回错误码和错误信息详见附录 B
笔记操作 API
创建笔记
URL http[baseURL]ywsopennotecreatejson
请求方式POST
Content-Typemultipartform-data
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
source 笔记来源 URL 否 String
author 笔记作者 否 String
title 笔记标题 否 String
content 笔记正文(笔记格式见附录 A) 是 String
notebook 该新建笔记所属的笔记本路径 否 String
返回结果操作成功时 http状态为 200并返回新建笔记的路径失败时 http
状态为 500并返回错误码和错误信息详见附录 B
结果示例
ldquopathrdquo ldquo4AF64012E9864CFE89D12134Erdquo
注如果第三方应用没有指定 notebook则在该第三方应用对应的默认笔记
本中创建该笔记
查看笔记
URL http[baseURL]ywsopennotegetjson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
path 笔记路径 是 String
返回结果操作成功时 http状态为 200并返回该笔记的相关信息失败时
http状态为 500并返回错误码和错误信息详见附录 B
结果示例
ldquotitlerdquo ldquo工作记录rdquo 笔记标题
ldquoauthorrdquo ldquoTomrdquo 笔记作者
ldquosourcerdquo ldquohttpnoteyoudaocomrdquo 笔记来源 URL
ldquosizerdquo ldquo1024rdquo 笔记大小包括笔记正文及附件
ldquocreate_timerdquo ldquo1323310917rdquo 笔记的创建时间单位秒
ldquomodify_timerdquo ldquo1323310949rdquo 笔记的最后修改时间单位秒
ldquocontentrdquo ldquoltpgtThis is a test noteltpgt 笔记正文
修改笔记
URL http[baseURL]ywsopennoteupdatejson
请求方式POST
Content-Typemultipartform-data
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
path 修改笔记的路径 是 String
source 修改后的笔记来源 URL 否 String
author 修改后的笔记作者 否 String
title 修改后的笔记标题 否 String
content 修改后的笔记正文(笔记格式见
附录 A)
是 String
返回结果操作成功时 http 状态为 200无返回结果失败时 http 状态为
500并返回错误码和错误信息详见附录 B
移动笔记
URL http[baseURL]ywsopennotemovejson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
path 想要移动的笔记原路径 是 String
notebook 目标笔记本的路径 是 String
返回结果操作成功时 http状态为 200返回移动后的笔记路径失败时 http
状态为 500并返回错误码和错误信息详见附录 B
结果示例
ldquopathrdquo ldquo5AB0C6B33BD1162FE89D12134Erdquo
删除笔记
URL http[baseURL]ywsopennotedeletejson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
path 想要删除的笔记原路径 是 String
返回结果操作成功时 http 状态为 200无返回结果失败时 http 状态为
500并返回错误码和错误信息详见附录 B
附件操作 API
上传附件或图片
URLhttp[baseURL]ywsopenresourceuploadjson
请求方式POST
Content-Typemultipartform-data
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
file 上传的附件文件(包括附件的文
件名类型大小数据等)
是 Multipart File附件大
小限制 25M
返回结果操作成功时 http状态为 200对于图片返回该图片的链接 URL
对于普通附件服务器会为该附件生成一个图标文件因此返回结果包括该
附件对应的链接 URL以及图标的 URL失败时 http状态为 500并返回错误码
和错误信息详见附录 B
示例
图片附件
url httpbaseURLywsopenresource28d83f547f3055
普通附件
url httpbaseURLywsopenresource28d83f547f3055 附件 URL
src httpbaseURLywsopenresource297f2bd6fa2795 图标 URL
需要注意的是在附件上传完成后使用者应该紧接着更新对应的笔记否
则不被任何笔记引用的附件将被定期的空间回收所删除
下载附件图片图标
URLhttp[baseURL]ywsopenresourcedownload
请求方式GET
是否需要用户认证是 (关于登录授权参见请求用户授权)
返回结果操作成功时response返回附件及图片的二进制流失败时 http
状态为 500并返回错误码和错误信息详见附录 B
备注
1 当打开笔记时对于笔记中的附件及图片链接只需要添加用户的 OAuth
认证信息即可以获取对应的附件及图片同理在上传附件后返回的附
件及图片链接也可以通过这种方式进行访问
2 附件及图片的下载支持断点续传
附录 A有道云笔记内容格式
笔记内容的格式采用类 HTML的标记语言绝大部分格式相关 tag均采用标
准的 HTML Tag唯一需要不同的是附件及图片 Tag在格式上图片 Tag与标准的
img tag相同一个图片资源的标记如下
ltimg src=httpnoteyoudaocomywsopenresource227f2bd6fa2795441cgt
但是由于对应的接口需要用户认证因此在获取图片资源时需要加入 OAuth
的用户认证信息
附件通常以图标在笔记中进行显示因此我们扩展了图片 Tag ltimggt除了
img 本身的 src 属性额外加入了一个属性 path其中 src 对应着该附件的图标
URL而 path则为该附件的 URL如下所示
ltimg path=httpnoteyoudaocomywsopenresource219fe604c7c90642fd8f
src=httpnoteyoudaocomywsopenresource227f2bd6fa2795441cgt
同理也需要加入 OAuth的用户认证信息才可以正常访问附件资源及其图标
附录 B错误码及错误信息说明
同理当 Open API的请求在执行时出现任何异常或错误时系统将返回 Http
500应用程序可以根据此判断请求是否成功执行当应用程序在进行 OAuth认
证或者未经认证便调用 Open API时系统会返回 OAuth错误信息OAuth的
错误码与错误信息将以 json的格式进行返回各个错误码及错误信息说明如下
错误码 错误描述及可能原因
1001 token_rejectedconsumer没有找到consumerKey错误 consumer
没有创建或者 request token或者 access token 不存在于 server中
或者没有获得授权的 token或者 token过期
1002 parameter_rejected这个会返回具体原因 key是
oauth_parameters_rejected value是一个 parameter列表
1003 version_rejectedOAuth版本号不是 10
1004 timestamp_refusedtimestamp 非 5分钟内
1005 nonce_used5分钟内该 nonce被使用
1006 parameter_absent有些参数没有发送给 server
1007 signature_invalidoauth签名异常可能原因没有签名签名方法和
签名不一致等
1008 signature_method_rejectedoauth server没有提供该签名方法
1009 access_state_error获取 token时状态混乱详细的信息会告知当前的
状态 [AUTHORIZED | REQUEST | ACCESS | INVALID]
1010 consumer_rejected该 consumer在 server中不存在或者被禁掉
或者 consumerKey改变但是还没有反应到 server的数据库中
1011 accessor_rejected由 token得到的 accessor构造异常或者 accessor
中缺失某些属性或者转换失败
1012 callback_errorrequest token传来的 callback和以后的 callback不一致
1013 callback_domain_error当限定 callback后发来的 callback与原设置
的 callback的域不相同
1014 verifier_errorVerifier不一致错误
1015 permission_denied无授权的 token或者授权后没有获取过 access
token
同理当 Open API的请求在后台执行出现异常或错误时系统也将同时错
误码与错误信息以 json 的格式一同返回应用程序可以根据错误码得到相应的
原因常见的错误码说明如下
错误码 错误描述及可能原因
206 UNKNOWN_URI错误的 URI请求
207 AUTHENTICATION_FAILURE用户认证错误
209 RESOURCE_NOT_EXIST请求的资源(笔记本笔记附件等)不存在
210 USER_SPACE_FULL用户空间已满
214 INVALID_PARAMETER错误的传入参数必须的参数为空等
220 USER_NOT_EXISTS用户不存在
221 USER_ALREADY_EXISTS用户已经存在不能重复注册
225 PARENT_NOT_EXIST笔记本尚不存在不能在该笔记本下创建笔记
231 RESOURCE_ALREADY_EXIST该笔记或者附件已经存在不能重复创建
304 NOTE_ALREADY_DELETED笔记已经被删除
307 INVALID_APPLICATION无效的第三方应用未经过用户授权或者授权
失败便通过 OpenAPI访问用户数据这个一般是使用测试环境得到了
access_token利用该 access_token访问了线上环境这两套环境是独
立的Access_token不能共用
但是如果第三方应用未经过用户授权
示例当查看笔记路径错误时
error 209
message Required note does not exist path=5AB0C6B33BD12FE89D12134E
附录 C 访问 OAuth Server的类库与包
ActionScriptFlash
oauth-as3 httpcodegooglecompoauth-as3
A flex oauth client
httpwwwarcgiscomhomeitemhtmlid=ff6ffa302ad04a7194999f2ad08250d7
CC++
QTweetLib httpgithubcomminimoogQTweetLib
libOAuth httpliboauthsourceforgenet
clojure
clj-oauth httpgithubcommattreplclj-oauth
net
oauth-dot-net httpcodegooglecompoauth-dot-net
DotNetOpenAuth httpwwwdotnetopenauthnet
Erlang
erlang-oauth httpgithubcomtimerlang-oauth
java
Scrible httpgithubcomfernandezpablo85scribe-java
oauth-signpost httpcodegooglecompoauth-signpost
javascript
oauth in js httpoauthgooglecodecomsvncodejavascript
Objective-CCocoa amp iPhone programming
OAuthCore httpbitbucketorgatebitsoauthcore
MPOAuthConnection httpcodegooglecompmpoauthconnection
Objective-C OAuth httpoauthgooglecodecomsvncodeobj-c
Perl
NetOAuth httpoauthgooglecodecomsvncodeperl
PHP
tmhOAuth httpgithubcomthemattharristmhOAuth
oauth-php httpcodegooglecompoauth-php
Python
python-oauth2 httpgithubcombrosnerpython-oauth2
Qt
qOauth httpgithubcomayoyqoauth
Ruby
Oauth ruby gem httpoauthrubyforgeorg
Scala
DataBinder Dispatch httpdispatchdatabindernetAbout
附录 D Oauth签名加密 oauth_signature
1 加密内容是
a 请求方法名例如 GET POST等 加密时方法名大写并进行特殊替换
(详见 3)
b url (query param之前的部分不包括 )Http或者 https需要全部小
写 http如果带有 80端口或者 https带有 443端口需要将其省略
其他端口则不能省略例如
Httplocal9999requestToken
httplocal9999requestToken
Httplocal80requestToken
httplocalrequestToken
Httpslocal443requestToken
httpslocal requestToken
c 参数(query param中的或者 header中的 key-value对) 首先将这些参数
进行特殊替换后按字典序排序升序排列如果两个 key相同则以
value特殊替换后字典序为准key与 value之间使用rdquo=rdquo连接如果
value==null则使用rdquordquo替代两个参数对之间使用rdquoamprdquo连接连接后形成
的最终字符串的开头和结尾没有rdquoamprdquo
d 字典序字符串比较大小伪代码
Int compare(string a string b)
Int min_len = min(len(a) len(b))
For I to min_len
If (a[i] = b[i])
Return a[i] ndash b[i]
Return len(a) ndash len(b)
将以上 abc三部分进行特殊替换后使用amp连接最终形成的字符串的
开头和结尾都没有rdquoamprdquo这就是加密内容
2 加密的 key是 consumerSecret + amp + TokenSecret 如果 TokenSecret还没有
得到则使用rdquordquo consumerSecret和 TokenSecret需先做特殊替换然后
再进行签名
3 特殊替换是将 String进行 URL编码后将rdquo+rdquo替换为rdquo20rdquo将rdquordquo替换
为rdquo2Ardquo将rdquo7Erdquo替换为rdquo~rdquo
4 签名方法可以使用 HMAC-SHA1PLAINTEXT RSA_SHA1三种其中
PLAINTEXT为 2中的 key 该方法不提倡使用
得到签名内容后使用 Base64进行编码编码后的字符串即为 oauth_signature
是由于本地笔记本仅存储在用户的本机而没有上传至服务器因此开放 API只能
创建或者访问用户同步笔记本中的笔记
笔记
一篇笔记由一段超文本以及相关联的附件(例如图片文本PPTPDF等)
所组成其中超文本的内容按照一种标记语言的格式进行存储每个附件所在的
位置都对应着一个 tag包含着该附件路径从而可以根据该信息找到对应附件
的数据同时每个笔记还包含一些属性信息例如题目作者来源 URL以及
创建修改时间等这些信息可以用来对笔记进行查找过滤以及排序
当一个笔记被删除时它将被放入回收站回收站中的笔记在一定的时间内
仍然可以访问(Open API不可以访问删除的笔记)但是不可以进行编辑如果
没有进行恢复回收站的笔记将在一定的时间后(目前为两个月)被清除
笔记标记语言格式的详细说明见附录 A
附件
笔记附件是附属于笔记的二进制数据无法脱离笔记单独存在因此如果仅
上传附件而不添加相应的笔记则该附件会被定期的空间回收所删除笔记附件
类似于邮件的附件但是与邮件的附件不同的是笔记的附件没有与笔记的内容
进行整体编码而只是在笔记内容超文本的对应位置放置了一个 tag附件的数
据则单独进行存储因此如果将附件 tag在两个笔记之间进行拷贝这两个笔记
将共享同一个附件而对附件的修改也将同时反映在两个笔记之中不过目前我
们尚不提供附件修改的 API还不存在这样的问题随着 API的晚上以后将提
供类似的 API因此如果第三方应用希望避免这种情况需要自行对附件拷贝进
行处理另一方面如果共享附件的两篇笔记中有一篇笔记被删除不会对另外
一篇笔记及其附件造成影响
目前笔记的附件支持除了 execomcmdbatsys以外的所有文件格式
大小限制为 25MB
授权机制
为了对用户的数据进行保护大部分API的访问都需要获得用户的身份信息
我们采用 OAuth 的方式对第三方应用进行授权只有经过用户授权的应用才可
以对用户的数据进行访问目前我们支持 OAuth 10aOAuth的官方技术说明可
参看 httpoauthnet
申请 Consumer Key
对于所有需要使用 Open API的应用在使用 Open API之前首先要在系统内
申请一个应用程序申请者需要提交申请人姓名应用名称callback URL以及
是否限制 callbackURL 等信息我们会生成相应 的 ConsumerKey 和
ConsumerSecret作为每个应用的身份标识应用名称和 ConsumerKey在系统中
均是唯一的在进行请求时第三方应用需要将 ConsumerKey加入请求中而系
统收到请求后便可以根据 ConsumerKey 和 ConsumerSecret 对请求进行验证与
记录
目前我们采用网站申请的方式申请网址httpnoteyoudaocomopen
也可以采用邮件申请的方式申请人可直接发送邮件至 noteapirdneteasecom
邮件内容示例如下
App名称pYNote
组织类型个人公司
姓名张三XX科技有限公司
email XXX163com
homelinkhttpwwwyoudaocom
应用类型浏览器插件(应用)IOS appAndroid appWindows appMac os app
其它请在详细描述中说明
详细描述Linux下基于 Python的有道云笔记客户端
另外还需要 2种规格的 LOGO6060177177JPG格式即可
请求用户授权
授权流程
在拿到 ConsumerKey 和 ConsumerSecret 以后应用程序便可以结合
ConsumerKey 申请一个 request_token 和 request_secret发送的内容应该有
ConsumerSecret的签名
应用程序再次用 request_token 和 ConsumerKey 来申请用户授权该请求内
容应该由 ConsumerSecret 和 request_secret 共同签名授权时需要用户在
OauthServer 提供的页面中输入用户名密码等信息进行授权操作已经登录过的
用户可以直接进行授权操作用户授权之后会返回 request_token和 verifier 此
时的 request_token在 OauthServer中已经授权
授权之后应用程序就可以使用 request_token 申请 access_token 和
access_secret该请求内容同样要使用 ConsumerSecret 和 request_secret 共同签
名
如果以上步骤中可能会因为超时或者发送内容不符造成错误OAuth会返回
错误信息给应用程序
详细流程见图 211
开始
结束
请求是否合法
请求requst_token
返回错误信息
生成request_token
Y
返回授权的request_tokensecr
et verifier等信息
请求授权
对request_token授权生成
verifier(PIN码)
request_token
是否存在
Y
请求是否合法
N
请求access_token
生成access_token
Y
图 211 授权流程图
授权请求参数方法和返回值
下面将介绍如何使用 OauthServer服务得到 access_token和 access_secret下
面的文字中[baseURL]指代 OauthServer 的 URL对于线上环境该 baseURL
即为 httpnoteyoudaocom而对于 sandbox 测试环境该 baseURL 为
httpsandboxnoteyoudaocom这里使用 HTTP Header设置参数 Header
name 设 为 Authorization Header value 设 为 OAuth[ 空
格][parameterName=rdquovaluerdquo][空格][ parameterName=rdquovaluerdquo]hellip 值得注意
的是 parameterName 和 value 必须进行 URL 编码并且在 URL 编码后还要
将 rdquo+rdquo替换为 rdquo20rdquo将rdquordquo替换为 rdquo2Ardquo将 rdquo7Erdquo替换为 rdquo~rdquo例如请求
authorized token时 HTTP header中的 value是
OAuth[ 空 格 ]oauth_token=29cc36314495ee1cf55ebf26ca9711bc[ 空 格 ]
oauth_consumer_key=407d014e17ad5cd02f3e0a55fcb198af [ 空
格 ]oauth_signature_method=HMAC-SHA1[ 空
格 ]oauth_timestamp=1323325710[ 空
格 ]oauth_nonce=278825208972307[ 空 格 ]oauth_version=10[ 空 格 ]
oauth_signature=x8E7wrAmn6GyHv4aldWSo1M2ShU3D 注意其中双引
号rdquordquo是必须的 发送请求时这些参数可以是无序的但是签名时这些参
数有一定的顺序详见附录 D
以下各个请求正确时返回值 content-type 为 textplain 返回
key=value[空格]key=value
以下各个请求错误时会返回错误信息该信息包含 error message等
error是错误码message包含更详尽的错误信息另外特殊错误时还可能返
回更多信息详见附录 B
请求 request_token
URL[baseURL]oauthrequest_token
请求方式GET
请求参数
参数名 参数说明
oauth_callback 回调 url该 url可以为 oob代表不回调另外 url还可
以跟其他参数
oauth_consumer_key 申请应用时拿到的 consumerKey
oauth_signature_method 签名方法支持 HMAC-SHA1
oauth_timestamp 时间戳当前时间单位毫秒
oauth_nonce 随机串为了防止重放攻击5分钟内同一用户同一应用同
一时间发来的请求中 oauth_nonce应不同
oauth_version 10
oauth_signature 签名使用 consumerSecret +rsquoamprsquo作为签名的 key 而
签名的内容是除 oath_signature以外的请求 url内容
计算签名完毕后使用 base64编码
正确时返回oauth_token_secret(授权流程中的 request_secret 用于申请
access_token 时签名) oauth_token(授权流程中的 requset_token 用于
authorize请求和 access_token请求)和 oauth_callback_confirmed(boolean
值)
错误时返回 error message error是 error code message是错误信息以 json
串形式返回
发送示例
用 curl来举例 请求信息类似于
curl ndashH ldquoAuthorization OAuth oauth_callback=rdquooobrdquo
oauth_consumer_key=rdquo7a23b1eaf487060deaa5660b323c341brdquo
oauth_signature_method=rdquoHMAC-SHA1rdquo oauth_timestamp=rdquo1321847131rdquo
oauth_nonce=rdquo439563436203139rdquo oauth_version=rdquo10rdquordquo
ldquohttpsandboxnoteyoudaocomoauthrequest_tokenrdquo
但是需要注意的是各个 key-value对都需要使用 OAuth编码 详见附录 D
备注
示例中的签名内容大致为(参数顺序可能有变化详见附录 D的签名过程)
GETamp
httpsandboxnoteyoudaocomoauthrequest_tokenampoauth_callback=oobampo
auth_consumer_key=7a23b1eaf487060deaa5660b323c341bampoauth_signature_
method=HMAC-SHA1ampoauth_timestamp=1321847131ampoauth_nonce=4395634
36203139ampoauth_version=10
具体签名方法详见附录 D
请求授权
URL [baseURL]oauthauthorize
请求方式GET
请求参数该处的参数必须以 query string的形式发送
参数名 参数说明
oauth_token 请求 request_token时返回的 oauth_token
正确时返回oauth_token(授权后的 request_token) 和 oauth_verifier
错误时返回error message
发送示例
GET http
sandboxnoteyoudaocomoauthauthorizeoauth_token=5420db084cc41d768d885
a53f7b2c1a6
备注如果 oauth_callback为 oob则不会回调用户会在 Oauth Server页面上
看到 pin 码用户需要手工将 pin 码粘帖到 application 中才能申请到
AccessToken应用请求 authorize时如果请求携带了网易或者有道的 cookie
则将直接询问用户是否授权否则会重新定向到网易的通行证页面
请求 access_token
URL[baseURL]oauthaccess_token
请求方式GET
请求参数
参数名 参数说明
oauth_consumer_key 回调 url
oauth_token request_token时返回的 oauth_token
oauth_verifier Authorize请求时发送回来的 oauth_verifier或者是
OauthServer页面显示的 Pin码
oauth_signature_method 签名方法支持 HMAC-SHA1
oauth_timestamp 时间戳当前时间单位毫秒
oauth_nonce 随机串为了防止重放攻击5分钟内同一用户同一应用同
一时间发来的请求中 oauth_nonce应不同
oauth_version 10
oauth_signature 使用 consumerSecret + rsquoamprsquo + oauth_token_secret
字串作为key 而签名的内容是除oauth_signature以外
的请求 url内容计算签名完毕后使用 base64编码
正确时返回oauth_token_secret (授权流程中的 access_secret)oauth_token
(授权流程中的 access_token)
错误时返回error message
发送示例 http header的例子
curl ndashH ldquoAuthorization OAuth
oauth_verifier=rdquo8714fb943a28d7faffec3265e96d85cdrdquo
oauth_token=rdquob348d10a0f45a4cf6936381d6c9fb00frdquo
oauth_consumer_key=rdquo7a23b1eaf487060deaa5660b323c341brdquo
oauth_signature_method=rdquoHMAC-SHA1rdquo oauth_timestamp=rdquo1321857128rdquo
oauth_nonce=rdquo449560105422526rdquo oauth_version=rdquo10rdquo
oauth_signature=rdquoS8yxdpLIA7MiFVDE4OzSDoo2F62FI3Drdquordquo
ldquohttpsandboxnoteyoudaocomoauthaccess_tokenrdquo
访问 OpenAPI
由 223 返回的 oauth_token 将用于 OpenAPI 的请求 consumerSecret + rsquoamprsquo +
oauth_token_secret 将 用 作 签 名 例 如 请 求 创 建 笔 记 本
http[baseURL]ywsopennotebookcreatejson则应在请求创建笔记中添加各
种参数(创建笔记本的其他参数按文档要求不变)如果没有则会返回 error
和 message(此处的 error和 message会放入到 json串中error是错误码 message
是具体错误信息)不会执行任何 OpenAPI操作
例如执行创建笔记本操作参数 name需和 oauth 的其他值一起进行签名
但是不应该将 name 放入 header 中并且发送 post 请求的 Content-Type 为
applicationx-www-form-urlencoded其他参数填入 http content 域Oauth 参数
放入 Authorization Header域否则可能会出现错误
对于上传笔记或者附件图片的 open API 中post 请求的 Content-Type 为
multipartform-data非 oauth参数均不参与签名非 oauth参数填入 http content
域Oauth参数放入 Authorization Header域否则可能会出现错误
对于使用 GET请求 http[baseURL]ywsopenusergetjson需要将 oauth参
数和非 oauth参数一起放入 url参数中签名时需注意参数顺序发送请求时参
数可以无序
POST
httpnoteyoudaocomywsopennotecreatejson
Header 中 Authorization的值为
OAuth[ 空 格 ]oauth_token=29cc36314495ee1cf55ebf26ca9711bc
oauth_consumer_key=407d014e17ad5cd02f3e0a55fcb198af
oauth_signature_method=HMAC-SHA1 oauth_timestamp=1323327110
oauth_nonce=280224628487931 oauth_version=10
oauth_signature=rXpd0apk82wMAZLun2FDSUt1wbQE3D
最终 Header类似于
Authorization=OAuth20oauth_token3D2229cc36314495ee1cf55ebf26ca
9711bc222C20oauth_consumer_key3D22407d014e17ad5cd02f3e0a55fcb198
af222C20oauth_signature_method3D22HMAC-SHA1222C20oauth_timest
amp3D221323327041222C20oauth_nonce3D22280155519121203222C20
oauth_version3D2210222C20oauth_signature3D22E252F8dFmTFGTmdC
FE2rnJ8f252Bkzw9c253D22
签名的具体方法详见附录 D访问 Oauth的类库包详见附录 C
用户操作 API
查看用户信息
URLhttp[baseURL]ywsopenusergetjson
请求方式GET
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数无
返回结果操作成功时 http 状态为 200并用户信息失败时 http 状态为
500并返回错误码和错误信息详见附录 B
结果示例
ldquouserrdquo ldquotest163comrdquo 用户 ID
ldquototal_sizerdquo ldquo10293736383rdquo 用户总的空间大小单位字节
ldquoused_sizerdquo ldquo1024rdquo 用户已经使用了的空间大小单位字节
ldquoregister_timerdquo ldquo1323310917650rdquo 用户注册时间单位毫秒
ldquolast_login_timerdquo ldquo1323310949120rdquo 用户最后登录时间单位毫秒
ldquolast_modify_timerdquo ldquo1323310978120rdquo 用户最后修改时间单位毫秒
ldquodefault_notebookrdquo ldquoAB384D734rdquo 该应用的默认笔记本
注对于每个第三方应用都分别在用户的笔记空间中对应一个默认笔记本
笔记本名在申请应用时指定在使用 OpenAPI创建笔记时如果第三方应用
不指定笔记本则自动创建在该默认笔记本中
笔记本操作 API
查看用户全部笔记本
URLhttp[baseURL]ywsopennotebookalljson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数无
返回结果操作成功时 http状态为 200并返回笔记本列表失败时 http状
态为 500并返回错误码和错误信息详见附录 B
结果示例
[
ldquopathrdquo ldquo4AF64012E9864Crdquo 笔记本的路径
ldquonamerdquo ldquo笔记本 1rdquo 笔记本的名称
ldquonotes_numrdquo ldquo3rdquo 该笔记本中笔记的数目
ldquocreate_timerdquo ldquo1323310917rdquo 笔记本的创建时间单位秒
ldquomodify_timerdquo ldquo1323310949rdquo 笔记本的最后修改时间单位秒
ldquopathrdquo ldquo5AB0C6B33BD1162rdquo
ldquonamerdquo ldquo笔记本 2rdquo
ldquonotes_numrdquo ldquo10rdquo
ldquocreate_timerdquo ldquo1323311244rdquo
ldquomodify_timerdquo ldquo1323310349rdquo
]
列出笔记本下的笔记
URLhttp[baseURL]ywsopennotebooklistjson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
notebook 笔记本路径 是 String
返回结果操作成功时 http状态为 200并返回该笔记本下的笔记列表(只
有笔记路径笔记内容需要通过笔记接口获取)失败时 http状态 500并返
回错误码和错误信息详见附录 B
结果示例
[
ldquo4AF64012E9864C123TDE3DCrdquo 笔记路径
ldquo4AF64012E9864CDC12FTDE3rdquo
ldquo4AF64012E9864CFE23TDE3Crdquo
]
创建笔记本
URL http[baseURL]ywsopennotebookcreatejson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
name 笔记本名称 是 String
返回结果操作成功时 http状态 200并返回新创建笔记本的路径失败时
http状态 500并返回错误码和错误信息详见附录 B
结果示例
ldquopathrdquo ldquo4AF64012E9864Crdquo
删除笔记本
URL http[baseURL]ywsopennotebookdeletejson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
notebook 笔记本路径 是 String
返回结果操作成功时 http状态 200无返回数据失败时 http状态 500并
返回错误码和错误信息详见附录 B
笔记操作 API
创建笔记
URL http[baseURL]ywsopennotecreatejson
请求方式POST
Content-Typemultipartform-data
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
source 笔记来源 URL 否 String
author 笔记作者 否 String
title 笔记标题 否 String
content 笔记正文(笔记格式见附录 A) 是 String
notebook 该新建笔记所属的笔记本路径 否 String
返回结果操作成功时 http状态为 200并返回新建笔记的路径失败时 http
状态为 500并返回错误码和错误信息详见附录 B
结果示例
ldquopathrdquo ldquo4AF64012E9864CFE89D12134Erdquo
注如果第三方应用没有指定 notebook则在该第三方应用对应的默认笔记
本中创建该笔记
查看笔记
URL http[baseURL]ywsopennotegetjson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
path 笔记路径 是 String
返回结果操作成功时 http状态为 200并返回该笔记的相关信息失败时
http状态为 500并返回错误码和错误信息详见附录 B
结果示例
ldquotitlerdquo ldquo工作记录rdquo 笔记标题
ldquoauthorrdquo ldquoTomrdquo 笔记作者
ldquosourcerdquo ldquohttpnoteyoudaocomrdquo 笔记来源 URL
ldquosizerdquo ldquo1024rdquo 笔记大小包括笔记正文及附件
ldquocreate_timerdquo ldquo1323310917rdquo 笔记的创建时间单位秒
ldquomodify_timerdquo ldquo1323310949rdquo 笔记的最后修改时间单位秒
ldquocontentrdquo ldquoltpgtThis is a test noteltpgt 笔记正文
修改笔记
URL http[baseURL]ywsopennoteupdatejson
请求方式POST
Content-Typemultipartform-data
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
path 修改笔记的路径 是 String
source 修改后的笔记来源 URL 否 String
author 修改后的笔记作者 否 String
title 修改后的笔记标题 否 String
content 修改后的笔记正文(笔记格式见
附录 A)
是 String
返回结果操作成功时 http 状态为 200无返回结果失败时 http 状态为
500并返回错误码和错误信息详见附录 B
移动笔记
URL http[baseURL]ywsopennotemovejson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
path 想要移动的笔记原路径 是 String
notebook 目标笔记本的路径 是 String
返回结果操作成功时 http状态为 200返回移动后的笔记路径失败时 http
状态为 500并返回错误码和错误信息详见附录 B
结果示例
ldquopathrdquo ldquo5AB0C6B33BD1162FE89D12134Erdquo
删除笔记
URL http[baseURL]ywsopennotedeletejson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
path 想要删除的笔记原路径 是 String
返回结果操作成功时 http 状态为 200无返回结果失败时 http 状态为
500并返回错误码和错误信息详见附录 B
附件操作 API
上传附件或图片
URLhttp[baseURL]ywsopenresourceuploadjson
请求方式POST
Content-Typemultipartform-data
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
file 上传的附件文件(包括附件的文
件名类型大小数据等)
是 Multipart File附件大
小限制 25M
返回结果操作成功时 http状态为 200对于图片返回该图片的链接 URL
对于普通附件服务器会为该附件生成一个图标文件因此返回结果包括该
附件对应的链接 URL以及图标的 URL失败时 http状态为 500并返回错误码
和错误信息详见附录 B
示例
图片附件
url httpbaseURLywsopenresource28d83f547f3055
普通附件
url httpbaseURLywsopenresource28d83f547f3055 附件 URL
src httpbaseURLywsopenresource297f2bd6fa2795 图标 URL
需要注意的是在附件上传完成后使用者应该紧接着更新对应的笔记否
则不被任何笔记引用的附件将被定期的空间回收所删除
下载附件图片图标
URLhttp[baseURL]ywsopenresourcedownload
请求方式GET
是否需要用户认证是 (关于登录授权参见请求用户授权)
返回结果操作成功时response返回附件及图片的二进制流失败时 http
状态为 500并返回错误码和错误信息详见附录 B
备注
1 当打开笔记时对于笔记中的附件及图片链接只需要添加用户的 OAuth
认证信息即可以获取对应的附件及图片同理在上传附件后返回的附
件及图片链接也可以通过这种方式进行访问
2 附件及图片的下载支持断点续传
附录 A有道云笔记内容格式
笔记内容的格式采用类 HTML的标记语言绝大部分格式相关 tag均采用标
准的 HTML Tag唯一需要不同的是附件及图片 Tag在格式上图片 Tag与标准的
img tag相同一个图片资源的标记如下
ltimg src=httpnoteyoudaocomywsopenresource227f2bd6fa2795441cgt
但是由于对应的接口需要用户认证因此在获取图片资源时需要加入 OAuth
的用户认证信息
附件通常以图标在笔记中进行显示因此我们扩展了图片 Tag ltimggt除了
img 本身的 src 属性额外加入了一个属性 path其中 src 对应着该附件的图标
URL而 path则为该附件的 URL如下所示
ltimg path=httpnoteyoudaocomywsopenresource219fe604c7c90642fd8f
src=httpnoteyoudaocomywsopenresource227f2bd6fa2795441cgt
同理也需要加入 OAuth的用户认证信息才可以正常访问附件资源及其图标
附录 B错误码及错误信息说明
同理当 Open API的请求在执行时出现任何异常或错误时系统将返回 Http
500应用程序可以根据此判断请求是否成功执行当应用程序在进行 OAuth认
证或者未经认证便调用 Open API时系统会返回 OAuth错误信息OAuth的
错误码与错误信息将以 json的格式进行返回各个错误码及错误信息说明如下
错误码 错误描述及可能原因
1001 token_rejectedconsumer没有找到consumerKey错误 consumer
没有创建或者 request token或者 access token 不存在于 server中
或者没有获得授权的 token或者 token过期
1002 parameter_rejected这个会返回具体原因 key是
oauth_parameters_rejected value是一个 parameter列表
1003 version_rejectedOAuth版本号不是 10
1004 timestamp_refusedtimestamp 非 5分钟内
1005 nonce_used5分钟内该 nonce被使用
1006 parameter_absent有些参数没有发送给 server
1007 signature_invalidoauth签名异常可能原因没有签名签名方法和
签名不一致等
1008 signature_method_rejectedoauth server没有提供该签名方法
1009 access_state_error获取 token时状态混乱详细的信息会告知当前的
状态 [AUTHORIZED | REQUEST | ACCESS | INVALID]
1010 consumer_rejected该 consumer在 server中不存在或者被禁掉
或者 consumerKey改变但是还没有反应到 server的数据库中
1011 accessor_rejected由 token得到的 accessor构造异常或者 accessor
中缺失某些属性或者转换失败
1012 callback_errorrequest token传来的 callback和以后的 callback不一致
1013 callback_domain_error当限定 callback后发来的 callback与原设置
的 callback的域不相同
1014 verifier_errorVerifier不一致错误
1015 permission_denied无授权的 token或者授权后没有获取过 access
token
同理当 Open API的请求在后台执行出现异常或错误时系统也将同时错
误码与错误信息以 json 的格式一同返回应用程序可以根据错误码得到相应的
原因常见的错误码说明如下
错误码 错误描述及可能原因
206 UNKNOWN_URI错误的 URI请求
207 AUTHENTICATION_FAILURE用户认证错误
209 RESOURCE_NOT_EXIST请求的资源(笔记本笔记附件等)不存在
210 USER_SPACE_FULL用户空间已满
214 INVALID_PARAMETER错误的传入参数必须的参数为空等
220 USER_NOT_EXISTS用户不存在
221 USER_ALREADY_EXISTS用户已经存在不能重复注册
225 PARENT_NOT_EXIST笔记本尚不存在不能在该笔记本下创建笔记
231 RESOURCE_ALREADY_EXIST该笔记或者附件已经存在不能重复创建
304 NOTE_ALREADY_DELETED笔记已经被删除
307 INVALID_APPLICATION无效的第三方应用未经过用户授权或者授权
失败便通过 OpenAPI访问用户数据这个一般是使用测试环境得到了
access_token利用该 access_token访问了线上环境这两套环境是独
立的Access_token不能共用
但是如果第三方应用未经过用户授权
示例当查看笔记路径错误时
error 209
message Required note does not exist path=5AB0C6B33BD12FE89D12134E
附录 C 访问 OAuth Server的类库与包
ActionScriptFlash
oauth-as3 httpcodegooglecompoauth-as3
A flex oauth client
httpwwwarcgiscomhomeitemhtmlid=ff6ffa302ad04a7194999f2ad08250d7
CC++
QTweetLib httpgithubcomminimoogQTweetLib
libOAuth httpliboauthsourceforgenet
clojure
clj-oauth httpgithubcommattreplclj-oauth
net
oauth-dot-net httpcodegooglecompoauth-dot-net
DotNetOpenAuth httpwwwdotnetopenauthnet
Erlang
erlang-oauth httpgithubcomtimerlang-oauth
java
Scrible httpgithubcomfernandezpablo85scribe-java
oauth-signpost httpcodegooglecompoauth-signpost
javascript
oauth in js httpoauthgooglecodecomsvncodejavascript
Objective-CCocoa amp iPhone programming
OAuthCore httpbitbucketorgatebitsoauthcore
MPOAuthConnection httpcodegooglecompmpoauthconnection
Objective-C OAuth httpoauthgooglecodecomsvncodeobj-c
Perl
NetOAuth httpoauthgooglecodecomsvncodeperl
PHP
tmhOAuth httpgithubcomthemattharristmhOAuth
oauth-php httpcodegooglecompoauth-php
Python
python-oauth2 httpgithubcombrosnerpython-oauth2
Qt
qOauth httpgithubcomayoyqoauth
Ruby
Oauth ruby gem httpoauthrubyforgeorg
Scala
DataBinder Dispatch httpdispatchdatabindernetAbout
附录 D Oauth签名加密 oauth_signature
1 加密内容是
a 请求方法名例如 GET POST等 加密时方法名大写并进行特殊替换
(详见 3)
b url (query param之前的部分不包括 )Http或者 https需要全部小
写 http如果带有 80端口或者 https带有 443端口需要将其省略
其他端口则不能省略例如
Httplocal9999requestToken
httplocal9999requestToken
Httplocal80requestToken
httplocalrequestToken
Httpslocal443requestToken
httpslocal requestToken
c 参数(query param中的或者 header中的 key-value对) 首先将这些参数
进行特殊替换后按字典序排序升序排列如果两个 key相同则以
value特殊替换后字典序为准key与 value之间使用rdquo=rdquo连接如果
value==null则使用rdquordquo替代两个参数对之间使用rdquoamprdquo连接连接后形成
的最终字符串的开头和结尾没有rdquoamprdquo
d 字典序字符串比较大小伪代码
Int compare(string a string b)
Int min_len = min(len(a) len(b))
For I to min_len
If (a[i] = b[i])
Return a[i] ndash b[i]
Return len(a) ndash len(b)
将以上 abc三部分进行特殊替换后使用amp连接最终形成的字符串的
开头和结尾都没有rdquoamprdquo这就是加密内容
2 加密的 key是 consumerSecret + amp + TokenSecret 如果 TokenSecret还没有
得到则使用rdquordquo consumerSecret和 TokenSecret需先做特殊替换然后
再进行签名
3 特殊替换是将 String进行 URL编码后将rdquo+rdquo替换为rdquo20rdquo将rdquordquo替换
为rdquo2Ardquo将rdquo7Erdquo替换为rdquo~rdquo
4 签名方法可以使用 HMAC-SHA1PLAINTEXT RSA_SHA1三种其中
PLAINTEXT为 2中的 key 该方法不提倡使用
得到签名内容后使用 Base64进行编码编码后的字符串即为 oauth_signature
参看 httpoauthnet
申请 Consumer Key
对于所有需要使用 Open API的应用在使用 Open API之前首先要在系统内
申请一个应用程序申请者需要提交申请人姓名应用名称callback URL以及
是否限制 callbackURL 等信息我们会生成相应 的 ConsumerKey 和
ConsumerSecret作为每个应用的身份标识应用名称和 ConsumerKey在系统中
均是唯一的在进行请求时第三方应用需要将 ConsumerKey加入请求中而系
统收到请求后便可以根据 ConsumerKey 和 ConsumerSecret 对请求进行验证与
记录
目前我们采用网站申请的方式申请网址httpnoteyoudaocomopen
也可以采用邮件申请的方式申请人可直接发送邮件至 noteapirdneteasecom
邮件内容示例如下
App名称pYNote
组织类型个人公司
姓名张三XX科技有限公司
email XXX163com
homelinkhttpwwwyoudaocom
应用类型浏览器插件(应用)IOS appAndroid appWindows appMac os app
其它请在详细描述中说明
详细描述Linux下基于 Python的有道云笔记客户端
另外还需要 2种规格的 LOGO6060177177JPG格式即可
请求用户授权
授权流程
在拿到 ConsumerKey 和 ConsumerSecret 以后应用程序便可以结合
ConsumerKey 申请一个 request_token 和 request_secret发送的内容应该有
ConsumerSecret的签名
应用程序再次用 request_token 和 ConsumerKey 来申请用户授权该请求内
容应该由 ConsumerSecret 和 request_secret 共同签名授权时需要用户在
OauthServer 提供的页面中输入用户名密码等信息进行授权操作已经登录过的
用户可以直接进行授权操作用户授权之后会返回 request_token和 verifier 此
时的 request_token在 OauthServer中已经授权
授权之后应用程序就可以使用 request_token 申请 access_token 和
access_secret该请求内容同样要使用 ConsumerSecret 和 request_secret 共同签
名
如果以上步骤中可能会因为超时或者发送内容不符造成错误OAuth会返回
错误信息给应用程序
详细流程见图 211
开始
结束
请求是否合法
请求requst_token
返回错误信息
生成request_token
Y
返回授权的request_tokensecr
et verifier等信息
请求授权
对request_token授权生成
verifier(PIN码)
request_token
是否存在
Y
请求是否合法
N
请求access_token
生成access_token
Y
图 211 授权流程图
授权请求参数方法和返回值
下面将介绍如何使用 OauthServer服务得到 access_token和 access_secret下
面的文字中[baseURL]指代 OauthServer 的 URL对于线上环境该 baseURL
即为 httpnoteyoudaocom而对于 sandbox 测试环境该 baseURL 为
httpsandboxnoteyoudaocom这里使用 HTTP Header设置参数 Header
name 设 为 Authorization Header value 设 为 OAuth[ 空
格][parameterName=rdquovaluerdquo][空格][ parameterName=rdquovaluerdquo]hellip 值得注意
的是 parameterName 和 value 必须进行 URL 编码并且在 URL 编码后还要
将 rdquo+rdquo替换为 rdquo20rdquo将rdquordquo替换为 rdquo2Ardquo将 rdquo7Erdquo替换为 rdquo~rdquo例如请求
authorized token时 HTTP header中的 value是
OAuth[ 空 格 ]oauth_token=29cc36314495ee1cf55ebf26ca9711bc[ 空 格 ]
oauth_consumer_key=407d014e17ad5cd02f3e0a55fcb198af [ 空
格 ]oauth_signature_method=HMAC-SHA1[ 空
格 ]oauth_timestamp=1323325710[ 空
格 ]oauth_nonce=278825208972307[ 空 格 ]oauth_version=10[ 空 格 ]
oauth_signature=x8E7wrAmn6GyHv4aldWSo1M2ShU3D 注意其中双引
号rdquordquo是必须的 发送请求时这些参数可以是无序的但是签名时这些参
数有一定的顺序详见附录 D
以下各个请求正确时返回值 content-type 为 textplain 返回
key=value[空格]key=value
以下各个请求错误时会返回错误信息该信息包含 error message等
error是错误码message包含更详尽的错误信息另外特殊错误时还可能返
回更多信息详见附录 B
请求 request_token
URL[baseURL]oauthrequest_token
请求方式GET
请求参数
参数名 参数说明
oauth_callback 回调 url该 url可以为 oob代表不回调另外 url还可
以跟其他参数
oauth_consumer_key 申请应用时拿到的 consumerKey
oauth_signature_method 签名方法支持 HMAC-SHA1
oauth_timestamp 时间戳当前时间单位毫秒
oauth_nonce 随机串为了防止重放攻击5分钟内同一用户同一应用同
一时间发来的请求中 oauth_nonce应不同
oauth_version 10
oauth_signature 签名使用 consumerSecret +rsquoamprsquo作为签名的 key 而
签名的内容是除 oath_signature以外的请求 url内容
计算签名完毕后使用 base64编码
正确时返回oauth_token_secret(授权流程中的 request_secret 用于申请
access_token 时签名) oauth_token(授权流程中的 requset_token 用于
authorize请求和 access_token请求)和 oauth_callback_confirmed(boolean
值)
错误时返回 error message error是 error code message是错误信息以 json
串形式返回
发送示例
用 curl来举例 请求信息类似于
curl ndashH ldquoAuthorization OAuth oauth_callback=rdquooobrdquo
oauth_consumer_key=rdquo7a23b1eaf487060deaa5660b323c341brdquo
oauth_signature_method=rdquoHMAC-SHA1rdquo oauth_timestamp=rdquo1321847131rdquo
oauth_nonce=rdquo439563436203139rdquo oauth_version=rdquo10rdquordquo
ldquohttpsandboxnoteyoudaocomoauthrequest_tokenrdquo
但是需要注意的是各个 key-value对都需要使用 OAuth编码 详见附录 D
备注
示例中的签名内容大致为(参数顺序可能有变化详见附录 D的签名过程)
GETamp
httpsandboxnoteyoudaocomoauthrequest_tokenampoauth_callback=oobampo
auth_consumer_key=7a23b1eaf487060deaa5660b323c341bampoauth_signature_
method=HMAC-SHA1ampoauth_timestamp=1321847131ampoauth_nonce=4395634
36203139ampoauth_version=10
具体签名方法详见附录 D
请求授权
URL [baseURL]oauthauthorize
请求方式GET
请求参数该处的参数必须以 query string的形式发送
参数名 参数说明
oauth_token 请求 request_token时返回的 oauth_token
正确时返回oauth_token(授权后的 request_token) 和 oauth_verifier
错误时返回error message
发送示例
GET http
sandboxnoteyoudaocomoauthauthorizeoauth_token=5420db084cc41d768d885
a53f7b2c1a6
备注如果 oauth_callback为 oob则不会回调用户会在 Oauth Server页面上
看到 pin 码用户需要手工将 pin 码粘帖到 application 中才能申请到
AccessToken应用请求 authorize时如果请求携带了网易或者有道的 cookie
则将直接询问用户是否授权否则会重新定向到网易的通行证页面
请求 access_token
URL[baseURL]oauthaccess_token
请求方式GET
请求参数
参数名 参数说明
oauth_consumer_key 回调 url
oauth_token request_token时返回的 oauth_token
oauth_verifier Authorize请求时发送回来的 oauth_verifier或者是
OauthServer页面显示的 Pin码
oauth_signature_method 签名方法支持 HMAC-SHA1
oauth_timestamp 时间戳当前时间单位毫秒
oauth_nonce 随机串为了防止重放攻击5分钟内同一用户同一应用同
一时间发来的请求中 oauth_nonce应不同
oauth_version 10
oauth_signature 使用 consumerSecret + rsquoamprsquo + oauth_token_secret
字串作为key 而签名的内容是除oauth_signature以外
的请求 url内容计算签名完毕后使用 base64编码
正确时返回oauth_token_secret (授权流程中的 access_secret)oauth_token
(授权流程中的 access_token)
错误时返回error message
发送示例 http header的例子
curl ndashH ldquoAuthorization OAuth
oauth_verifier=rdquo8714fb943a28d7faffec3265e96d85cdrdquo
oauth_token=rdquob348d10a0f45a4cf6936381d6c9fb00frdquo
oauth_consumer_key=rdquo7a23b1eaf487060deaa5660b323c341brdquo
oauth_signature_method=rdquoHMAC-SHA1rdquo oauth_timestamp=rdquo1321857128rdquo
oauth_nonce=rdquo449560105422526rdquo oauth_version=rdquo10rdquo
oauth_signature=rdquoS8yxdpLIA7MiFVDE4OzSDoo2F62FI3Drdquordquo
ldquohttpsandboxnoteyoudaocomoauthaccess_tokenrdquo
访问 OpenAPI
由 223 返回的 oauth_token 将用于 OpenAPI 的请求 consumerSecret + rsquoamprsquo +
oauth_token_secret 将 用 作 签 名 例 如 请 求 创 建 笔 记 本
http[baseURL]ywsopennotebookcreatejson则应在请求创建笔记中添加各
种参数(创建笔记本的其他参数按文档要求不变)如果没有则会返回 error
和 message(此处的 error和 message会放入到 json串中error是错误码 message
是具体错误信息)不会执行任何 OpenAPI操作
例如执行创建笔记本操作参数 name需和 oauth 的其他值一起进行签名
但是不应该将 name 放入 header 中并且发送 post 请求的 Content-Type 为
applicationx-www-form-urlencoded其他参数填入 http content 域Oauth 参数
放入 Authorization Header域否则可能会出现错误
对于上传笔记或者附件图片的 open API 中post 请求的 Content-Type 为
multipartform-data非 oauth参数均不参与签名非 oauth参数填入 http content
域Oauth参数放入 Authorization Header域否则可能会出现错误
对于使用 GET请求 http[baseURL]ywsopenusergetjson需要将 oauth参
数和非 oauth参数一起放入 url参数中签名时需注意参数顺序发送请求时参
数可以无序
POST
httpnoteyoudaocomywsopennotecreatejson
Header 中 Authorization的值为
OAuth[ 空 格 ]oauth_token=29cc36314495ee1cf55ebf26ca9711bc
oauth_consumer_key=407d014e17ad5cd02f3e0a55fcb198af
oauth_signature_method=HMAC-SHA1 oauth_timestamp=1323327110
oauth_nonce=280224628487931 oauth_version=10
oauth_signature=rXpd0apk82wMAZLun2FDSUt1wbQE3D
最终 Header类似于
Authorization=OAuth20oauth_token3D2229cc36314495ee1cf55ebf26ca
9711bc222C20oauth_consumer_key3D22407d014e17ad5cd02f3e0a55fcb198
af222C20oauth_signature_method3D22HMAC-SHA1222C20oauth_timest
amp3D221323327041222C20oauth_nonce3D22280155519121203222C20
oauth_version3D2210222C20oauth_signature3D22E252F8dFmTFGTmdC
FE2rnJ8f252Bkzw9c253D22
签名的具体方法详见附录 D访问 Oauth的类库包详见附录 C
用户操作 API
查看用户信息
URLhttp[baseURL]ywsopenusergetjson
请求方式GET
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数无
返回结果操作成功时 http 状态为 200并用户信息失败时 http 状态为
500并返回错误码和错误信息详见附录 B
结果示例
ldquouserrdquo ldquotest163comrdquo 用户 ID
ldquototal_sizerdquo ldquo10293736383rdquo 用户总的空间大小单位字节
ldquoused_sizerdquo ldquo1024rdquo 用户已经使用了的空间大小单位字节
ldquoregister_timerdquo ldquo1323310917650rdquo 用户注册时间单位毫秒
ldquolast_login_timerdquo ldquo1323310949120rdquo 用户最后登录时间单位毫秒
ldquolast_modify_timerdquo ldquo1323310978120rdquo 用户最后修改时间单位毫秒
ldquodefault_notebookrdquo ldquoAB384D734rdquo 该应用的默认笔记本
注对于每个第三方应用都分别在用户的笔记空间中对应一个默认笔记本
笔记本名在申请应用时指定在使用 OpenAPI创建笔记时如果第三方应用
不指定笔记本则自动创建在该默认笔记本中
笔记本操作 API
查看用户全部笔记本
URLhttp[baseURL]ywsopennotebookalljson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数无
返回结果操作成功时 http状态为 200并返回笔记本列表失败时 http状
态为 500并返回错误码和错误信息详见附录 B
结果示例
[
ldquopathrdquo ldquo4AF64012E9864Crdquo 笔记本的路径
ldquonamerdquo ldquo笔记本 1rdquo 笔记本的名称
ldquonotes_numrdquo ldquo3rdquo 该笔记本中笔记的数目
ldquocreate_timerdquo ldquo1323310917rdquo 笔记本的创建时间单位秒
ldquomodify_timerdquo ldquo1323310949rdquo 笔记本的最后修改时间单位秒
ldquopathrdquo ldquo5AB0C6B33BD1162rdquo
ldquonamerdquo ldquo笔记本 2rdquo
ldquonotes_numrdquo ldquo10rdquo
ldquocreate_timerdquo ldquo1323311244rdquo
ldquomodify_timerdquo ldquo1323310349rdquo
]
列出笔记本下的笔记
URLhttp[baseURL]ywsopennotebooklistjson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
notebook 笔记本路径 是 String
返回结果操作成功时 http状态为 200并返回该笔记本下的笔记列表(只
有笔记路径笔记内容需要通过笔记接口获取)失败时 http状态 500并返
回错误码和错误信息详见附录 B
结果示例
[
ldquo4AF64012E9864C123TDE3DCrdquo 笔记路径
ldquo4AF64012E9864CDC12FTDE3rdquo
ldquo4AF64012E9864CFE23TDE3Crdquo
]
创建笔记本
URL http[baseURL]ywsopennotebookcreatejson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
name 笔记本名称 是 String
返回结果操作成功时 http状态 200并返回新创建笔记本的路径失败时
http状态 500并返回错误码和错误信息详见附录 B
结果示例
ldquopathrdquo ldquo4AF64012E9864Crdquo
删除笔记本
URL http[baseURL]ywsopennotebookdeletejson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
notebook 笔记本路径 是 String
返回结果操作成功时 http状态 200无返回数据失败时 http状态 500并
返回错误码和错误信息详见附录 B
笔记操作 API
创建笔记
URL http[baseURL]ywsopennotecreatejson
请求方式POST
Content-Typemultipartform-data
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
source 笔记来源 URL 否 String
author 笔记作者 否 String
title 笔记标题 否 String
content 笔记正文(笔记格式见附录 A) 是 String
notebook 该新建笔记所属的笔记本路径 否 String
返回结果操作成功时 http状态为 200并返回新建笔记的路径失败时 http
状态为 500并返回错误码和错误信息详见附录 B
结果示例
ldquopathrdquo ldquo4AF64012E9864CFE89D12134Erdquo
注如果第三方应用没有指定 notebook则在该第三方应用对应的默认笔记
本中创建该笔记
查看笔记
URL http[baseURL]ywsopennotegetjson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
path 笔记路径 是 String
返回结果操作成功时 http状态为 200并返回该笔记的相关信息失败时
http状态为 500并返回错误码和错误信息详见附录 B
结果示例
ldquotitlerdquo ldquo工作记录rdquo 笔记标题
ldquoauthorrdquo ldquoTomrdquo 笔记作者
ldquosourcerdquo ldquohttpnoteyoudaocomrdquo 笔记来源 URL
ldquosizerdquo ldquo1024rdquo 笔记大小包括笔记正文及附件
ldquocreate_timerdquo ldquo1323310917rdquo 笔记的创建时间单位秒
ldquomodify_timerdquo ldquo1323310949rdquo 笔记的最后修改时间单位秒
ldquocontentrdquo ldquoltpgtThis is a test noteltpgt 笔记正文
修改笔记
URL http[baseURL]ywsopennoteupdatejson
请求方式POST
Content-Typemultipartform-data
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
path 修改笔记的路径 是 String
source 修改后的笔记来源 URL 否 String
author 修改后的笔记作者 否 String
title 修改后的笔记标题 否 String
content 修改后的笔记正文(笔记格式见
附录 A)
是 String
返回结果操作成功时 http 状态为 200无返回结果失败时 http 状态为
500并返回错误码和错误信息详见附录 B
移动笔记
URL http[baseURL]ywsopennotemovejson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
path 想要移动的笔记原路径 是 String
notebook 目标笔记本的路径 是 String
返回结果操作成功时 http状态为 200返回移动后的笔记路径失败时 http
状态为 500并返回错误码和错误信息详见附录 B
结果示例
ldquopathrdquo ldquo5AB0C6B33BD1162FE89D12134Erdquo
删除笔记
URL http[baseURL]ywsopennotedeletejson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
path 想要删除的笔记原路径 是 String
返回结果操作成功时 http 状态为 200无返回结果失败时 http 状态为
500并返回错误码和错误信息详见附录 B
附件操作 API
上传附件或图片
URLhttp[baseURL]ywsopenresourceuploadjson
请求方式POST
Content-Typemultipartform-data
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
file 上传的附件文件(包括附件的文
件名类型大小数据等)
是 Multipart File附件大
小限制 25M
返回结果操作成功时 http状态为 200对于图片返回该图片的链接 URL
对于普通附件服务器会为该附件生成一个图标文件因此返回结果包括该
附件对应的链接 URL以及图标的 URL失败时 http状态为 500并返回错误码
和错误信息详见附录 B
示例
图片附件
url httpbaseURLywsopenresource28d83f547f3055
普通附件
url httpbaseURLywsopenresource28d83f547f3055 附件 URL
src httpbaseURLywsopenresource297f2bd6fa2795 图标 URL
需要注意的是在附件上传完成后使用者应该紧接着更新对应的笔记否
则不被任何笔记引用的附件将被定期的空间回收所删除
下载附件图片图标
URLhttp[baseURL]ywsopenresourcedownload
请求方式GET
是否需要用户认证是 (关于登录授权参见请求用户授权)
返回结果操作成功时response返回附件及图片的二进制流失败时 http
状态为 500并返回错误码和错误信息详见附录 B
备注
1 当打开笔记时对于笔记中的附件及图片链接只需要添加用户的 OAuth
认证信息即可以获取对应的附件及图片同理在上传附件后返回的附
件及图片链接也可以通过这种方式进行访问
2 附件及图片的下载支持断点续传
附录 A有道云笔记内容格式
笔记内容的格式采用类 HTML的标记语言绝大部分格式相关 tag均采用标
准的 HTML Tag唯一需要不同的是附件及图片 Tag在格式上图片 Tag与标准的
img tag相同一个图片资源的标记如下
ltimg src=httpnoteyoudaocomywsopenresource227f2bd6fa2795441cgt
但是由于对应的接口需要用户认证因此在获取图片资源时需要加入 OAuth
的用户认证信息
附件通常以图标在笔记中进行显示因此我们扩展了图片 Tag ltimggt除了
img 本身的 src 属性额外加入了一个属性 path其中 src 对应着该附件的图标
URL而 path则为该附件的 URL如下所示
ltimg path=httpnoteyoudaocomywsopenresource219fe604c7c90642fd8f
src=httpnoteyoudaocomywsopenresource227f2bd6fa2795441cgt
同理也需要加入 OAuth的用户认证信息才可以正常访问附件资源及其图标
附录 B错误码及错误信息说明
同理当 Open API的请求在执行时出现任何异常或错误时系统将返回 Http
500应用程序可以根据此判断请求是否成功执行当应用程序在进行 OAuth认
证或者未经认证便调用 Open API时系统会返回 OAuth错误信息OAuth的
错误码与错误信息将以 json的格式进行返回各个错误码及错误信息说明如下
错误码 错误描述及可能原因
1001 token_rejectedconsumer没有找到consumerKey错误 consumer
没有创建或者 request token或者 access token 不存在于 server中
或者没有获得授权的 token或者 token过期
1002 parameter_rejected这个会返回具体原因 key是
oauth_parameters_rejected value是一个 parameter列表
1003 version_rejectedOAuth版本号不是 10
1004 timestamp_refusedtimestamp 非 5分钟内
1005 nonce_used5分钟内该 nonce被使用
1006 parameter_absent有些参数没有发送给 server
1007 signature_invalidoauth签名异常可能原因没有签名签名方法和
签名不一致等
1008 signature_method_rejectedoauth server没有提供该签名方法
1009 access_state_error获取 token时状态混乱详细的信息会告知当前的
状态 [AUTHORIZED | REQUEST | ACCESS | INVALID]
1010 consumer_rejected该 consumer在 server中不存在或者被禁掉
或者 consumerKey改变但是还没有反应到 server的数据库中
1011 accessor_rejected由 token得到的 accessor构造异常或者 accessor
中缺失某些属性或者转换失败
1012 callback_errorrequest token传来的 callback和以后的 callback不一致
1013 callback_domain_error当限定 callback后发来的 callback与原设置
的 callback的域不相同
1014 verifier_errorVerifier不一致错误
1015 permission_denied无授权的 token或者授权后没有获取过 access
token
同理当 Open API的请求在后台执行出现异常或错误时系统也将同时错
误码与错误信息以 json 的格式一同返回应用程序可以根据错误码得到相应的
原因常见的错误码说明如下
错误码 错误描述及可能原因
206 UNKNOWN_URI错误的 URI请求
207 AUTHENTICATION_FAILURE用户认证错误
209 RESOURCE_NOT_EXIST请求的资源(笔记本笔记附件等)不存在
210 USER_SPACE_FULL用户空间已满
214 INVALID_PARAMETER错误的传入参数必须的参数为空等
220 USER_NOT_EXISTS用户不存在
221 USER_ALREADY_EXISTS用户已经存在不能重复注册
225 PARENT_NOT_EXIST笔记本尚不存在不能在该笔记本下创建笔记
231 RESOURCE_ALREADY_EXIST该笔记或者附件已经存在不能重复创建
304 NOTE_ALREADY_DELETED笔记已经被删除
307 INVALID_APPLICATION无效的第三方应用未经过用户授权或者授权
失败便通过 OpenAPI访问用户数据这个一般是使用测试环境得到了
access_token利用该 access_token访问了线上环境这两套环境是独
立的Access_token不能共用
但是如果第三方应用未经过用户授权
示例当查看笔记路径错误时
error 209
message Required note does not exist path=5AB0C6B33BD12FE89D12134E
附录 C 访问 OAuth Server的类库与包
ActionScriptFlash
oauth-as3 httpcodegooglecompoauth-as3
A flex oauth client
httpwwwarcgiscomhomeitemhtmlid=ff6ffa302ad04a7194999f2ad08250d7
CC++
QTweetLib httpgithubcomminimoogQTweetLib
libOAuth httpliboauthsourceforgenet
clojure
clj-oauth httpgithubcommattreplclj-oauth
net
oauth-dot-net httpcodegooglecompoauth-dot-net
DotNetOpenAuth httpwwwdotnetopenauthnet
Erlang
erlang-oauth httpgithubcomtimerlang-oauth
java
Scrible httpgithubcomfernandezpablo85scribe-java
oauth-signpost httpcodegooglecompoauth-signpost
javascript
oauth in js httpoauthgooglecodecomsvncodejavascript
Objective-CCocoa amp iPhone programming
OAuthCore httpbitbucketorgatebitsoauthcore
MPOAuthConnection httpcodegooglecompmpoauthconnection
Objective-C OAuth httpoauthgooglecodecomsvncodeobj-c
Perl
NetOAuth httpoauthgooglecodecomsvncodeperl
PHP
tmhOAuth httpgithubcomthemattharristmhOAuth
oauth-php httpcodegooglecompoauth-php
Python
python-oauth2 httpgithubcombrosnerpython-oauth2
Qt
qOauth httpgithubcomayoyqoauth
Ruby
Oauth ruby gem httpoauthrubyforgeorg
Scala
DataBinder Dispatch httpdispatchdatabindernetAbout
附录 D Oauth签名加密 oauth_signature
1 加密内容是
a 请求方法名例如 GET POST等 加密时方法名大写并进行特殊替换
(详见 3)
b url (query param之前的部分不包括 )Http或者 https需要全部小
写 http如果带有 80端口或者 https带有 443端口需要将其省略
其他端口则不能省略例如
Httplocal9999requestToken
httplocal9999requestToken
Httplocal80requestToken
httplocalrequestToken
Httpslocal443requestToken
httpslocal requestToken
c 参数(query param中的或者 header中的 key-value对) 首先将这些参数
进行特殊替换后按字典序排序升序排列如果两个 key相同则以
value特殊替换后字典序为准key与 value之间使用rdquo=rdquo连接如果
value==null则使用rdquordquo替代两个参数对之间使用rdquoamprdquo连接连接后形成
的最终字符串的开头和结尾没有rdquoamprdquo
d 字典序字符串比较大小伪代码
Int compare(string a string b)
Int min_len = min(len(a) len(b))
For I to min_len
If (a[i] = b[i])
Return a[i] ndash b[i]
Return len(a) ndash len(b)
将以上 abc三部分进行特殊替换后使用amp连接最终形成的字符串的
开头和结尾都没有rdquoamprdquo这就是加密内容
2 加密的 key是 consumerSecret + amp + TokenSecret 如果 TokenSecret还没有
得到则使用rdquordquo consumerSecret和 TokenSecret需先做特殊替换然后
再进行签名
3 特殊替换是将 String进行 URL编码后将rdquo+rdquo替换为rdquo20rdquo将rdquordquo替换
为rdquo2Ardquo将rdquo7Erdquo替换为rdquo~rdquo
4 签名方法可以使用 HMAC-SHA1PLAINTEXT RSA_SHA1三种其中
PLAINTEXT为 2中的 key 该方法不提倡使用
得到签名内容后使用 Base64进行编码编码后的字符串即为 oauth_signature
时的 request_token在 OauthServer中已经授权
授权之后应用程序就可以使用 request_token 申请 access_token 和
access_secret该请求内容同样要使用 ConsumerSecret 和 request_secret 共同签
名
如果以上步骤中可能会因为超时或者发送内容不符造成错误OAuth会返回
错误信息给应用程序
详细流程见图 211
开始
结束
请求是否合法
请求requst_token
返回错误信息
生成request_token
Y
返回授权的request_tokensecr
et verifier等信息
请求授权
对request_token授权生成
verifier(PIN码)
request_token
是否存在
Y
请求是否合法
N
请求access_token
生成access_token
Y
图 211 授权流程图
授权请求参数方法和返回值
下面将介绍如何使用 OauthServer服务得到 access_token和 access_secret下
面的文字中[baseURL]指代 OauthServer 的 URL对于线上环境该 baseURL
即为 httpnoteyoudaocom而对于 sandbox 测试环境该 baseURL 为
httpsandboxnoteyoudaocom这里使用 HTTP Header设置参数 Header
name 设 为 Authorization Header value 设 为 OAuth[ 空
格][parameterName=rdquovaluerdquo][空格][ parameterName=rdquovaluerdquo]hellip 值得注意
的是 parameterName 和 value 必须进行 URL 编码并且在 URL 编码后还要
将 rdquo+rdquo替换为 rdquo20rdquo将rdquordquo替换为 rdquo2Ardquo将 rdquo7Erdquo替换为 rdquo~rdquo例如请求
authorized token时 HTTP header中的 value是
OAuth[ 空 格 ]oauth_token=29cc36314495ee1cf55ebf26ca9711bc[ 空 格 ]
oauth_consumer_key=407d014e17ad5cd02f3e0a55fcb198af [ 空
格 ]oauth_signature_method=HMAC-SHA1[ 空
格 ]oauth_timestamp=1323325710[ 空
格 ]oauth_nonce=278825208972307[ 空 格 ]oauth_version=10[ 空 格 ]
oauth_signature=x8E7wrAmn6GyHv4aldWSo1M2ShU3D 注意其中双引
号rdquordquo是必须的 发送请求时这些参数可以是无序的但是签名时这些参
数有一定的顺序详见附录 D
以下各个请求正确时返回值 content-type 为 textplain 返回
key=value[空格]key=value
以下各个请求错误时会返回错误信息该信息包含 error message等
error是错误码message包含更详尽的错误信息另外特殊错误时还可能返
回更多信息详见附录 B
请求 request_token
URL[baseURL]oauthrequest_token
请求方式GET
请求参数
参数名 参数说明
oauth_callback 回调 url该 url可以为 oob代表不回调另外 url还可
以跟其他参数
oauth_consumer_key 申请应用时拿到的 consumerKey
oauth_signature_method 签名方法支持 HMAC-SHA1
oauth_timestamp 时间戳当前时间单位毫秒
oauth_nonce 随机串为了防止重放攻击5分钟内同一用户同一应用同
一时间发来的请求中 oauth_nonce应不同
oauth_version 10
oauth_signature 签名使用 consumerSecret +rsquoamprsquo作为签名的 key 而
签名的内容是除 oath_signature以外的请求 url内容
计算签名完毕后使用 base64编码
正确时返回oauth_token_secret(授权流程中的 request_secret 用于申请
access_token 时签名) oauth_token(授权流程中的 requset_token 用于
authorize请求和 access_token请求)和 oauth_callback_confirmed(boolean
值)
错误时返回 error message error是 error code message是错误信息以 json
串形式返回
发送示例
用 curl来举例 请求信息类似于
curl ndashH ldquoAuthorization OAuth oauth_callback=rdquooobrdquo
oauth_consumer_key=rdquo7a23b1eaf487060deaa5660b323c341brdquo
oauth_signature_method=rdquoHMAC-SHA1rdquo oauth_timestamp=rdquo1321847131rdquo
oauth_nonce=rdquo439563436203139rdquo oauth_version=rdquo10rdquordquo
ldquohttpsandboxnoteyoudaocomoauthrequest_tokenrdquo
但是需要注意的是各个 key-value对都需要使用 OAuth编码 详见附录 D
备注
示例中的签名内容大致为(参数顺序可能有变化详见附录 D的签名过程)
GETamp
httpsandboxnoteyoudaocomoauthrequest_tokenampoauth_callback=oobampo
auth_consumer_key=7a23b1eaf487060deaa5660b323c341bampoauth_signature_
method=HMAC-SHA1ampoauth_timestamp=1321847131ampoauth_nonce=4395634
36203139ampoauth_version=10
具体签名方法详见附录 D
请求授权
URL [baseURL]oauthauthorize
请求方式GET
请求参数该处的参数必须以 query string的形式发送
参数名 参数说明
oauth_token 请求 request_token时返回的 oauth_token
正确时返回oauth_token(授权后的 request_token) 和 oauth_verifier
错误时返回error message
发送示例
GET http
sandboxnoteyoudaocomoauthauthorizeoauth_token=5420db084cc41d768d885
a53f7b2c1a6
备注如果 oauth_callback为 oob则不会回调用户会在 Oauth Server页面上
看到 pin 码用户需要手工将 pin 码粘帖到 application 中才能申请到
AccessToken应用请求 authorize时如果请求携带了网易或者有道的 cookie
则将直接询问用户是否授权否则会重新定向到网易的通行证页面
请求 access_token
URL[baseURL]oauthaccess_token
请求方式GET
请求参数
参数名 参数说明
oauth_consumer_key 回调 url
oauth_token request_token时返回的 oauth_token
oauth_verifier Authorize请求时发送回来的 oauth_verifier或者是
OauthServer页面显示的 Pin码
oauth_signature_method 签名方法支持 HMAC-SHA1
oauth_timestamp 时间戳当前时间单位毫秒
oauth_nonce 随机串为了防止重放攻击5分钟内同一用户同一应用同
一时间发来的请求中 oauth_nonce应不同
oauth_version 10
oauth_signature 使用 consumerSecret + rsquoamprsquo + oauth_token_secret
字串作为key 而签名的内容是除oauth_signature以外
的请求 url内容计算签名完毕后使用 base64编码
正确时返回oauth_token_secret (授权流程中的 access_secret)oauth_token
(授权流程中的 access_token)
错误时返回error message
发送示例 http header的例子
curl ndashH ldquoAuthorization OAuth
oauth_verifier=rdquo8714fb943a28d7faffec3265e96d85cdrdquo
oauth_token=rdquob348d10a0f45a4cf6936381d6c9fb00frdquo
oauth_consumer_key=rdquo7a23b1eaf487060deaa5660b323c341brdquo
oauth_signature_method=rdquoHMAC-SHA1rdquo oauth_timestamp=rdquo1321857128rdquo
oauth_nonce=rdquo449560105422526rdquo oauth_version=rdquo10rdquo
oauth_signature=rdquoS8yxdpLIA7MiFVDE4OzSDoo2F62FI3Drdquordquo
ldquohttpsandboxnoteyoudaocomoauthaccess_tokenrdquo
访问 OpenAPI
由 223 返回的 oauth_token 将用于 OpenAPI 的请求 consumerSecret + rsquoamprsquo +
oauth_token_secret 将 用 作 签 名 例 如 请 求 创 建 笔 记 本
http[baseURL]ywsopennotebookcreatejson则应在请求创建笔记中添加各
种参数(创建笔记本的其他参数按文档要求不变)如果没有则会返回 error
和 message(此处的 error和 message会放入到 json串中error是错误码 message
是具体错误信息)不会执行任何 OpenAPI操作
例如执行创建笔记本操作参数 name需和 oauth 的其他值一起进行签名
但是不应该将 name 放入 header 中并且发送 post 请求的 Content-Type 为
applicationx-www-form-urlencoded其他参数填入 http content 域Oauth 参数
放入 Authorization Header域否则可能会出现错误
对于上传笔记或者附件图片的 open API 中post 请求的 Content-Type 为
multipartform-data非 oauth参数均不参与签名非 oauth参数填入 http content
域Oauth参数放入 Authorization Header域否则可能会出现错误
对于使用 GET请求 http[baseURL]ywsopenusergetjson需要将 oauth参
数和非 oauth参数一起放入 url参数中签名时需注意参数顺序发送请求时参
数可以无序
POST
httpnoteyoudaocomywsopennotecreatejson
Header 中 Authorization的值为
OAuth[ 空 格 ]oauth_token=29cc36314495ee1cf55ebf26ca9711bc
oauth_consumer_key=407d014e17ad5cd02f3e0a55fcb198af
oauth_signature_method=HMAC-SHA1 oauth_timestamp=1323327110
oauth_nonce=280224628487931 oauth_version=10
oauth_signature=rXpd0apk82wMAZLun2FDSUt1wbQE3D
最终 Header类似于
Authorization=OAuth20oauth_token3D2229cc36314495ee1cf55ebf26ca
9711bc222C20oauth_consumer_key3D22407d014e17ad5cd02f3e0a55fcb198
af222C20oauth_signature_method3D22HMAC-SHA1222C20oauth_timest
amp3D221323327041222C20oauth_nonce3D22280155519121203222C20
oauth_version3D2210222C20oauth_signature3D22E252F8dFmTFGTmdC
FE2rnJ8f252Bkzw9c253D22
签名的具体方法详见附录 D访问 Oauth的类库包详见附录 C
用户操作 API
查看用户信息
URLhttp[baseURL]ywsopenusergetjson
请求方式GET
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数无
返回结果操作成功时 http 状态为 200并用户信息失败时 http 状态为
500并返回错误码和错误信息详见附录 B
结果示例
ldquouserrdquo ldquotest163comrdquo 用户 ID
ldquototal_sizerdquo ldquo10293736383rdquo 用户总的空间大小单位字节
ldquoused_sizerdquo ldquo1024rdquo 用户已经使用了的空间大小单位字节
ldquoregister_timerdquo ldquo1323310917650rdquo 用户注册时间单位毫秒
ldquolast_login_timerdquo ldquo1323310949120rdquo 用户最后登录时间单位毫秒
ldquolast_modify_timerdquo ldquo1323310978120rdquo 用户最后修改时间单位毫秒
ldquodefault_notebookrdquo ldquoAB384D734rdquo 该应用的默认笔记本
注对于每个第三方应用都分别在用户的笔记空间中对应一个默认笔记本
笔记本名在申请应用时指定在使用 OpenAPI创建笔记时如果第三方应用
不指定笔记本则自动创建在该默认笔记本中
笔记本操作 API
查看用户全部笔记本
URLhttp[baseURL]ywsopennotebookalljson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数无
返回结果操作成功时 http状态为 200并返回笔记本列表失败时 http状
态为 500并返回错误码和错误信息详见附录 B
结果示例
[
ldquopathrdquo ldquo4AF64012E9864Crdquo 笔记本的路径
ldquonamerdquo ldquo笔记本 1rdquo 笔记本的名称
ldquonotes_numrdquo ldquo3rdquo 该笔记本中笔记的数目
ldquocreate_timerdquo ldquo1323310917rdquo 笔记本的创建时间单位秒
ldquomodify_timerdquo ldquo1323310949rdquo 笔记本的最后修改时间单位秒
ldquopathrdquo ldquo5AB0C6B33BD1162rdquo
ldquonamerdquo ldquo笔记本 2rdquo
ldquonotes_numrdquo ldquo10rdquo
ldquocreate_timerdquo ldquo1323311244rdquo
ldquomodify_timerdquo ldquo1323310349rdquo
]
列出笔记本下的笔记
URLhttp[baseURL]ywsopennotebooklistjson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
notebook 笔记本路径 是 String
返回结果操作成功时 http状态为 200并返回该笔记本下的笔记列表(只
有笔记路径笔记内容需要通过笔记接口获取)失败时 http状态 500并返
回错误码和错误信息详见附录 B
结果示例
[
ldquo4AF64012E9864C123TDE3DCrdquo 笔记路径
ldquo4AF64012E9864CDC12FTDE3rdquo
ldquo4AF64012E9864CFE23TDE3Crdquo
]
创建笔记本
URL http[baseURL]ywsopennotebookcreatejson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
name 笔记本名称 是 String
返回结果操作成功时 http状态 200并返回新创建笔记本的路径失败时
http状态 500并返回错误码和错误信息详见附录 B
结果示例
ldquopathrdquo ldquo4AF64012E9864Crdquo
删除笔记本
URL http[baseURL]ywsopennotebookdeletejson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
notebook 笔记本路径 是 String
返回结果操作成功时 http状态 200无返回数据失败时 http状态 500并
返回错误码和错误信息详见附录 B
笔记操作 API
创建笔记
URL http[baseURL]ywsopennotecreatejson
请求方式POST
Content-Typemultipartform-data
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
source 笔记来源 URL 否 String
author 笔记作者 否 String
title 笔记标题 否 String
content 笔记正文(笔记格式见附录 A) 是 String
notebook 该新建笔记所属的笔记本路径 否 String
返回结果操作成功时 http状态为 200并返回新建笔记的路径失败时 http
状态为 500并返回错误码和错误信息详见附录 B
结果示例
ldquopathrdquo ldquo4AF64012E9864CFE89D12134Erdquo
注如果第三方应用没有指定 notebook则在该第三方应用对应的默认笔记
本中创建该笔记
查看笔记
URL http[baseURL]ywsopennotegetjson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
path 笔记路径 是 String
返回结果操作成功时 http状态为 200并返回该笔记的相关信息失败时
http状态为 500并返回错误码和错误信息详见附录 B
结果示例
ldquotitlerdquo ldquo工作记录rdquo 笔记标题
ldquoauthorrdquo ldquoTomrdquo 笔记作者
ldquosourcerdquo ldquohttpnoteyoudaocomrdquo 笔记来源 URL
ldquosizerdquo ldquo1024rdquo 笔记大小包括笔记正文及附件
ldquocreate_timerdquo ldquo1323310917rdquo 笔记的创建时间单位秒
ldquomodify_timerdquo ldquo1323310949rdquo 笔记的最后修改时间单位秒
ldquocontentrdquo ldquoltpgtThis is a test noteltpgt 笔记正文
修改笔记
URL http[baseURL]ywsopennoteupdatejson
请求方式POST
Content-Typemultipartform-data
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
path 修改笔记的路径 是 String
source 修改后的笔记来源 URL 否 String
author 修改后的笔记作者 否 String
title 修改后的笔记标题 否 String
content 修改后的笔记正文(笔记格式见
附录 A)
是 String
返回结果操作成功时 http 状态为 200无返回结果失败时 http 状态为
500并返回错误码和错误信息详见附录 B
移动笔记
URL http[baseURL]ywsopennotemovejson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
path 想要移动的笔记原路径 是 String
notebook 目标笔记本的路径 是 String
返回结果操作成功时 http状态为 200返回移动后的笔记路径失败时 http
状态为 500并返回错误码和错误信息详见附录 B
结果示例
ldquopathrdquo ldquo5AB0C6B33BD1162FE89D12134Erdquo
删除笔记
URL http[baseURL]ywsopennotedeletejson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
path 想要删除的笔记原路径 是 String
返回结果操作成功时 http 状态为 200无返回结果失败时 http 状态为
500并返回错误码和错误信息详见附录 B
附件操作 API
上传附件或图片
URLhttp[baseURL]ywsopenresourceuploadjson
请求方式POST
Content-Typemultipartform-data
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
file 上传的附件文件(包括附件的文
件名类型大小数据等)
是 Multipart File附件大
小限制 25M
返回结果操作成功时 http状态为 200对于图片返回该图片的链接 URL
对于普通附件服务器会为该附件生成一个图标文件因此返回结果包括该
附件对应的链接 URL以及图标的 URL失败时 http状态为 500并返回错误码
和错误信息详见附录 B
示例
图片附件
url httpbaseURLywsopenresource28d83f547f3055
普通附件
url httpbaseURLywsopenresource28d83f547f3055 附件 URL
src httpbaseURLywsopenresource297f2bd6fa2795 图标 URL
需要注意的是在附件上传完成后使用者应该紧接着更新对应的笔记否
则不被任何笔记引用的附件将被定期的空间回收所删除
下载附件图片图标
URLhttp[baseURL]ywsopenresourcedownload
请求方式GET
是否需要用户认证是 (关于登录授权参见请求用户授权)
返回结果操作成功时response返回附件及图片的二进制流失败时 http
状态为 500并返回错误码和错误信息详见附录 B
备注
1 当打开笔记时对于笔记中的附件及图片链接只需要添加用户的 OAuth
认证信息即可以获取对应的附件及图片同理在上传附件后返回的附
件及图片链接也可以通过这种方式进行访问
2 附件及图片的下载支持断点续传
附录 A有道云笔记内容格式
笔记内容的格式采用类 HTML的标记语言绝大部分格式相关 tag均采用标
准的 HTML Tag唯一需要不同的是附件及图片 Tag在格式上图片 Tag与标准的
img tag相同一个图片资源的标记如下
ltimg src=httpnoteyoudaocomywsopenresource227f2bd6fa2795441cgt
但是由于对应的接口需要用户认证因此在获取图片资源时需要加入 OAuth
的用户认证信息
附件通常以图标在笔记中进行显示因此我们扩展了图片 Tag ltimggt除了
img 本身的 src 属性额外加入了一个属性 path其中 src 对应着该附件的图标
URL而 path则为该附件的 URL如下所示
ltimg path=httpnoteyoudaocomywsopenresource219fe604c7c90642fd8f
src=httpnoteyoudaocomywsopenresource227f2bd6fa2795441cgt
同理也需要加入 OAuth的用户认证信息才可以正常访问附件资源及其图标
附录 B错误码及错误信息说明
同理当 Open API的请求在执行时出现任何异常或错误时系统将返回 Http
500应用程序可以根据此判断请求是否成功执行当应用程序在进行 OAuth认
证或者未经认证便调用 Open API时系统会返回 OAuth错误信息OAuth的
错误码与错误信息将以 json的格式进行返回各个错误码及错误信息说明如下
错误码 错误描述及可能原因
1001 token_rejectedconsumer没有找到consumerKey错误 consumer
没有创建或者 request token或者 access token 不存在于 server中
或者没有获得授权的 token或者 token过期
1002 parameter_rejected这个会返回具体原因 key是
oauth_parameters_rejected value是一个 parameter列表
1003 version_rejectedOAuth版本号不是 10
1004 timestamp_refusedtimestamp 非 5分钟内
1005 nonce_used5分钟内该 nonce被使用
1006 parameter_absent有些参数没有发送给 server
1007 signature_invalidoauth签名异常可能原因没有签名签名方法和
签名不一致等
1008 signature_method_rejectedoauth server没有提供该签名方法
1009 access_state_error获取 token时状态混乱详细的信息会告知当前的
状态 [AUTHORIZED | REQUEST | ACCESS | INVALID]
1010 consumer_rejected该 consumer在 server中不存在或者被禁掉
或者 consumerKey改变但是还没有反应到 server的数据库中
1011 accessor_rejected由 token得到的 accessor构造异常或者 accessor
中缺失某些属性或者转换失败
1012 callback_errorrequest token传来的 callback和以后的 callback不一致
1013 callback_domain_error当限定 callback后发来的 callback与原设置
的 callback的域不相同
1014 verifier_errorVerifier不一致错误
1015 permission_denied无授权的 token或者授权后没有获取过 access
token
同理当 Open API的请求在后台执行出现异常或错误时系统也将同时错
误码与错误信息以 json 的格式一同返回应用程序可以根据错误码得到相应的
原因常见的错误码说明如下
错误码 错误描述及可能原因
206 UNKNOWN_URI错误的 URI请求
207 AUTHENTICATION_FAILURE用户认证错误
209 RESOURCE_NOT_EXIST请求的资源(笔记本笔记附件等)不存在
210 USER_SPACE_FULL用户空间已满
214 INVALID_PARAMETER错误的传入参数必须的参数为空等
220 USER_NOT_EXISTS用户不存在
221 USER_ALREADY_EXISTS用户已经存在不能重复注册
225 PARENT_NOT_EXIST笔记本尚不存在不能在该笔记本下创建笔记
231 RESOURCE_ALREADY_EXIST该笔记或者附件已经存在不能重复创建
304 NOTE_ALREADY_DELETED笔记已经被删除
307 INVALID_APPLICATION无效的第三方应用未经过用户授权或者授权
失败便通过 OpenAPI访问用户数据这个一般是使用测试环境得到了
access_token利用该 access_token访问了线上环境这两套环境是独
立的Access_token不能共用
但是如果第三方应用未经过用户授权
示例当查看笔记路径错误时
error 209
message Required note does not exist path=5AB0C6B33BD12FE89D12134E
附录 C 访问 OAuth Server的类库与包
ActionScriptFlash
oauth-as3 httpcodegooglecompoauth-as3
A flex oauth client
httpwwwarcgiscomhomeitemhtmlid=ff6ffa302ad04a7194999f2ad08250d7
CC++
QTweetLib httpgithubcomminimoogQTweetLib
libOAuth httpliboauthsourceforgenet
clojure
clj-oauth httpgithubcommattreplclj-oauth
net
oauth-dot-net httpcodegooglecompoauth-dot-net
DotNetOpenAuth httpwwwdotnetopenauthnet
Erlang
erlang-oauth httpgithubcomtimerlang-oauth
java
Scrible httpgithubcomfernandezpablo85scribe-java
oauth-signpost httpcodegooglecompoauth-signpost
javascript
oauth in js httpoauthgooglecodecomsvncodejavascript
Objective-CCocoa amp iPhone programming
OAuthCore httpbitbucketorgatebitsoauthcore
MPOAuthConnection httpcodegooglecompmpoauthconnection
Objective-C OAuth httpoauthgooglecodecomsvncodeobj-c
Perl
NetOAuth httpoauthgooglecodecomsvncodeperl
PHP
tmhOAuth httpgithubcomthemattharristmhOAuth
oauth-php httpcodegooglecompoauth-php
Python
python-oauth2 httpgithubcombrosnerpython-oauth2
Qt
qOauth httpgithubcomayoyqoauth
Ruby
Oauth ruby gem httpoauthrubyforgeorg
Scala
DataBinder Dispatch httpdispatchdatabindernetAbout
附录 D Oauth签名加密 oauth_signature
1 加密内容是
a 请求方法名例如 GET POST等 加密时方法名大写并进行特殊替换
(详见 3)
b url (query param之前的部分不包括 )Http或者 https需要全部小
写 http如果带有 80端口或者 https带有 443端口需要将其省略
其他端口则不能省略例如
Httplocal9999requestToken
httplocal9999requestToken
Httplocal80requestToken
httplocalrequestToken
Httpslocal443requestToken
httpslocal requestToken
c 参数(query param中的或者 header中的 key-value对) 首先将这些参数
进行特殊替换后按字典序排序升序排列如果两个 key相同则以
value特殊替换后字典序为准key与 value之间使用rdquo=rdquo连接如果
value==null则使用rdquordquo替代两个参数对之间使用rdquoamprdquo连接连接后形成
的最终字符串的开头和结尾没有rdquoamprdquo
d 字典序字符串比较大小伪代码
Int compare(string a string b)
Int min_len = min(len(a) len(b))
For I to min_len
If (a[i] = b[i])
Return a[i] ndash b[i]
Return len(a) ndash len(b)
将以上 abc三部分进行特殊替换后使用amp连接最终形成的字符串的
开头和结尾都没有rdquoamprdquo这就是加密内容
2 加密的 key是 consumerSecret + amp + TokenSecret 如果 TokenSecret还没有
得到则使用rdquordquo consumerSecret和 TokenSecret需先做特殊替换然后
再进行签名
3 特殊替换是将 String进行 URL编码后将rdquo+rdquo替换为rdquo20rdquo将rdquordquo替换
为rdquo2Ardquo将rdquo7Erdquo替换为rdquo~rdquo
4 签名方法可以使用 HMAC-SHA1PLAINTEXT RSA_SHA1三种其中
PLAINTEXT为 2中的 key 该方法不提倡使用
得到签名内容后使用 Base64进行编码编码后的字符串即为 oauth_signature
授权请求参数方法和返回值
下面将介绍如何使用 OauthServer服务得到 access_token和 access_secret下
面的文字中[baseURL]指代 OauthServer 的 URL对于线上环境该 baseURL
即为 httpnoteyoudaocom而对于 sandbox 测试环境该 baseURL 为
httpsandboxnoteyoudaocom这里使用 HTTP Header设置参数 Header
name 设 为 Authorization Header value 设 为 OAuth[ 空
格][parameterName=rdquovaluerdquo][空格][ parameterName=rdquovaluerdquo]hellip 值得注意
的是 parameterName 和 value 必须进行 URL 编码并且在 URL 编码后还要
将 rdquo+rdquo替换为 rdquo20rdquo将rdquordquo替换为 rdquo2Ardquo将 rdquo7Erdquo替换为 rdquo~rdquo例如请求
authorized token时 HTTP header中的 value是
OAuth[ 空 格 ]oauth_token=29cc36314495ee1cf55ebf26ca9711bc[ 空 格 ]
oauth_consumer_key=407d014e17ad5cd02f3e0a55fcb198af [ 空
格 ]oauth_signature_method=HMAC-SHA1[ 空
格 ]oauth_timestamp=1323325710[ 空
格 ]oauth_nonce=278825208972307[ 空 格 ]oauth_version=10[ 空 格 ]
oauth_signature=x8E7wrAmn6GyHv4aldWSo1M2ShU3D 注意其中双引
号rdquordquo是必须的 发送请求时这些参数可以是无序的但是签名时这些参
数有一定的顺序详见附录 D
以下各个请求正确时返回值 content-type 为 textplain 返回
key=value[空格]key=value
以下各个请求错误时会返回错误信息该信息包含 error message等
error是错误码message包含更详尽的错误信息另外特殊错误时还可能返
回更多信息详见附录 B
请求 request_token
URL[baseURL]oauthrequest_token
请求方式GET
请求参数
参数名 参数说明
oauth_callback 回调 url该 url可以为 oob代表不回调另外 url还可
以跟其他参数
oauth_consumer_key 申请应用时拿到的 consumerKey
oauth_signature_method 签名方法支持 HMAC-SHA1
oauth_timestamp 时间戳当前时间单位毫秒
oauth_nonce 随机串为了防止重放攻击5分钟内同一用户同一应用同
一时间发来的请求中 oauth_nonce应不同
oauth_version 10
oauth_signature 签名使用 consumerSecret +rsquoamprsquo作为签名的 key 而
签名的内容是除 oath_signature以外的请求 url内容
计算签名完毕后使用 base64编码
正确时返回oauth_token_secret(授权流程中的 request_secret 用于申请
access_token 时签名) oauth_token(授权流程中的 requset_token 用于
authorize请求和 access_token请求)和 oauth_callback_confirmed(boolean
值)
错误时返回 error message error是 error code message是错误信息以 json
串形式返回
发送示例
用 curl来举例 请求信息类似于
curl ndashH ldquoAuthorization OAuth oauth_callback=rdquooobrdquo
oauth_consumer_key=rdquo7a23b1eaf487060deaa5660b323c341brdquo
oauth_signature_method=rdquoHMAC-SHA1rdquo oauth_timestamp=rdquo1321847131rdquo
oauth_nonce=rdquo439563436203139rdquo oauth_version=rdquo10rdquordquo
ldquohttpsandboxnoteyoudaocomoauthrequest_tokenrdquo
但是需要注意的是各个 key-value对都需要使用 OAuth编码 详见附录 D
备注
示例中的签名内容大致为(参数顺序可能有变化详见附录 D的签名过程)
GETamp
httpsandboxnoteyoudaocomoauthrequest_tokenampoauth_callback=oobampo
auth_consumer_key=7a23b1eaf487060deaa5660b323c341bampoauth_signature_
method=HMAC-SHA1ampoauth_timestamp=1321847131ampoauth_nonce=4395634
36203139ampoauth_version=10
具体签名方法详见附录 D
请求授权
URL [baseURL]oauthauthorize
请求方式GET
请求参数该处的参数必须以 query string的形式发送
参数名 参数说明
oauth_token 请求 request_token时返回的 oauth_token
正确时返回oauth_token(授权后的 request_token) 和 oauth_verifier
错误时返回error message
发送示例
GET http
sandboxnoteyoudaocomoauthauthorizeoauth_token=5420db084cc41d768d885
a53f7b2c1a6
备注如果 oauth_callback为 oob则不会回调用户会在 Oauth Server页面上
看到 pin 码用户需要手工将 pin 码粘帖到 application 中才能申请到
AccessToken应用请求 authorize时如果请求携带了网易或者有道的 cookie
则将直接询问用户是否授权否则会重新定向到网易的通行证页面
请求 access_token
URL[baseURL]oauthaccess_token
请求方式GET
请求参数
参数名 参数说明
oauth_consumer_key 回调 url
oauth_token request_token时返回的 oauth_token
oauth_verifier Authorize请求时发送回来的 oauth_verifier或者是
OauthServer页面显示的 Pin码
oauth_signature_method 签名方法支持 HMAC-SHA1
oauth_timestamp 时间戳当前时间单位毫秒
oauth_nonce 随机串为了防止重放攻击5分钟内同一用户同一应用同
一时间发来的请求中 oauth_nonce应不同
oauth_version 10
oauth_signature 使用 consumerSecret + rsquoamprsquo + oauth_token_secret
字串作为key 而签名的内容是除oauth_signature以外
的请求 url内容计算签名完毕后使用 base64编码
正确时返回oauth_token_secret (授权流程中的 access_secret)oauth_token
(授权流程中的 access_token)
错误时返回error message
发送示例 http header的例子
curl ndashH ldquoAuthorization OAuth
oauth_verifier=rdquo8714fb943a28d7faffec3265e96d85cdrdquo
oauth_token=rdquob348d10a0f45a4cf6936381d6c9fb00frdquo
oauth_consumer_key=rdquo7a23b1eaf487060deaa5660b323c341brdquo
oauth_signature_method=rdquoHMAC-SHA1rdquo oauth_timestamp=rdquo1321857128rdquo
oauth_nonce=rdquo449560105422526rdquo oauth_version=rdquo10rdquo
oauth_signature=rdquoS8yxdpLIA7MiFVDE4OzSDoo2F62FI3Drdquordquo
ldquohttpsandboxnoteyoudaocomoauthaccess_tokenrdquo
访问 OpenAPI
由 223 返回的 oauth_token 将用于 OpenAPI 的请求 consumerSecret + rsquoamprsquo +
oauth_token_secret 将 用 作 签 名 例 如 请 求 创 建 笔 记 本
http[baseURL]ywsopennotebookcreatejson则应在请求创建笔记中添加各
种参数(创建笔记本的其他参数按文档要求不变)如果没有则会返回 error
和 message(此处的 error和 message会放入到 json串中error是错误码 message
是具体错误信息)不会执行任何 OpenAPI操作
例如执行创建笔记本操作参数 name需和 oauth 的其他值一起进行签名
但是不应该将 name 放入 header 中并且发送 post 请求的 Content-Type 为
applicationx-www-form-urlencoded其他参数填入 http content 域Oauth 参数
放入 Authorization Header域否则可能会出现错误
对于上传笔记或者附件图片的 open API 中post 请求的 Content-Type 为
multipartform-data非 oauth参数均不参与签名非 oauth参数填入 http content
域Oauth参数放入 Authorization Header域否则可能会出现错误
对于使用 GET请求 http[baseURL]ywsopenusergetjson需要将 oauth参
数和非 oauth参数一起放入 url参数中签名时需注意参数顺序发送请求时参
数可以无序
POST
httpnoteyoudaocomywsopennotecreatejson
Header 中 Authorization的值为
OAuth[ 空 格 ]oauth_token=29cc36314495ee1cf55ebf26ca9711bc
oauth_consumer_key=407d014e17ad5cd02f3e0a55fcb198af
oauth_signature_method=HMAC-SHA1 oauth_timestamp=1323327110
oauth_nonce=280224628487931 oauth_version=10
oauth_signature=rXpd0apk82wMAZLun2FDSUt1wbQE3D
最终 Header类似于
Authorization=OAuth20oauth_token3D2229cc36314495ee1cf55ebf26ca
9711bc222C20oauth_consumer_key3D22407d014e17ad5cd02f3e0a55fcb198
af222C20oauth_signature_method3D22HMAC-SHA1222C20oauth_timest
amp3D221323327041222C20oauth_nonce3D22280155519121203222C20
oauth_version3D2210222C20oauth_signature3D22E252F8dFmTFGTmdC
FE2rnJ8f252Bkzw9c253D22
签名的具体方法详见附录 D访问 Oauth的类库包详见附录 C
用户操作 API
查看用户信息
URLhttp[baseURL]ywsopenusergetjson
请求方式GET
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数无
返回结果操作成功时 http 状态为 200并用户信息失败时 http 状态为
500并返回错误码和错误信息详见附录 B
结果示例
ldquouserrdquo ldquotest163comrdquo 用户 ID
ldquototal_sizerdquo ldquo10293736383rdquo 用户总的空间大小单位字节
ldquoused_sizerdquo ldquo1024rdquo 用户已经使用了的空间大小单位字节
ldquoregister_timerdquo ldquo1323310917650rdquo 用户注册时间单位毫秒
ldquolast_login_timerdquo ldquo1323310949120rdquo 用户最后登录时间单位毫秒
ldquolast_modify_timerdquo ldquo1323310978120rdquo 用户最后修改时间单位毫秒
ldquodefault_notebookrdquo ldquoAB384D734rdquo 该应用的默认笔记本
注对于每个第三方应用都分别在用户的笔记空间中对应一个默认笔记本
笔记本名在申请应用时指定在使用 OpenAPI创建笔记时如果第三方应用
不指定笔记本则自动创建在该默认笔记本中
笔记本操作 API
查看用户全部笔记本
URLhttp[baseURL]ywsopennotebookalljson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数无
返回结果操作成功时 http状态为 200并返回笔记本列表失败时 http状
态为 500并返回错误码和错误信息详见附录 B
结果示例
[
ldquopathrdquo ldquo4AF64012E9864Crdquo 笔记本的路径
ldquonamerdquo ldquo笔记本 1rdquo 笔记本的名称
ldquonotes_numrdquo ldquo3rdquo 该笔记本中笔记的数目
ldquocreate_timerdquo ldquo1323310917rdquo 笔记本的创建时间单位秒
ldquomodify_timerdquo ldquo1323310949rdquo 笔记本的最后修改时间单位秒
ldquopathrdquo ldquo5AB0C6B33BD1162rdquo
ldquonamerdquo ldquo笔记本 2rdquo
ldquonotes_numrdquo ldquo10rdquo
ldquocreate_timerdquo ldquo1323311244rdquo
ldquomodify_timerdquo ldquo1323310349rdquo
]
列出笔记本下的笔记
URLhttp[baseURL]ywsopennotebooklistjson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
notebook 笔记本路径 是 String
返回结果操作成功时 http状态为 200并返回该笔记本下的笔记列表(只
有笔记路径笔记内容需要通过笔记接口获取)失败时 http状态 500并返
回错误码和错误信息详见附录 B
结果示例
[
ldquo4AF64012E9864C123TDE3DCrdquo 笔记路径
ldquo4AF64012E9864CDC12FTDE3rdquo
ldquo4AF64012E9864CFE23TDE3Crdquo
]
创建笔记本
URL http[baseURL]ywsopennotebookcreatejson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
name 笔记本名称 是 String
返回结果操作成功时 http状态 200并返回新创建笔记本的路径失败时
http状态 500并返回错误码和错误信息详见附录 B
结果示例
ldquopathrdquo ldquo4AF64012E9864Crdquo
删除笔记本
URL http[baseURL]ywsopennotebookdeletejson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
notebook 笔记本路径 是 String
返回结果操作成功时 http状态 200无返回数据失败时 http状态 500并
返回错误码和错误信息详见附录 B
笔记操作 API
创建笔记
URL http[baseURL]ywsopennotecreatejson
请求方式POST
Content-Typemultipartform-data
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
source 笔记来源 URL 否 String
author 笔记作者 否 String
title 笔记标题 否 String
content 笔记正文(笔记格式见附录 A) 是 String
notebook 该新建笔记所属的笔记本路径 否 String
返回结果操作成功时 http状态为 200并返回新建笔记的路径失败时 http
状态为 500并返回错误码和错误信息详见附录 B
结果示例
ldquopathrdquo ldquo4AF64012E9864CFE89D12134Erdquo
注如果第三方应用没有指定 notebook则在该第三方应用对应的默认笔记
本中创建该笔记
查看笔记
URL http[baseURL]ywsopennotegetjson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
path 笔记路径 是 String
返回结果操作成功时 http状态为 200并返回该笔记的相关信息失败时
http状态为 500并返回错误码和错误信息详见附录 B
结果示例
ldquotitlerdquo ldquo工作记录rdquo 笔记标题
ldquoauthorrdquo ldquoTomrdquo 笔记作者
ldquosourcerdquo ldquohttpnoteyoudaocomrdquo 笔记来源 URL
ldquosizerdquo ldquo1024rdquo 笔记大小包括笔记正文及附件
ldquocreate_timerdquo ldquo1323310917rdquo 笔记的创建时间单位秒
ldquomodify_timerdquo ldquo1323310949rdquo 笔记的最后修改时间单位秒
ldquocontentrdquo ldquoltpgtThis is a test noteltpgt 笔记正文
修改笔记
URL http[baseURL]ywsopennoteupdatejson
请求方式POST
Content-Typemultipartform-data
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
path 修改笔记的路径 是 String
source 修改后的笔记来源 URL 否 String
author 修改后的笔记作者 否 String
title 修改后的笔记标题 否 String
content 修改后的笔记正文(笔记格式见
附录 A)
是 String
返回结果操作成功时 http 状态为 200无返回结果失败时 http 状态为
500并返回错误码和错误信息详见附录 B
移动笔记
URL http[baseURL]ywsopennotemovejson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
path 想要移动的笔记原路径 是 String
notebook 目标笔记本的路径 是 String
返回结果操作成功时 http状态为 200返回移动后的笔记路径失败时 http
状态为 500并返回错误码和错误信息详见附录 B
结果示例
ldquopathrdquo ldquo5AB0C6B33BD1162FE89D12134Erdquo
删除笔记
URL http[baseURL]ywsopennotedeletejson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
path 想要删除的笔记原路径 是 String
返回结果操作成功时 http 状态为 200无返回结果失败时 http 状态为
500并返回错误码和错误信息详见附录 B
附件操作 API
上传附件或图片
URLhttp[baseURL]ywsopenresourceuploadjson
请求方式POST
Content-Typemultipartform-data
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
file 上传的附件文件(包括附件的文
件名类型大小数据等)
是 Multipart File附件大
小限制 25M
返回结果操作成功时 http状态为 200对于图片返回该图片的链接 URL
对于普通附件服务器会为该附件生成一个图标文件因此返回结果包括该
附件对应的链接 URL以及图标的 URL失败时 http状态为 500并返回错误码
和错误信息详见附录 B
示例
图片附件
url httpbaseURLywsopenresource28d83f547f3055
普通附件
url httpbaseURLywsopenresource28d83f547f3055 附件 URL
src httpbaseURLywsopenresource297f2bd6fa2795 图标 URL
需要注意的是在附件上传完成后使用者应该紧接着更新对应的笔记否
则不被任何笔记引用的附件将被定期的空间回收所删除
下载附件图片图标
URLhttp[baseURL]ywsopenresourcedownload
请求方式GET
是否需要用户认证是 (关于登录授权参见请求用户授权)
返回结果操作成功时response返回附件及图片的二进制流失败时 http
状态为 500并返回错误码和错误信息详见附录 B
备注
1 当打开笔记时对于笔记中的附件及图片链接只需要添加用户的 OAuth
认证信息即可以获取对应的附件及图片同理在上传附件后返回的附
件及图片链接也可以通过这种方式进行访问
2 附件及图片的下载支持断点续传
附录 A有道云笔记内容格式
笔记内容的格式采用类 HTML的标记语言绝大部分格式相关 tag均采用标
准的 HTML Tag唯一需要不同的是附件及图片 Tag在格式上图片 Tag与标准的
img tag相同一个图片资源的标记如下
ltimg src=httpnoteyoudaocomywsopenresource227f2bd6fa2795441cgt
但是由于对应的接口需要用户认证因此在获取图片资源时需要加入 OAuth
的用户认证信息
附件通常以图标在笔记中进行显示因此我们扩展了图片 Tag ltimggt除了
img 本身的 src 属性额外加入了一个属性 path其中 src 对应着该附件的图标
URL而 path则为该附件的 URL如下所示
ltimg path=httpnoteyoudaocomywsopenresource219fe604c7c90642fd8f
src=httpnoteyoudaocomywsopenresource227f2bd6fa2795441cgt
同理也需要加入 OAuth的用户认证信息才可以正常访问附件资源及其图标
附录 B错误码及错误信息说明
同理当 Open API的请求在执行时出现任何异常或错误时系统将返回 Http
500应用程序可以根据此判断请求是否成功执行当应用程序在进行 OAuth认
证或者未经认证便调用 Open API时系统会返回 OAuth错误信息OAuth的
错误码与错误信息将以 json的格式进行返回各个错误码及错误信息说明如下
错误码 错误描述及可能原因
1001 token_rejectedconsumer没有找到consumerKey错误 consumer
没有创建或者 request token或者 access token 不存在于 server中
或者没有获得授权的 token或者 token过期
1002 parameter_rejected这个会返回具体原因 key是
oauth_parameters_rejected value是一个 parameter列表
1003 version_rejectedOAuth版本号不是 10
1004 timestamp_refusedtimestamp 非 5分钟内
1005 nonce_used5分钟内该 nonce被使用
1006 parameter_absent有些参数没有发送给 server
1007 signature_invalidoauth签名异常可能原因没有签名签名方法和
签名不一致等
1008 signature_method_rejectedoauth server没有提供该签名方法
1009 access_state_error获取 token时状态混乱详细的信息会告知当前的
状态 [AUTHORIZED | REQUEST | ACCESS | INVALID]
1010 consumer_rejected该 consumer在 server中不存在或者被禁掉
或者 consumerKey改变但是还没有反应到 server的数据库中
1011 accessor_rejected由 token得到的 accessor构造异常或者 accessor
中缺失某些属性或者转换失败
1012 callback_errorrequest token传来的 callback和以后的 callback不一致
1013 callback_domain_error当限定 callback后发来的 callback与原设置
的 callback的域不相同
1014 verifier_errorVerifier不一致错误
1015 permission_denied无授权的 token或者授权后没有获取过 access
token
同理当 Open API的请求在后台执行出现异常或错误时系统也将同时错
误码与错误信息以 json 的格式一同返回应用程序可以根据错误码得到相应的
原因常见的错误码说明如下
错误码 错误描述及可能原因
206 UNKNOWN_URI错误的 URI请求
207 AUTHENTICATION_FAILURE用户认证错误
209 RESOURCE_NOT_EXIST请求的资源(笔记本笔记附件等)不存在
210 USER_SPACE_FULL用户空间已满
214 INVALID_PARAMETER错误的传入参数必须的参数为空等
220 USER_NOT_EXISTS用户不存在
221 USER_ALREADY_EXISTS用户已经存在不能重复注册
225 PARENT_NOT_EXIST笔记本尚不存在不能在该笔记本下创建笔记
231 RESOURCE_ALREADY_EXIST该笔记或者附件已经存在不能重复创建
304 NOTE_ALREADY_DELETED笔记已经被删除
307 INVALID_APPLICATION无效的第三方应用未经过用户授权或者授权
失败便通过 OpenAPI访问用户数据这个一般是使用测试环境得到了
access_token利用该 access_token访问了线上环境这两套环境是独
立的Access_token不能共用
但是如果第三方应用未经过用户授权
示例当查看笔记路径错误时
error 209
message Required note does not exist path=5AB0C6B33BD12FE89D12134E
附录 C 访问 OAuth Server的类库与包
ActionScriptFlash
oauth-as3 httpcodegooglecompoauth-as3
A flex oauth client
httpwwwarcgiscomhomeitemhtmlid=ff6ffa302ad04a7194999f2ad08250d7
CC++
QTweetLib httpgithubcomminimoogQTweetLib
libOAuth httpliboauthsourceforgenet
clojure
clj-oauth httpgithubcommattreplclj-oauth
net
oauth-dot-net httpcodegooglecompoauth-dot-net
DotNetOpenAuth httpwwwdotnetopenauthnet
Erlang
erlang-oauth httpgithubcomtimerlang-oauth
java
Scrible httpgithubcomfernandezpablo85scribe-java
oauth-signpost httpcodegooglecompoauth-signpost
javascript
oauth in js httpoauthgooglecodecomsvncodejavascript
Objective-CCocoa amp iPhone programming
OAuthCore httpbitbucketorgatebitsoauthcore
MPOAuthConnection httpcodegooglecompmpoauthconnection
Objective-C OAuth httpoauthgooglecodecomsvncodeobj-c
Perl
NetOAuth httpoauthgooglecodecomsvncodeperl
PHP
tmhOAuth httpgithubcomthemattharristmhOAuth
oauth-php httpcodegooglecompoauth-php
Python
python-oauth2 httpgithubcombrosnerpython-oauth2
Qt
qOauth httpgithubcomayoyqoauth
Ruby
Oauth ruby gem httpoauthrubyforgeorg
Scala
DataBinder Dispatch httpdispatchdatabindernetAbout
附录 D Oauth签名加密 oauth_signature
1 加密内容是
a 请求方法名例如 GET POST等 加密时方法名大写并进行特殊替换
(详见 3)
b url (query param之前的部分不包括 )Http或者 https需要全部小
写 http如果带有 80端口或者 https带有 443端口需要将其省略
其他端口则不能省略例如
Httplocal9999requestToken
httplocal9999requestToken
Httplocal80requestToken
httplocalrequestToken
Httpslocal443requestToken
httpslocal requestToken
c 参数(query param中的或者 header中的 key-value对) 首先将这些参数
进行特殊替换后按字典序排序升序排列如果两个 key相同则以
value特殊替换后字典序为准key与 value之间使用rdquo=rdquo连接如果
value==null则使用rdquordquo替代两个参数对之间使用rdquoamprdquo连接连接后形成
的最终字符串的开头和结尾没有rdquoamprdquo
d 字典序字符串比较大小伪代码
Int compare(string a string b)
Int min_len = min(len(a) len(b))
For I to min_len
If (a[i] = b[i])
Return a[i] ndash b[i]
Return len(a) ndash len(b)
将以上 abc三部分进行特殊替换后使用amp连接最终形成的字符串的
开头和结尾都没有rdquoamprdquo这就是加密内容
2 加密的 key是 consumerSecret + amp + TokenSecret 如果 TokenSecret还没有
得到则使用rdquordquo consumerSecret和 TokenSecret需先做特殊替换然后
再进行签名
3 特殊替换是将 String进行 URL编码后将rdquo+rdquo替换为rdquo20rdquo将rdquordquo替换
为rdquo2Ardquo将rdquo7Erdquo替换为rdquo~rdquo
4 签名方法可以使用 HMAC-SHA1PLAINTEXT RSA_SHA1三种其中
PLAINTEXT为 2中的 key 该方法不提倡使用
得到签名内容后使用 Base64进行编码编码后的字符串即为 oauth_signature
oauth_consumer_key 申请应用时拿到的 consumerKey
oauth_signature_method 签名方法支持 HMAC-SHA1
oauth_timestamp 时间戳当前时间单位毫秒
oauth_nonce 随机串为了防止重放攻击5分钟内同一用户同一应用同
一时间发来的请求中 oauth_nonce应不同
oauth_version 10
oauth_signature 签名使用 consumerSecret +rsquoamprsquo作为签名的 key 而
签名的内容是除 oath_signature以外的请求 url内容
计算签名完毕后使用 base64编码
正确时返回oauth_token_secret(授权流程中的 request_secret 用于申请
access_token 时签名) oauth_token(授权流程中的 requset_token 用于
authorize请求和 access_token请求)和 oauth_callback_confirmed(boolean
值)
错误时返回 error message error是 error code message是错误信息以 json
串形式返回
发送示例
用 curl来举例 请求信息类似于
curl ndashH ldquoAuthorization OAuth oauth_callback=rdquooobrdquo
oauth_consumer_key=rdquo7a23b1eaf487060deaa5660b323c341brdquo
oauth_signature_method=rdquoHMAC-SHA1rdquo oauth_timestamp=rdquo1321847131rdquo
oauth_nonce=rdquo439563436203139rdquo oauth_version=rdquo10rdquordquo
ldquohttpsandboxnoteyoudaocomoauthrequest_tokenrdquo
但是需要注意的是各个 key-value对都需要使用 OAuth编码 详见附录 D
备注
示例中的签名内容大致为(参数顺序可能有变化详见附录 D的签名过程)
GETamp
httpsandboxnoteyoudaocomoauthrequest_tokenampoauth_callback=oobampo
auth_consumer_key=7a23b1eaf487060deaa5660b323c341bampoauth_signature_
method=HMAC-SHA1ampoauth_timestamp=1321847131ampoauth_nonce=4395634
36203139ampoauth_version=10
具体签名方法详见附录 D
请求授权
URL [baseURL]oauthauthorize
请求方式GET
请求参数该处的参数必须以 query string的形式发送
参数名 参数说明
oauth_token 请求 request_token时返回的 oauth_token
正确时返回oauth_token(授权后的 request_token) 和 oauth_verifier
错误时返回error message
发送示例
GET http
sandboxnoteyoudaocomoauthauthorizeoauth_token=5420db084cc41d768d885
a53f7b2c1a6
备注如果 oauth_callback为 oob则不会回调用户会在 Oauth Server页面上
看到 pin 码用户需要手工将 pin 码粘帖到 application 中才能申请到
AccessToken应用请求 authorize时如果请求携带了网易或者有道的 cookie
则将直接询问用户是否授权否则会重新定向到网易的通行证页面
请求 access_token
URL[baseURL]oauthaccess_token
请求方式GET
请求参数
参数名 参数说明
oauth_consumer_key 回调 url
oauth_token request_token时返回的 oauth_token
oauth_verifier Authorize请求时发送回来的 oauth_verifier或者是
OauthServer页面显示的 Pin码
oauth_signature_method 签名方法支持 HMAC-SHA1
oauth_timestamp 时间戳当前时间单位毫秒
oauth_nonce 随机串为了防止重放攻击5分钟内同一用户同一应用同
一时间发来的请求中 oauth_nonce应不同
oauth_version 10
oauth_signature 使用 consumerSecret + rsquoamprsquo + oauth_token_secret
字串作为key 而签名的内容是除oauth_signature以外
的请求 url内容计算签名完毕后使用 base64编码
正确时返回oauth_token_secret (授权流程中的 access_secret)oauth_token
(授权流程中的 access_token)
错误时返回error message
发送示例 http header的例子
curl ndashH ldquoAuthorization OAuth
oauth_verifier=rdquo8714fb943a28d7faffec3265e96d85cdrdquo
oauth_token=rdquob348d10a0f45a4cf6936381d6c9fb00frdquo
oauth_consumer_key=rdquo7a23b1eaf487060deaa5660b323c341brdquo
oauth_signature_method=rdquoHMAC-SHA1rdquo oauth_timestamp=rdquo1321857128rdquo
oauth_nonce=rdquo449560105422526rdquo oauth_version=rdquo10rdquo
oauth_signature=rdquoS8yxdpLIA7MiFVDE4OzSDoo2F62FI3Drdquordquo
ldquohttpsandboxnoteyoudaocomoauthaccess_tokenrdquo
访问 OpenAPI
由 223 返回的 oauth_token 将用于 OpenAPI 的请求 consumerSecret + rsquoamprsquo +
oauth_token_secret 将 用 作 签 名 例 如 请 求 创 建 笔 记 本
http[baseURL]ywsopennotebookcreatejson则应在请求创建笔记中添加各
种参数(创建笔记本的其他参数按文档要求不变)如果没有则会返回 error
和 message(此处的 error和 message会放入到 json串中error是错误码 message
是具体错误信息)不会执行任何 OpenAPI操作
例如执行创建笔记本操作参数 name需和 oauth 的其他值一起进行签名
但是不应该将 name 放入 header 中并且发送 post 请求的 Content-Type 为
applicationx-www-form-urlencoded其他参数填入 http content 域Oauth 参数
放入 Authorization Header域否则可能会出现错误
对于上传笔记或者附件图片的 open API 中post 请求的 Content-Type 为
multipartform-data非 oauth参数均不参与签名非 oauth参数填入 http content
域Oauth参数放入 Authorization Header域否则可能会出现错误
对于使用 GET请求 http[baseURL]ywsopenusergetjson需要将 oauth参
数和非 oauth参数一起放入 url参数中签名时需注意参数顺序发送请求时参
数可以无序
POST
httpnoteyoudaocomywsopennotecreatejson
Header 中 Authorization的值为
OAuth[ 空 格 ]oauth_token=29cc36314495ee1cf55ebf26ca9711bc
oauth_consumer_key=407d014e17ad5cd02f3e0a55fcb198af
oauth_signature_method=HMAC-SHA1 oauth_timestamp=1323327110
oauth_nonce=280224628487931 oauth_version=10
oauth_signature=rXpd0apk82wMAZLun2FDSUt1wbQE3D
最终 Header类似于
Authorization=OAuth20oauth_token3D2229cc36314495ee1cf55ebf26ca
9711bc222C20oauth_consumer_key3D22407d014e17ad5cd02f3e0a55fcb198
af222C20oauth_signature_method3D22HMAC-SHA1222C20oauth_timest
amp3D221323327041222C20oauth_nonce3D22280155519121203222C20
oauth_version3D2210222C20oauth_signature3D22E252F8dFmTFGTmdC
FE2rnJ8f252Bkzw9c253D22
签名的具体方法详见附录 D访问 Oauth的类库包详见附录 C
用户操作 API
查看用户信息
URLhttp[baseURL]ywsopenusergetjson
请求方式GET
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数无
返回结果操作成功时 http 状态为 200并用户信息失败时 http 状态为
500并返回错误码和错误信息详见附录 B
结果示例
ldquouserrdquo ldquotest163comrdquo 用户 ID
ldquototal_sizerdquo ldquo10293736383rdquo 用户总的空间大小单位字节
ldquoused_sizerdquo ldquo1024rdquo 用户已经使用了的空间大小单位字节
ldquoregister_timerdquo ldquo1323310917650rdquo 用户注册时间单位毫秒
ldquolast_login_timerdquo ldquo1323310949120rdquo 用户最后登录时间单位毫秒
ldquolast_modify_timerdquo ldquo1323310978120rdquo 用户最后修改时间单位毫秒
ldquodefault_notebookrdquo ldquoAB384D734rdquo 该应用的默认笔记本
注对于每个第三方应用都分别在用户的笔记空间中对应一个默认笔记本
笔记本名在申请应用时指定在使用 OpenAPI创建笔记时如果第三方应用
不指定笔记本则自动创建在该默认笔记本中
笔记本操作 API
查看用户全部笔记本
URLhttp[baseURL]ywsopennotebookalljson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数无
返回结果操作成功时 http状态为 200并返回笔记本列表失败时 http状
态为 500并返回错误码和错误信息详见附录 B
结果示例
[
ldquopathrdquo ldquo4AF64012E9864Crdquo 笔记本的路径
ldquonamerdquo ldquo笔记本 1rdquo 笔记本的名称
ldquonotes_numrdquo ldquo3rdquo 该笔记本中笔记的数目
ldquocreate_timerdquo ldquo1323310917rdquo 笔记本的创建时间单位秒
ldquomodify_timerdquo ldquo1323310949rdquo 笔记本的最后修改时间单位秒
ldquopathrdquo ldquo5AB0C6B33BD1162rdquo
ldquonamerdquo ldquo笔记本 2rdquo
ldquonotes_numrdquo ldquo10rdquo
ldquocreate_timerdquo ldquo1323311244rdquo
ldquomodify_timerdquo ldquo1323310349rdquo
]
列出笔记本下的笔记
URLhttp[baseURL]ywsopennotebooklistjson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
notebook 笔记本路径 是 String
返回结果操作成功时 http状态为 200并返回该笔记本下的笔记列表(只
有笔记路径笔记内容需要通过笔记接口获取)失败时 http状态 500并返
回错误码和错误信息详见附录 B
结果示例
[
ldquo4AF64012E9864C123TDE3DCrdquo 笔记路径
ldquo4AF64012E9864CDC12FTDE3rdquo
ldquo4AF64012E9864CFE23TDE3Crdquo
]
创建笔记本
URL http[baseURL]ywsopennotebookcreatejson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
name 笔记本名称 是 String
返回结果操作成功时 http状态 200并返回新创建笔记本的路径失败时
http状态 500并返回错误码和错误信息详见附录 B
结果示例
ldquopathrdquo ldquo4AF64012E9864Crdquo
删除笔记本
URL http[baseURL]ywsopennotebookdeletejson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
notebook 笔记本路径 是 String
返回结果操作成功时 http状态 200无返回数据失败时 http状态 500并
返回错误码和错误信息详见附录 B
笔记操作 API
创建笔记
URL http[baseURL]ywsopennotecreatejson
请求方式POST
Content-Typemultipartform-data
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
source 笔记来源 URL 否 String
author 笔记作者 否 String
title 笔记标题 否 String
content 笔记正文(笔记格式见附录 A) 是 String
notebook 该新建笔记所属的笔记本路径 否 String
返回结果操作成功时 http状态为 200并返回新建笔记的路径失败时 http
状态为 500并返回错误码和错误信息详见附录 B
结果示例
ldquopathrdquo ldquo4AF64012E9864CFE89D12134Erdquo
注如果第三方应用没有指定 notebook则在该第三方应用对应的默认笔记
本中创建该笔记
查看笔记
URL http[baseURL]ywsopennotegetjson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
path 笔记路径 是 String
返回结果操作成功时 http状态为 200并返回该笔记的相关信息失败时
http状态为 500并返回错误码和错误信息详见附录 B
结果示例
ldquotitlerdquo ldquo工作记录rdquo 笔记标题
ldquoauthorrdquo ldquoTomrdquo 笔记作者
ldquosourcerdquo ldquohttpnoteyoudaocomrdquo 笔记来源 URL
ldquosizerdquo ldquo1024rdquo 笔记大小包括笔记正文及附件
ldquocreate_timerdquo ldquo1323310917rdquo 笔记的创建时间单位秒
ldquomodify_timerdquo ldquo1323310949rdquo 笔记的最后修改时间单位秒
ldquocontentrdquo ldquoltpgtThis is a test noteltpgt 笔记正文
修改笔记
URL http[baseURL]ywsopennoteupdatejson
请求方式POST
Content-Typemultipartform-data
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
path 修改笔记的路径 是 String
source 修改后的笔记来源 URL 否 String
author 修改后的笔记作者 否 String
title 修改后的笔记标题 否 String
content 修改后的笔记正文(笔记格式见
附录 A)
是 String
返回结果操作成功时 http 状态为 200无返回结果失败时 http 状态为
500并返回错误码和错误信息详见附录 B
移动笔记
URL http[baseURL]ywsopennotemovejson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
path 想要移动的笔记原路径 是 String
notebook 目标笔记本的路径 是 String
返回结果操作成功时 http状态为 200返回移动后的笔记路径失败时 http
状态为 500并返回错误码和错误信息详见附录 B
结果示例
ldquopathrdquo ldquo5AB0C6B33BD1162FE89D12134Erdquo
删除笔记
URL http[baseURL]ywsopennotedeletejson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
path 想要删除的笔记原路径 是 String
返回结果操作成功时 http 状态为 200无返回结果失败时 http 状态为
500并返回错误码和错误信息详见附录 B
附件操作 API
上传附件或图片
URLhttp[baseURL]ywsopenresourceuploadjson
请求方式POST
Content-Typemultipartform-data
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
file 上传的附件文件(包括附件的文
件名类型大小数据等)
是 Multipart File附件大
小限制 25M
返回结果操作成功时 http状态为 200对于图片返回该图片的链接 URL
对于普通附件服务器会为该附件生成一个图标文件因此返回结果包括该
附件对应的链接 URL以及图标的 URL失败时 http状态为 500并返回错误码
和错误信息详见附录 B
示例
图片附件
url httpbaseURLywsopenresource28d83f547f3055
普通附件
url httpbaseURLywsopenresource28d83f547f3055 附件 URL
src httpbaseURLywsopenresource297f2bd6fa2795 图标 URL
需要注意的是在附件上传完成后使用者应该紧接着更新对应的笔记否
则不被任何笔记引用的附件将被定期的空间回收所删除
下载附件图片图标
URLhttp[baseURL]ywsopenresourcedownload
请求方式GET
是否需要用户认证是 (关于登录授权参见请求用户授权)
返回结果操作成功时response返回附件及图片的二进制流失败时 http
状态为 500并返回错误码和错误信息详见附录 B
备注
1 当打开笔记时对于笔记中的附件及图片链接只需要添加用户的 OAuth
认证信息即可以获取对应的附件及图片同理在上传附件后返回的附
件及图片链接也可以通过这种方式进行访问
2 附件及图片的下载支持断点续传
附录 A有道云笔记内容格式
笔记内容的格式采用类 HTML的标记语言绝大部分格式相关 tag均采用标
准的 HTML Tag唯一需要不同的是附件及图片 Tag在格式上图片 Tag与标准的
img tag相同一个图片资源的标记如下
ltimg src=httpnoteyoudaocomywsopenresource227f2bd6fa2795441cgt
但是由于对应的接口需要用户认证因此在获取图片资源时需要加入 OAuth
的用户认证信息
附件通常以图标在笔记中进行显示因此我们扩展了图片 Tag ltimggt除了
img 本身的 src 属性额外加入了一个属性 path其中 src 对应着该附件的图标
URL而 path则为该附件的 URL如下所示
ltimg path=httpnoteyoudaocomywsopenresource219fe604c7c90642fd8f
src=httpnoteyoudaocomywsopenresource227f2bd6fa2795441cgt
同理也需要加入 OAuth的用户认证信息才可以正常访问附件资源及其图标
附录 B错误码及错误信息说明
同理当 Open API的请求在执行时出现任何异常或错误时系统将返回 Http
500应用程序可以根据此判断请求是否成功执行当应用程序在进行 OAuth认
证或者未经认证便调用 Open API时系统会返回 OAuth错误信息OAuth的
错误码与错误信息将以 json的格式进行返回各个错误码及错误信息说明如下
错误码 错误描述及可能原因
1001 token_rejectedconsumer没有找到consumerKey错误 consumer
没有创建或者 request token或者 access token 不存在于 server中
或者没有获得授权的 token或者 token过期
1002 parameter_rejected这个会返回具体原因 key是
oauth_parameters_rejected value是一个 parameter列表
1003 version_rejectedOAuth版本号不是 10
1004 timestamp_refusedtimestamp 非 5分钟内
1005 nonce_used5分钟内该 nonce被使用
1006 parameter_absent有些参数没有发送给 server
1007 signature_invalidoauth签名异常可能原因没有签名签名方法和
签名不一致等
1008 signature_method_rejectedoauth server没有提供该签名方法
1009 access_state_error获取 token时状态混乱详细的信息会告知当前的
状态 [AUTHORIZED | REQUEST | ACCESS | INVALID]
1010 consumer_rejected该 consumer在 server中不存在或者被禁掉
或者 consumerKey改变但是还没有反应到 server的数据库中
1011 accessor_rejected由 token得到的 accessor构造异常或者 accessor
中缺失某些属性或者转换失败
1012 callback_errorrequest token传来的 callback和以后的 callback不一致
1013 callback_domain_error当限定 callback后发来的 callback与原设置
的 callback的域不相同
1014 verifier_errorVerifier不一致错误
1015 permission_denied无授权的 token或者授权后没有获取过 access
token
同理当 Open API的请求在后台执行出现异常或错误时系统也将同时错
误码与错误信息以 json 的格式一同返回应用程序可以根据错误码得到相应的
原因常见的错误码说明如下
错误码 错误描述及可能原因
206 UNKNOWN_URI错误的 URI请求
207 AUTHENTICATION_FAILURE用户认证错误
209 RESOURCE_NOT_EXIST请求的资源(笔记本笔记附件等)不存在
210 USER_SPACE_FULL用户空间已满
214 INVALID_PARAMETER错误的传入参数必须的参数为空等
220 USER_NOT_EXISTS用户不存在
221 USER_ALREADY_EXISTS用户已经存在不能重复注册
225 PARENT_NOT_EXIST笔记本尚不存在不能在该笔记本下创建笔记
231 RESOURCE_ALREADY_EXIST该笔记或者附件已经存在不能重复创建
304 NOTE_ALREADY_DELETED笔记已经被删除
307 INVALID_APPLICATION无效的第三方应用未经过用户授权或者授权
失败便通过 OpenAPI访问用户数据这个一般是使用测试环境得到了
access_token利用该 access_token访问了线上环境这两套环境是独
立的Access_token不能共用
但是如果第三方应用未经过用户授权
示例当查看笔记路径错误时
error 209
message Required note does not exist path=5AB0C6B33BD12FE89D12134E
附录 C 访问 OAuth Server的类库与包
ActionScriptFlash
oauth-as3 httpcodegooglecompoauth-as3
A flex oauth client
httpwwwarcgiscomhomeitemhtmlid=ff6ffa302ad04a7194999f2ad08250d7
CC++
QTweetLib httpgithubcomminimoogQTweetLib
libOAuth httpliboauthsourceforgenet
clojure
clj-oauth httpgithubcommattreplclj-oauth
net
oauth-dot-net httpcodegooglecompoauth-dot-net
DotNetOpenAuth httpwwwdotnetopenauthnet
Erlang
erlang-oauth httpgithubcomtimerlang-oauth
java
Scrible httpgithubcomfernandezpablo85scribe-java
oauth-signpost httpcodegooglecompoauth-signpost
javascript
oauth in js httpoauthgooglecodecomsvncodejavascript
Objective-CCocoa amp iPhone programming
OAuthCore httpbitbucketorgatebitsoauthcore
MPOAuthConnection httpcodegooglecompmpoauthconnection
Objective-C OAuth httpoauthgooglecodecomsvncodeobj-c
Perl
NetOAuth httpoauthgooglecodecomsvncodeperl
PHP
tmhOAuth httpgithubcomthemattharristmhOAuth
oauth-php httpcodegooglecompoauth-php
Python
python-oauth2 httpgithubcombrosnerpython-oauth2
Qt
qOauth httpgithubcomayoyqoauth
Ruby
Oauth ruby gem httpoauthrubyforgeorg
Scala
DataBinder Dispatch httpdispatchdatabindernetAbout
附录 D Oauth签名加密 oauth_signature
1 加密内容是
a 请求方法名例如 GET POST等 加密时方法名大写并进行特殊替换
(详见 3)
b url (query param之前的部分不包括 )Http或者 https需要全部小
写 http如果带有 80端口或者 https带有 443端口需要将其省略
其他端口则不能省略例如
Httplocal9999requestToken
httplocal9999requestToken
Httplocal80requestToken
httplocalrequestToken
Httpslocal443requestToken
httpslocal requestToken
c 参数(query param中的或者 header中的 key-value对) 首先将这些参数
进行特殊替换后按字典序排序升序排列如果两个 key相同则以
value特殊替换后字典序为准key与 value之间使用rdquo=rdquo连接如果
value==null则使用rdquordquo替代两个参数对之间使用rdquoamprdquo连接连接后形成
的最终字符串的开头和结尾没有rdquoamprdquo
d 字典序字符串比较大小伪代码
Int compare(string a string b)
Int min_len = min(len(a) len(b))
For I to min_len
If (a[i] = b[i])
Return a[i] ndash b[i]
Return len(a) ndash len(b)
将以上 abc三部分进行特殊替换后使用amp连接最终形成的字符串的
开头和结尾都没有rdquoamprdquo这就是加密内容
2 加密的 key是 consumerSecret + amp + TokenSecret 如果 TokenSecret还没有
得到则使用rdquordquo consumerSecret和 TokenSecret需先做特殊替换然后
再进行签名
3 特殊替换是将 String进行 URL编码后将rdquo+rdquo替换为rdquo20rdquo将rdquordquo替换
为rdquo2Ardquo将rdquo7Erdquo替换为rdquo~rdquo
4 签名方法可以使用 HMAC-SHA1PLAINTEXT RSA_SHA1三种其中
PLAINTEXT为 2中的 key 该方法不提倡使用
得到签名内容后使用 Base64进行编码编码后的字符串即为 oauth_signature
请求授权
URL [baseURL]oauthauthorize
请求方式GET
请求参数该处的参数必须以 query string的形式发送
参数名 参数说明
oauth_token 请求 request_token时返回的 oauth_token
正确时返回oauth_token(授权后的 request_token) 和 oauth_verifier
错误时返回error message
发送示例
GET http
sandboxnoteyoudaocomoauthauthorizeoauth_token=5420db084cc41d768d885
a53f7b2c1a6
备注如果 oauth_callback为 oob则不会回调用户会在 Oauth Server页面上
看到 pin 码用户需要手工将 pin 码粘帖到 application 中才能申请到
AccessToken应用请求 authorize时如果请求携带了网易或者有道的 cookie
则将直接询问用户是否授权否则会重新定向到网易的通行证页面
请求 access_token
URL[baseURL]oauthaccess_token
请求方式GET
请求参数
参数名 参数说明
oauth_consumer_key 回调 url
oauth_token request_token时返回的 oauth_token
oauth_verifier Authorize请求时发送回来的 oauth_verifier或者是
OauthServer页面显示的 Pin码
oauth_signature_method 签名方法支持 HMAC-SHA1
oauth_timestamp 时间戳当前时间单位毫秒
oauth_nonce 随机串为了防止重放攻击5分钟内同一用户同一应用同
一时间发来的请求中 oauth_nonce应不同
oauth_version 10
oauth_signature 使用 consumerSecret + rsquoamprsquo + oauth_token_secret
字串作为key 而签名的内容是除oauth_signature以外
的请求 url内容计算签名完毕后使用 base64编码
正确时返回oauth_token_secret (授权流程中的 access_secret)oauth_token
(授权流程中的 access_token)
错误时返回error message
发送示例 http header的例子
curl ndashH ldquoAuthorization OAuth
oauth_verifier=rdquo8714fb943a28d7faffec3265e96d85cdrdquo
oauth_token=rdquob348d10a0f45a4cf6936381d6c9fb00frdquo
oauth_consumer_key=rdquo7a23b1eaf487060deaa5660b323c341brdquo
oauth_signature_method=rdquoHMAC-SHA1rdquo oauth_timestamp=rdquo1321857128rdquo
oauth_nonce=rdquo449560105422526rdquo oauth_version=rdquo10rdquo
oauth_signature=rdquoS8yxdpLIA7MiFVDE4OzSDoo2F62FI3Drdquordquo
ldquohttpsandboxnoteyoudaocomoauthaccess_tokenrdquo
访问 OpenAPI
由 223 返回的 oauth_token 将用于 OpenAPI 的请求 consumerSecret + rsquoamprsquo +
oauth_token_secret 将 用 作 签 名 例 如 请 求 创 建 笔 记 本
http[baseURL]ywsopennotebookcreatejson则应在请求创建笔记中添加各
种参数(创建笔记本的其他参数按文档要求不变)如果没有则会返回 error
和 message(此处的 error和 message会放入到 json串中error是错误码 message
是具体错误信息)不会执行任何 OpenAPI操作
例如执行创建笔记本操作参数 name需和 oauth 的其他值一起进行签名
但是不应该将 name 放入 header 中并且发送 post 请求的 Content-Type 为
applicationx-www-form-urlencoded其他参数填入 http content 域Oauth 参数
放入 Authorization Header域否则可能会出现错误
对于上传笔记或者附件图片的 open API 中post 请求的 Content-Type 为
multipartform-data非 oauth参数均不参与签名非 oauth参数填入 http content
域Oauth参数放入 Authorization Header域否则可能会出现错误
对于使用 GET请求 http[baseURL]ywsopenusergetjson需要将 oauth参
数和非 oauth参数一起放入 url参数中签名时需注意参数顺序发送请求时参
数可以无序
POST
httpnoteyoudaocomywsopennotecreatejson
Header 中 Authorization的值为
OAuth[ 空 格 ]oauth_token=29cc36314495ee1cf55ebf26ca9711bc
oauth_consumer_key=407d014e17ad5cd02f3e0a55fcb198af
oauth_signature_method=HMAC-SHA1 oauth_timestamp=1323327110
oauth_nonce=280224628487931 oauth_version=10
oauth_signature=rXpd0apk82wMAZLun2FDSUt1wbQE3D
最终 Header类似于
Authorization=OAuth20oauth_token3D2229cc36314495ee1cf55ebf26ca
9711bc222C20oauth_consumer_key3D22407d014e17ad5cd02f3e0a55fcb198
af222C20oauth_signature_method3D22HMAC-SHA1222C20oauth_timest
amp3D221323327041222C20oauth_nonce3D22280155519121203222C20
oauth_version3D2210222C20oauth_signature3D22E252F8dFmTFGTmdC
FE2rnJ8f252Bkzw9c253D22
签名的具体方法详见附录 D访问 Oauth的类库包详见附录 C
用户操作 API
查看用户信息
URLhttp[baseURL]ywsopenusergetjson
请求方式GET
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数无
返回结果操作成功时 http 状态为 200并用户信息失败时 http 状态为
500并返回错误码和错误信息详见附录 B
结果示例
ldquouserrdquo ldquotest163comrdquo 用户 ID
ldquototal_sizerdquo ldquo10293736383rdquo 用户总的空间大小单位字节
ldquoused_sizerdquo ldquo1024rdquo 用户已经使用了的空间大小单位字节
ldquoregister_timerdquo ldquo1323310917650rdquo 用户注册时间单位毫秒
ldquolast_login_timerdquo ldquo1323310949120rdquo 用户最后登录时间单位毫秒
ldquolast_modify_timerdquo ldquo1323310978120rdquo 用户最后修改时间单位毫秒
ldquodefault_notebookrdquo ldquoAB384D734rdquo 该应用的默认笔记本
注对于每个第三方应用都分别在用户的笔记空间中对应一个默认笔记本
笔记本名在申请应用时指定在使用 OpenAPI创建笔记时如果第三方应用
不指定笔记本则自动创建在该默认笔记本中
笔记本操作 API
查看用户全部笔记本
URLhttp[baseURL]ywsopennotebookalljson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数无
返回结果操作成功时 http状态为 200并返回笔记本列表失败时 http状
态为 500并返回错误码和错误信息详见附录 B
结果示例
[
ldquopathrdquo ldquo4AF64012E9864Crdquo 笔记本的路径
ldquonamerdquo ldquo笔记本 1rdquo 笔记本的名称
ldquonotes_numrdquo ldquo3rdquo 该笔记本中笔记的数目
ldquocreate_timerdquo ldquo1323310917rdquo 笔记本的创建时间单位秒
ldquomodify_timerdquo ldquo1323310949rdquo 笔记本的最后修改时间单位秒
ldquopathrdquo ldquo5AB0C6B33BD1162rdquo
ldquonamerdquo ldquo笔记本 2rdquo
ldquonotes_numrdquo ldquo10rdquo
ldquocreate_timerdquo ldquo1323311244rdquo
ldquomodify_timerdquo ldquo1323310349rdquo
]
列出笔记本下的笔记
URLhttp[baseURL]ywsopennotebooklistjson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
notebook 笔记本路径 是 String
返回结果操作成功时 http状态为 200并返回该笔记本下的笔记列表(只
有笔记路径笔记内容需要通过笔记接口获取)失败时 http状态 500并返
回错误码和错误信息详见附录 B
结果示例
[
ldquo4AF64012E9864C123TDE3DCrdquo 笔记路径
ldquo4AF64012E9864CDC12FTDE3rdquo
ldquo4AF64012E9864CFE23TDE3Crdquo
]
创建笔记本
URL http[baseURL]ywsopennotebookcreatejson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
name 笔记本名称 是 String
返回结果操作成功时 http状态 200并返回新创建笔记本的路径失败时
http状态 500并返回错误码和错误信息详见附录 B
结果示例
ldquopathrdquo ldquo4AF64012E9864Crdquo
删除笔记本
URL http[baseURL]ywsopennotebookdeletejson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
notebook 笔记本路径 是 String
返回结果操作成功时 http状态 200无返回数据失败时 http状态 500并
返回错误码和错误信息详见附录 B
笔记操作 API
创建笔记
URL http[baseURL]ywsopennotecreatejson
请求方式POST
Content-Typemultipartform-data
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
source 笔记来源 URL 否 String
author 笔记作者 否 String
title 笔记标题 否 String
content 笔记正文(笔记格式见附录 A) 是 String
notebook 该新建笔记所属的笔记本路径 否 String
返回结果操作成功时 http状态为 200并返回新建笔记的路径失败时 http
状态为 500并返回错误码和错误信息详见附录 B
结果示例
ldquopathrdquo ldquo4AF64012E9864CFE89D12134Erdquo
注如果第三方应用没有指定 notebook则在该第三方应用对应的默认笔记
本中创建该笔记
查看笔记
URL http[baseURL]ywsopennotegetjson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
path 笔记路径 是 String
返回结果操作成功时 http状态为 200并返回该笔记的相关信息失败时
http状态为 500并返回错误码和错误信息详见附录 B
结果示例
ldquotitlerdquo ldquo工作记录rdquo 笔记标题
ldquoauthorrdquo ldquoTomrdquo 笔记作者
ldquosourcerdquo ldquohttpnoteyoudaocomrdquo 笔记来源 URL
ldquosizerdquo ldquo1024rdquo 笔记大小包括笔记正文及附件
ldquocreate_timerdquo ldquo1323310917rdquo 笔记的创建时间单位秒
ldquomodify_timerdquo ldquo1323310949rdquo 笔记的最后修改时间单位秒
ldquocontentrdquo ldquoltpgtThis is a test noteltpgt 笔记正文
修改笔记
URL http[baseURL]ywsopennoteupdatejson
请求方式POST
Content-Typemultipartform-data
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
path 修改笔记的路径 是 String
source 修改后的笔记来源 URL 否 String
author 修改后的笔记作者 否 String
title 修改后的笔记标题 否 String
content 修改后的笔记正文(笔记格式见
附录 A)
是 String
返回结果操作成功时 http 状态为 200无返回结果失败时 http 状态为
500并返回错误码和错误信息详见附录 B
移动笔记
URL http[baseURL]ywsopennotemovejson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
path 想要移动的笔记原路径 是 String
notebook 目标笔记本的路径 是 String
返回结果操作成功时 http状态为 200返回移动后的笔记路径失败时 http
状态为 500并返回错误码和错误信息详见附录 B
结果示例
ldquopathrdquo ldquo5AB0C6B33BD1162FE89D12134Erdquo
删除笔记
URL http[baseURL]ywsopennotedeletejson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
path 想要删除的笔记原路径 是 String
返回结果操作成功时 http 状态为 200无返回结果失败时 http 状态为
500并返回错误码和错误信息详见附录 B
附件操作 API
上传附件或图片
URLhttp[baseURL]ywsopenresourceuploadjson
请求方式POST
Content-Typemultipartform-data
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
file 上传的附件文件(包括附件的文
件名类型大小数据等)
是 Multipart File附件大
小限制 25M
返回结果操作成功时 http状态为 200对于图片返回该图片的链接 URL
对于普通附件服务器会为该附件生成一个图标文件因此返回结果包括该
附件对应的链接 URL以及图标的 URL失败时 http状态为 500并返回错误码
和错误信息详见附录 B
示例
图片附件
url httpbaseURLywsopenresource28d83f547f3055
普通附件
url httpbaseURLywsopenresource28d83f547f3055 附件 URL
src httpbaseURLywsopenresource297f2bd6fa2795 图标 URL
需要注意的是在附件上传完成后使用者应该紧接着更新对应的笔记否
则不被任何笔记引用的附件将被定期的空间回收所删除
下载附件图片图标
URLhttp[baseURL]ywsopenresourcedownload
请求方式GET
是否需要用户认证是 (关于登录授权参见请求用户授权)
返回结果操作成功时response返回附件及图片的二进制流失败时 http
状态为 500并返回错误码和错误信息详见附录 B
备注
1 当打开笔记时对于笔记中的附件及图片链接只需要添加用户的 OAuth
认证信息即可以获取对应的附件及图片同理在上传附件后返回的附
件及图片链接也可以通过这种方式进行访问
2 附件及图片的下载支持断点续传
附录 A有道云笔记内容格式
笔记内容的格式采用类 HTML的标记语言绝大部分格式相关 tag均采用标
准的 HTML Tag唯一需要不同的是附件及图片 Tag在格式上图片 Tag与标准的
img tag相同一个图片资源的标记如下
ltimg src=httpnoteyoudaocomywsopenresource227f2bd6fa2795441cgt
但是由于对应的接口需要用户认证因此在获取图片资源时需要加入 OAuth
的用户认证信息
附件通常以图标在笔记中进行显示因此我们扩展了图片 Tag ltimggt除了
img 本身的 src 属性额外加入了一个属性 path其中 src 对应着该附件的图标
URL而 path则为该附件的 URL如下所示
ltimg path=httpnoteyoudaocomywsopenresource219fe604c7c90642fd8f
src=httpnoteyoudaocomywsopenresource227f2bd6fa2795441cgt
同理也需要加入 OAuth的用户认证信息才可以正常访问附件资源及其图标
附录 B错误码及错误信息说明
同理当 Open API的请求在执行时出现任何异常或错误时系统将返回 Http
500应用程序可以根据此判断请求是否成功执行当应用程序在进行 OAuth认
证或者未经认证便调用 Open API时系统会返回 OAuth错误信息OAuth的
错误码与错误信息将以 json的格式进行返回各个错误码及错误信息说明如下
错误码 错误描述及可能原因
1001 token_rejectedconsumer没有找到consumerKey错误 consumer
没有创建或者 request token或者 access token 不存在于 server中
或者没有获得授权的 token或者 token过期
1002 parameter_rejected这个会返回具体原因 key是
oauth_parameters_rejected value是一个 parameter列表
1003 version_rejectedOAuth版本号不是 10
1004 timestamp_refusedtimestamp 非 5分钟内
1005 nonce_used5分钟内该 nonce被使用
1006 parameter_absent有些参数没有发送给 server
1007 signature_invalidoauth签名异常可能原因没有签名签名方法和
签名不一致等
1008 signature_method_rejectedoauth server没有提供该签名方法
1009 access_state_error获取 token时状态混乱详细的信息会告知当前的
状态 [AUTHORIZED | REQUEST | ACCESS | INVALID]
1010 consumer_rejected该 consumer在 server中不存在或者被禁掉
或者 consumerKey改变但是还没有反应到 server的数据库中
1011 accessor_rejected由 token得到的 accessor构造异常或者 accessor
中缺失某些属性或者转换失败
1012 callback_errorrequest token传来的 callback和以后的 callback不一致
1013 callback_domain_error当限定 callback后发来的 callback与原设置
的 callback的域不相同
1014 verifier_errorVerifier不一致错误
1015 permission_denied无授权的 token或者授权后没有获取过 access
token
同理当 Open API的请求在后台执行出现异常或错误时系统也将同时错
误码与错误信息以 json 的格式一同返回应用程序可以根据错误码得到相应的
原因常见的错误码说明如下
错误码 错误描述及可能原因
206 UNKNOWN_URI错误的 URI请求
207 AUTHENTICATION_FAILURE用户认证错误
209 RESOURCE_NOT_EXIST请求的资源(笔记本笔记附件等)不存在
210 USER_SPACE_FULL用户空间已满
214 INVALID_PARAMETER错误的传入参数必须的参数为空等
220 USER_NOT_EXISTS用户不存在
221 USER_ALREADY_EXISTS用户已经存在不能重复注册
225 PARENT_NOT_EXIST笔记本尚不存在不能在该笔记本下创建笔记
231 RESOURCE_ALREADY_EXIST该笔记或者附件已经存在不能重复创建
304 NOTE_ALREADY_DELETED笔记已经被删除
307 INVALID_APPLICATION无效的第三方应用未经过用户授权或者授权
失败便通过 OpenAPI访问用户数据这个一般是使用测试环境得到了
access_token利用该 access_token访问了线上环境这两套环境是独
立的Access_token不能共用
但是如果第三方应用未经过用户授权
示例当查看笔记路径错误时
error 209
message Required note does not exist path=5AB0C6B33BD12FE89D12134E
附录 C 访问 OAuth Server的类库与包
ActionScriptFlash
oauth-as3 httpcodegooglecompoauth-as3
A flex oauth client
httpwwwarcgiscomhomeitemhtmlid=ff6ffa302ad04a7194999f2ad08250d7
CC++
QTweetLib httpgithubcomminimoogQTweetLib
libOAuth httpliboauthsourceforgenet
clojure
clj-oauth httpgithubcommattreplclj-oauth
net
oauth-dot-net httpcodegooglecompoauth-dot-net
DotNetOpenAuth httpwwwdotnetopenauthnet
Erlang
erlang-oauth httpgithubcomtimerlang-oauth
java
Scrible httpgithubcomfernandezpablo85scribe-java
oauth-signpost httpcodegooglecompoauth-signpost
javascript
oauth in js httpoauthgooglecodecomsvncodejavascript
Objective-CCocoa amp iPhone programming
OAuthCore httpbitbucketorgatebitsoauthcore
MPOAuthConnection httpcodegooglecompmpoauthconnection
Objective-C OAuth httpoauthgooglecodecomsvncodeobj-c
Perl
NetOAuth httpoauthgooglecodecomsvncodeperl
PHP
tmhOAuth httpgithubcomthemattharristmhOAuth
oauth-php httpcodegooglecompoauth-php
Python
python-oauth2 httpgithubcombrosnerpython-oauth2
Qt
qOauth httpgithubcomayoyqoauth
Ruby
Oauth ruby gem httpoauthrubyforgeorg
Scala
DataBinder Dispatch httpdispatchdatabindernetAbout
附录 D Oauth签名加密 oauth_signature
1 加密内容是
a 请求方法名例如 GET POST等 加密时方法名大写并进行特殊替换
(详见 3)
b url (query param之前的部分不包括 )Http或者 https需要全部小
写 http如果带有 80端口或者 https带有 443端口需要将其省略
其他端口则不能省略例如
Httplocal9999requestToken
httplocal9999requestToken
Httplocal80requestToken
httplocalrequestToken
Httpslocal443requestToken
httpslocal requestToken
c 参数(query param中的或者 header中的 key-value对) 首先将这些参数
进行特殊替换后按字典序排序升序排列如果两个 key相同则以
value特殊替换后字典序为准key与 value之间使用rdquo=rdquo连接如果
value==null则使用rdquordquo替代两个参数对之间使用rdquoamprdquo连接连接后形成
的最终字符串的开头和结尾没有rdquoamprdquo
d 字典序字符串比较大小伪代码
Int compare(string a string b)
Int min_len = min(len(a) len(b))
For I to min_len
If (a[i] = b[i])
Return a[i] ndash b[i]
Return len(a) ndash len(b)
将以上 abc三部分进行特殊替换后使用amp连接最终形成的字符串的
开头和结尾都没有rdquoamprdquo这就是加密内容
2 加密的 key是 consumerSecret + amp + TokenSecret 如果 TokenSecret还没有
得到则使用rdquordquo consumerSecret和 TokenSecret需先做特殊替换然后
再进行签名
3 特殊替换是将 String进行 URL编码后将rdquo+rdquo替换为rdquo20rdquo将rdquordquo替换
为rdquo2Ardquo将rdquo7Erdquo替换为rdquo~rdquo
4 签名方法可以使用 HMAC-SHA1PLAINTEXT RSA_SHA1三种其中
PLAINTEXT为 2中的 key 该方法不提倡使用
得到签名内容后使用 Base64进行编码编码后的字符串即为 oauth_signature
字串作为key 而签名的内容是除oauth_signature以外
的请求 url内容计算签名完毕后使用 base64编码
正确时返回oauth_token_secret (授权流程中的 access_secret)oauth_token
(授权流程中的 access_token)
错误时返回error message
发送示例 http header的例子
curl ndashH ldquoAuthorization OAuth
oauth_verifier=rdquo8714fb943a28d7faffec3265e96d85cdrdquo
oauth_token=rdquob348d10a0f45a4cf6936381d6c9fb00frdquo
oauth_consumer_key=rdquo7a23b1eaf487060deaa5660b323c341brdquo
oauth_signature_method=rdquoHMAC-SHA1rdquo oauth_timestamp=rdquo1321857128rdquo
oauth_nonce=rdquo449560105422526rdquo oauth_version=rdquo10rdquo
oauth_signature=rdquoS8yxdpLIA7MiFVDE4OzSDoo2F62FI3Drdquordquo
ldquohttpsandboxnoteyoudaocomoauthaccess_tokenrdquo
访问 OpenAPI
由 223 返回的 oauth_token 将用于 OpenAPI 的请求 consumerSecret + rsquoamprsquo +
oauth_token_secret 将 用 作 签 名 例 如 请 求 创 建 笔 记 本
http[baseURL]ywsopennotebookcreatejson则应在请求创建笔记中添加各
种参数(创建笔记本的其他参数按文档要求不变)如果没有则会返回 error
和 message(此处的 error和 message会放入到 json串中error是错误码 message
是具体错误信息)不会执行任何 OpenAPI操作
例如执行创建笔记本操作参数 name需和 oauth 的其他值一起进行签名
但是不应该将 name 放入 header 中并且发送 post 请求的 Content-Type 为
applicationx-www-form-urlencoded其他参数填入 http content 域Oauth 参数
放入 Authorization Header域否则可能会出现错误
对于上传笔记或者附件图片的 open API 中post 请求的 Content-Type 为
multipartform-data非 oauth参数均不参与签名非 oauth参数填入 http content
域Oauth参数放入 Authorization Header域否则可能会出现错误
对于使用 GET请求 http[baseURL]ywsopenusergetjson需要将 oauth参
数和非 oauth参数一起放入 url参数中签名时需注意参数顺序发送请求时参
数可以无序
POST
httpnoteyoudaocomywsopennotecreatejson
Header 中 Authorization的值为
OAuth[ 空 格 ]oauth_token=29cc36314495ee1cf55ebf26ca9711bc
oauth_consumer_key=407d014e17ad5cd02f3e0a55fcb198af
oauth_signature_method=HMAC-SHA1 oauth_timestamp=1323327110
oauth_nonce=280224628487931 oauth_version=10
oauth_signature=rXpd0apk82wMAZLun2FDSUt1wbQE3D
最终 Header类似于
Authorization=OAuth20oauth_token3D2229cc36314495ee1cf55ebf26ca
9711bc222C20oauth_consumer_key3D22407d014e17ad5cd02f3e0a55fcb198
af222C20oauth_signature_method3D22HMAC-SHA1222C20oauth_timest
amp3D221323327041222C20oauth_nonce3D22280155519121203222C20
oauth_version3D2210222C20oauth_signature3D22E252F8dFmTFGTmdC
FE2rnJ8f252Bkzw9c253D22
签名的具体方法详见附录 D访问 Oauth的类库包详见附录 C
用户操作 API
查看用户信息
URLhttp[baseURL]ywsopenusergetjson
请求方式GET
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数无
返回结果操作成功时 http 状态为 200并用户信息失败时 http 状态为
500并返回错误码和错误信息详见附录 B
结果示例
ldquouserrdquo ldquotest163comrdquo 用户 ID
ldquototal_sizerdquo ldquo10293736383rdquo 用户总的空间大小单位字节
ldquoused_sizerdquo ldquo1024rdquo 用户已经使用了的空间大小单位字节
ldquoregister_timerdquo ldquo1323310917650rdquo 用户注册时间单位毫秒
ldquolast_login_timerdquo ldquo1323310949120rdquo 用户最后登录时间单位毫秒
ldquolast_modify_timerdquo ldquo1323310978120rdquo 用户最后修改时间单位毫秒
ldquodefault_notebookrdquo ldquoAB384D734rdquo 该应用的默认笔记本
注对于每个第三方应用都分别在用户的笔记空间中对应一个默认笔记本
笔记本名在申请应用时指定在使用 OpenAPI创建笔记时如果第三方应用
不指定笔记本则自动创建在该默认笔记本中
笔记本操作 API
查看用户全部笔记本
URLhttp[baseURL]ywsopennotebookalljson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数无
返回结果操作成功时 http状态为 200并返回笔记本列表失败时 http状
态为 500并返回错误码和错误信息详见附录 B
结果示例
[
ldquopathrdquo ldquo4AF64012E9864Crdquo 笔记本的路径
ldquonamerdquo ldquo笔记本 1rdquo 笔记本的名称
ldquonotes_numrdquo ldquo3rdquo 该笔记本中笔记的数目
ldquocreate_timerdquo ldquo1323310917rdquo 笔记本的创建时间单位秒
ldquomodify_timerdquo ldquo1323310949rdquo 笔记本的最后修改时间单位秒
ldquopathrdquo ldquo5AB0C6B33BD1162rdquo
ldquonamerdquo ldquo笔记本 2rdquo
ldquonotes_numrdquo ldquo10rdquo
ldquocreate_timerdquo ldquo1323311244rdquo
ldquomodify_timerdquo ldquo1323310349rdquo
]
列出笔记本下的笔记
URLhttp[baseURL]ywsopennotebooklistjson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
notebook 笔记本路径 是 String
返回结果操作成功时 http状态为 200并返回该笔记本下的笔记列表(只
有笔记路径笔记内容需要通过笔记接口获取)失败时 http状态 500并返
回错误码和错误信息详见附录 B
结果示例
[
ldquo4AF64012E9864C123TDE3DCrdquo 笔记路径
ldquo4AF64012E9864CDC12FTDE3rdquo
ldquo4AF64012E9864CFE23TDE3Crdquo
]
创建笔记本
URL http[baseURL]ywsopennotebookcreatejson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
name 笔记本名称 是 String
返回结果操作成功时 http状态 200并返回新创建笔记本的路径失败时
http状态 500并返回错误码和错误信息详见附录 B
结果示例
ldquopathrdquo ldquo4AF64012E9864Crdquo
删除笔记本
URL http[baseURL]ywsopennotebookdeletejson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
notebook 笔记本路径 是 String
返回结果操作成功时 http状态 200无返回数据失败时 http状态 500并
返回错误码和错误信息详见附录 B
笔记操作 API
创建笔记
URL http[baseURL]ywsopennotecreatejson
请求方式POST
Content-Typemultipartform-data
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
source 笔记来源 URL 否 String
author 笔记作者 否 String
title 笔记标题 否 String
content 笔记正文(笔记格式见附录 A) 是 String
notebook 该新建笔记所属的笔记本路径 否 String
返回结果操作成功时 http状态为 200并返回新建笔记的路径失败时 http
状态为 500并返回错误码和错误信息详见附录 B
结果示例
ldquopathrdquo ldquo4AF64012E9864CFE89D12134Erdquo
注如果第三方应用没有指定 notebook则在该第三方应用对应的默认笔记
本中创建该笔记
查看笔记
URL http[baseURL]ywsopennotegetjson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
path 笔记路径 是 String
返回结果操作成功时 http状态为 200并返回该笔记的相关信息失败时
http状态为 500并返回错误码和错误信息详见附录 B
结果示例
ldquotitlerdquo ldquo工作记录rdquo 笔记标题
ldquoauthorrdquo ldquoTomrdquo 笔记作者
ldquosourcerdquo ldquohttpnoteyoudaocomrdquo 笔记来源 URL
ldquosizerdquo ldquo1024rdquo 笔记大小包括笔记正文及附件
ldquocreate_timerdquo ldquo1323310917rdquo 笔记的创建时间单位秒
ldquomodify_timerdquo ldquo1323310949rdquo 笔记的最后修改时间单位秒
ldquocontentrdquo ldquoltpgtThis is a test noteltpgt 笔记正文
修改笔记
URL http[baseURL]ywsopennoteupdatejson
请求方式POST
Content-Typemultipartform-data
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
path 修改笔记的路径 是 String
source 修改后的笔记来源 URL 否 String
author 修改后的笔记作者 否 String
title 修改后的笔记标题 否 String
content 修改后的笔记正文(笔记格式见
附录 A)
是 String
返回结果操作成功时 http 状态为 200无返回结果失败时 http 状态为
500并返回错误码和错误信息详见附录 B
移动笔记
URL http[baseURL]ywsopennotemovejson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
path 想要移动的笔记原路径 是 String
notebook 目标笔记本的路径 是 String
返回结果操作成功时 http状态为 200返回移动后的笔记路径失败时 http
状态为 500并返回错误码和错误信息详见附录 B
结果示例
ldquopathrdquo ldquo5AB0C6B33BD1162FE89D12134Erdquo
删除笔记
URL http[baseURL]ywsopennotedeletejson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
path 想要删除的笔记原路径 是 String
返回结果操作成功时 http 状态为 200无返回结果失败时 http 状态为
500并返回错误码和错误信息详见附录 B
附件操作 API
上传附件或图片
URLhttp[baseURL]ywsopenresourceuploadjson
请求方式POST
Content-Typemultipartform-data
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
file 上传的附件文件(包括附件的文
件名类型大小数据等)
是 Multipart File附件大
小限制 25M
返回结果操作成功时 http状态为 200对于图片返回该图片的链接 URL
对于普通附件服务器会为该附件生成一个图标文件因此返回结果包括该
附件对应的链接 URL以及图标的 URL失败时 http状态为 500并返回错误码
和错误信息详见附录 B
示例
图片附件
url httpbaseURLywsopenresource28d83f547f3055
普通附件
url httpbaseURLywsopenresource28d83f547f3055 附件 URL
src httpbaseURLywsopenresource297f2bd6fa2795 图标 URL
需要注意的是在附件上传完成后使用者应该紧接着更新对应的笔记否
则不被任何笔记引用的附件将被定期的空间回收所删除
下载附件图片图标
URLhttp[baseURL]ywsopenresourcedownload
请求方式GET
是否需要用户认证是 (关于登录授权参见请求用户授权)
返回结果操作成功时response返回附件及图片的二进制流失败时 http
状态为 500并返回错误码和错误信息详见附录 B
备注
1 当打开笔记时对于笔记中的附件及图片链接只需要添加用户的 OAuth
认证信息即可以获取对应的附件及图片同理在上传附件后返回的附
件及图片链接也可以通过这种方式进行访问
2 附件及图片的下载支持断点续传
附录 A有道云笔记内容格式
笔记内容的格式采用类 HTML的标记语言绝大部分格式相关 tag均采用标
准的 HTML Tag唯一需要不同的是附件及图片 Tag在格式上图片 Tag与标准的
img tag相同一个图片资源的标记如下
ltimg src=httpnoteyoudaocomywsopenresource227f2bd6fa2795441cgt
但是由于对应的接口需要用户认证因此在获取图片资源时需要加入 OAuth
的用户认证信息
附件通常以图标在笔记中进行显示因此我们扩展了图片 Tag ltimggt除了
img 本身的 src 属性额外加入了一个属性 path其中 src 对应着该附件的图标
URL而 path则为该附件的 URL如下所示
ltimg path=httpnoteyoudaocomywsopenresource219fe604c7c90642fd8f
src=httpnoteyoudaocomywsopenresource227f2bd6fa2795441cgt
同理也需要加入 OAuth的用户认证信息才可以正常访问附件资源及其图标
附录 B错误码及错误信息说明
同理当 Open API的请求在执行时出现任何异常或错误时系统将返回 Http
500应用程序可以根据此判断请求是否成功执行当应用程序在进行 OAuth认
证或者未经认证便调用 Open API时系统会返回 OAuth错误信息OAuth的
错误码与错误信息将以 json的格式进行返回各个错误码及错误信息说明如下
错误码 错误描述及可能原因
1001 token_rejectedconsumer没有找到consumerKey错误 consumer
没有创建或者 request token或者 access token 不存在于 server中
或者没有获得授权的 token或者 token过期
1002 parameter_rejected这个会返回具体原因 key是
oauth_parameters_rejected value是一个 parameter列表
1003 version_rejectedOAuth版本号不是 10
1004 timestamp_refusedtimestamp 非 5分钟内
1005 nonce_used5分钟内该 nonce被使用
1006 parameter_absent有些参数没有发送给 server
1007 signature_invalidoauth签名异常可能原因没有签名签名方法和
签名不一致等
1008 signature_method_rejectedoauth server没有提供该签名方法
1009 access_state_error获取 token时状态混乱详细的信息会告知当前的
状态 [AUTHORIZED | REQUEST | ACCESS | INVALID]
1010 consumer_rejected该 consumer在 server中不存在或者被禁掉
或者 consumerKey改变但是还没有反应到 server的数据库中
1011 accessor_rejected由 token得到的 accessor构造异常或者 accessor
中缺失某些属性或者转换失败
1012 callback_errorrequest token传来的 callback和以后的 callback不一致
1013 callback_domain_error当限定 callback后发来的 callback与原设置
的 callback的域不相同
1014 verifier_errorVerifier不一致错误
1015 permission_denied无授权的 token或者授权后没有获取过 access
token
同理当 Open API的请求在后台执行出现异常或错误时系统也将同时错
误码与错误信息以 json 的格式一同返回应用程序可以根据错误码得到相应的
原因常见的错误码说明如下
错误码 错误描述及可能原因
206 UNKNOWN_URI错误的 URI请求
207 AUTHENTICATION_FAILURE用户认证错误
209 RESOURCE_NOT_EXIST请求的资源(笔记本笔记附件等)不存在
210 USER_SPACE_FULL用户空间已满
214 INVALID_PARAMETER错误的传入参数必须的参数为空等
220 USER_NOT_EXISTS用户不存在
221 USER_ALREADY_EXISTS用户已经存在不能重复注册
225 PARENT_NOT_EXIST笔记本尚不存在不能在该笔记本下创建笔记
231 RESOURCE_ALREADY_EXIST该笔记或者附件已经存在不能重复创建
304 NOTE_ALREADY_DELETED笔记已经被删除
307 INVALID_APPLICATION无效的第三方应用未经过用户授权或者授权
失败便通过 OpenAPI访问用户数据这个一般是使用测试环境得到了
access_token利用该 access_token访问了线上环境这两套环境是独
立的Access_token不能共用
但是如果第三方应用未经过用户授权
示例当查看笔记路径错误时
error 209
message Required note does not exist path=5AB0C6B33BD12FE89D12134E
附录 C 访问 OAuth Server的类库与包
ActionScriptFlash
oauth-as3 httpcodegooglecompoauth-as3
A flex oauth client
httpwwwarcgiscomhomeitemhtmlid=ff6ffa302ad04a7194999f2ad08250d7
CC++
QTweetLib httpgithubcomminimoogQTweetLib
libOAuth httpliboauthsourceforgenet
clojure
clj-oauth httpgithubcommattreplclj-oauth
net
oauth-dot-net httpcodegooglecompoauth-dot-net
DotNetOpenAuth httpwwwdotnetopenauthnet
Erlang
erlang-oauth httpgithubcomtimerlang-oauth
java
Scrible httpgithubcomfernandezpablo85scribe-java
oauth-signpost httpcodegooglecompoauth-signpost
javascript
oauth in js httpoauthgooglecodecomsvncodejavascript
Objective-CCocoa amp iPhone programming
OAuthCore httpbitbucketorgatebitsoauthcore
MPOAuthConnection httpcodegooglecompmpoauthconnection
Objective-C OAuth httpoauthgooglecodecomsvncodeobj-c
Perl
NetOAuth httpoauthgooglecodecomsvncodeperl
PHP
tmhOAuth httpgithubcomthemattharristmhOAuth
oauth-php httpcodegooglecompoauth-php
Python
python-oauth2 httpgithubcombrosnerpython-oauth2
Qt
qOauth httpgithubcomayoyqoauth
Ruby
Oauth ruby gem httpoauthrubyforgeorg
Scala
DataBinder Dispatch httpdispatchdatabindernetAbout
附录 D Oauth签名加密 oauth_signature
1 加密内容是
a 请求方法名例如 GET POST等 加密时方法名大写并进行特殊替换
(详见 3)
b url (query param之前的部分不包括 )Http或者 https需要全部小
写 http如果带有 80端口或者 https带有 443端口需要将其省略
其他端口则不能省略例如
Httplocal9999requestToken
httplocal9999requestToken
Httplocal80requestToken
httplocalrequestToken
Httpslocal443requestToken
httpslocal requestToken
c 参数(query param中的或者 header中的 key-value对) 首先将这些参数
进行特殊替换后按字典序排序升序排列如果两个 key相同则以
value特殊替换后字典序为准key与 value之间使用rdquo=rdquo连接如果
value==null则使用rdquordquo替代两个参数对之间使用rdquoamprdquo连接连接后形成
的最终字符串的开头和结尾没有rdquoamprdquo
d 字典序字符串比较大小伪代码
Int compare(string a string b)
Int min_len = min(len(a) len(b))
For I to min_len
If (a[i] = b[i])
Return a[i] ndash b[i]
Return len(a) ndash len(b)
将以上 abc三部分进行特殊替换后使用amp连接最终形成的字符串的
开头和结尾都没有rdquoamprdquo这就是加密内容
2 加密的 key是 consumerSecret + amp + TokenSecret 如果 TokenSecret还没有
得到则使用rdquordquo consumerSecret和 TokenSecret需先做特殊替换然后
再进行签名
3 特殊替换是将 String进行 URL编码后将rdquo+rdquo替换为rdquo20rdquo将rdquordquo替换
为rdquo2Ardquo将rdquo7Erdquo替换为rdquo~rdquo
4 签名方法可以使用 HMAC-SHA1PLAINTEXT RSA_SHA1三种其中
PLAINTEXT为 2中的 key 该方法不提倡使用
得到签名内容后使用 Base64进行编码编码后的字符串即为 oauth_signature
httpnoteyoudaocomywsopennotecreatejson
Header 中 Authorization的值为
OAuth[ 空 格 ]oauth_token=29cc36314495ee1cf55ebf26ca9711bc
oauth_consumer_key=407d014e17ad5cd02f3e0a55fcb198af
oauth_signature_method=HMAC-SHA1 oauth_timestamp=1323327110
oauth_nonce=280224628487931 oauth_version=10
oauth_signature=rXpd0apk82wMAZLun2FDSUt1wbQE3D
最终 Header类似于
Authorization=OAuth20oauth_token3D2229cc36314495ee1cf55ebf26ca
9711bc222C20oauth_consumer_key3D22407d014e17ad5cd02f3e0a55fcb198
af222C20oauth_signature_method3D22HMAC-SHA1222C20oauth_timest
amp3D221323327041222C20oauth_nonce3D22280155519121203222C20
oauth_version3D2210222C20oauth_signature3D22E252F8dFmTFGTmdC
FE2rnJ8f252Bkzw9c253D22
签名的具体方法详见附录 D访问 Oauth的类库包详见附录 C
用户操作 API
查看用户信息
URLhttp[baseURL]ywsopenusergetjson
请求方式GET
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数无
返回结果操作成功时 http 状态为 200并用户信息失败时 http 状态为
500并返回错误码和错误信息详见附录 B
结果示例
ldquouserrdquo ldquotest163comrdquo 用户 ID
ldquototal_sizerdquo ldquo10293736383rdquo 用户总的空间大小单位字节
ldquoused_sizerdquo ldquo1024rdquo 用户已经使用了的空间大小单位字节
ldquoregister_timerdquo ldquo1323310917650rdquo 用户注册时间单位毫秒
ldquolast_login_timerdquo ldquo1323310949120rdquo 用户最后登录时间单位毫秒
ldquolast_modify_timerdquo ldquo1323310978120rdquo 用户最后修改时间单位毫秒
ldquodefault_notebookrdquo ldquoAB384D734rdquo 该应用的默认笔记本
注对于每个第三方应用都分别在用户的笔记空间中对应一个默认笔记本
笔记本名在申请应用时指定在使用 OpenAPI创建笔记时如果第三方应用
不指定笔记本则自动创建在该默认笔记本中
笔记本操作 API
查看用户全部笔记本
URLhttp[baseURL]ywsopennotebookalljson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数无
返回结果操作成功时 http状态为 200并返回笔记本列表失败时 http状
态为 500并返回错误码和错误信息详见附录 B
结果示例
[
ldquopathrdquo ldquo4AF64012E9864Crdquo 笔记本的路径
ldquonamerdquo ldquo笔记本 1rdquo 笔记本的名称
ldquonotes_numrdquo ldquo3rdquo 该笔记本中笔记的数目
ldquocreate_timerdquo ldquo1323310917rdquo 笔记本的创建时间单位秒
ldquomodify_timerdquo ldquo1323310949rdquo 笔记本的最后修改时间单位秒
ldquopathrdquo ldquo5AB0C6B33BD1162rdquo
ldquonamerdquo ldquo笔记本 2rdquo
ldquonotes_numrdquo ldquo10rdquo
ldquocreate_timerdquo ldquo1323311244rdquo
ldquomodify_timerdquo ldquo1323310349rdquo
]
列出笔记本下的笔记
URLhttp[baseURL]ywsopennotebooklistjson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
notebook 笔记本路径 是 String
返回结果操作成功时 http状态为 200并返回该笔记本下的笔记列表(只
有笔记路径笔记内容需要通过笔记接口获取)失败时 http状态 500并返
回错误码和错误信息详见附录 B
结果示例
[
ldquo4AF64012E9864C123TDE3DCrdquo 笔记路径
ldquo4AF64012E9864CDC12FTDE3rdquo
ldquo4AF64012E9864CFE23TDE3Crdquo
]
创建笔记本
URL http[baseURL]ywsopennotebookcreatejson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
name 笔记本名称 是 String
返回结果操作成功时 http状态 200并返回新创建笔记本的路径失败时
http状态 500并返回错误码和错误信息详见附录 B
结果示例
ldquopathrdquo ldquo4AF64012E9864Crdquo
删除笔记本
URL http[baseURL]ywsopennotebookdeletejson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
notebook 笔记本路径 是 String
返回结果操作成功时 http状态 200无返回数据失败时 http状态 500并
返回错误码和错误信息详见附录 B
笔记操作 API
创建笔记
URL http[baseURL]ywsopennotecreatejson
请求方式POST
Content-Typemultipartform-data
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
source 笔记来源 URL 否 String
author 笔记作者 否 String
title 笔记标题 否 String
content 笔记正文(笔记格式见附录 A) 是 String
notebook 该新建笔记所属的笔记本路径 否 String
返回结果操作成功时 http状态为 200并返回新建笔记的路径失败时 http
状态为 500并返回错误码和错误信息详见附录 B
结果示例
ldquopathrdquo ldquo4AF64012E9864CFE89D12134Erdquo
注如果第三方应用没有指定 notebook则在该第三方应用对应的默认笔记
本中创建该笔记
查看笔记
URL http[baseURL]ywsopennotegetjson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
path 笔记路径 是 String
返回结果操作成功时 http状态为 200并返回该笔记的相关信息失败时
http状态为 500并返回错误码和错误信息详见附录 B
结果示例
ldquotitlerdquo ldquo工作记录rdquo 笔记标题
ldquoauthorrdquo ldquoTomrdquo 笔记作者
ldquosourcerdquo ldquohttpnoteyoudaocomrdquo 笔记来源 URL
ldquosizerdquo ldquo1024rdquo 笔记大小包括笔记正文及附件
ldquocreate_timerdquo ldquo1323310917rdquo 笔记的创建时间单位秒
ldquomodify_timerdquo ldquo1323310949rdquo 笔记的最后修改时间单位秒
ldquocontentrdquo ldquoltpgtThis is a test noteltpgt 笔记正文
修改笔记
URL http[baseURL]ywsopennoteupdatejson
请求方式POST
Content-Typemultipartform-data
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
path 修改笔记的路径 是 String
source 修改后的笔记来源 URL 否 String
author 修改后的笔记作者 否 String
title 修改后的笔记标题 否 String
content 修改后的笔记正文(笔记格式见
附录 A)
是 String
返回结果操作成功时 http 状态为 200无返回结果失败时 http 状态为
500并返回错误码和错误信息详见附录 B
移动笔记
URL http[baseURL]ywsopennotemovejson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
path 想要移动的笔记原路径 是 String
notebook 目标笔记本的路径 是 String
返回结果操作成功时 http状态为 200返回移动后的笔记路径失败时 http
状态为 500并返回错误码和错误信息详见附录 B
结果示例
ldquopathrdquo ldquo5AB0C6B33BD1162FE89D12134Erdquo
删除笔记
URL http[baseURL]ywsopennotedeletejson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
path 想要删除的笔记原路径 是 String
返回结果操作成功时 http 状态为 200无返回结果失败时 http 状态为
500并返回错误码和错误信息详见附录 B
附件操作 API
上传附件或图片
URLhttp[baseURL]ywsopenresourceuploadjson
请求方式POST
Content-Typemultipartform-data
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
file 上传的附件文件(包括附件的文
件名类型大小数据等)
是 Multipart File附件大
小限制 25M
返回结果操作成功时 http状态为 200对于图片返回该图片的链接 URL
对于普通附件服务器会为该附件生成一个图标文件因此返回结果包括该
附件对应的链接 URL以及图标的 URL失败时 http状态为 500并返回错误码
和错误信息详见附录 B
示例
图片附件
url httpbaseURLywsopenresource28d83f547f3055
普通附件
url httpbaseURLywsopenresource28d83f547f3055 附件 URL
src httpbaseURLywsopenresource297f2bd6fa2795 图标 URL
需要注意的是在附件上传完成后使用者应该紧接着更新对应的笔记否
则不被任何笔记引用的附件将被定期的空间回收所删除
下载附件图片图标
URLhttp[baseURL]ywsopenresourcedownload
请求方式GET
是否需要用户认证是 (关于登录授权参见请求用户授权)
返回结果操作成功时response返回附件及图片的二进制流失败时 http
状态为 500并返回错误码和错误信息详见附录 B
备注
1 当打开笔记时对于笔记中的附件及图片链接只需要添加用户的 OAuth
认证信息即可以获取对应的附件及图片同理在上传附件后返回的附
件及图片链接也可以通过这种方式进行访问
2 附件及图片的下载支持断点续传
附录 A有道云笔记内容格式
笔记内容的格式采用类 HTML的标记语言绝大部分格式相关 tag均采用标
准的 HTML Tag唯一需要不同的是附件及图片 Tag在格式上图片 Tag与标准的
img tag相同一个图片资源的标记如下
ltimg src=httpnoteyoudaocomywsopenresource227f2bd6fa2795441cgt
但是由于对应的接口需要用户认证因此在获取图片资源时需要加入 OAuth
的用户认证信息
附件通常以图标在笔记中进行显示因此我们扩展了图片 Tag ltimggt除了
img 本身的 src 属性额外加入了一个属性 path其中 src 对应着该附件的图标
URL而 path则为该附件的 URL如下所示
ltimg path=httpnoteyoudaocomywsopenresource219fe604c7c90642fd8f
src=httpnoteyoudaocomywsopenresource227f2bd6fa2795441cgt
同理也需要加入 OAuth的用户认证信息才可以正常访问附件资源及其图标
附录 B错误码及错误信息说明
同理当 Open API的请求在执行时出现任何异常或错误时系统将返回 Http
500应用程序可以根据此判断请求是否成功执行当应用程序在进行 OAuth认
证或者未经认证便调用 Open API时系统会返回 OAuth错误信息OAuth的
错误码与错误信息将以 json的格式进行返回各个错误码及错误信息说明如下
错误码 错误描述及可能原因
1001 token_rejectedconsumer没有找到consumerKey错误 consumer
没有创建或者 request token或者 access token 不存在于 server中
或者没有获得授权的 token或者 token过期
1002 parameter_rejected这个会返回具体原因 key是
oauth_parameters_rejected value是一个 parameter列表
1003 version_rejectedOAuth版本号不是 10
1004 timestamp_refusedtimestamp 非 5分钟内
1005 nonce_used5分钟内该 nonce被使用
1006 parameter_absent有些参数没有发送给 server
1007 signature_invalidoauth签名异常可能原因没有签名签名方法和
签名不一致等
1008 signature_method_rejectedoauth server没有提供该签名方法
1009 access_state_error获取 token时状态混乱详细的信息会告知当前的
状态 [AUTHORIZED | REQUEST | ACCESS | INVALID]
1010 consumer_rejected该 consumer在 server中不存在或者被禁掉
或者 consumerKey改变但是还没有反应到 server的数据库中
1011 accessor_rejected由 token得到的 accessor构造异常或者 accessor
中缺失某些属性或者转换失败
1012 callback_errorrequest token传来的 callback和以后的 callback不一致
1013 callback_domain_error当限定 callback后发来的 callback与原设置
的 callback的域不相同
1014 verifier_errorVerifier不一致错误
1015 permission_denied无授权的 token或者授权后没有获取过 access
token
同理当 Open API的请求在后台执行出现异常或错误时系统也将同时错
误码与错误信息以 json 的格式一同返回应用程序可以根据错误码得到相应的
原因常见的错误码说明如下
错误码 错误描述及可能原因
206 UNKNOWN_URI错误的 URI请求
207 AUTHENTICATION_FAILURE用户认证错误
209 RESOURCE_NOT_EXIST请求的资源(笔记本笔记附件等)不存在
210 USER_SPACE_FULL用户空间已满
214 INVALID_PARAMETER错误的传入参数必须的参数为空等
220 USER_NOT_EXISTS用户不存在
221 USER_ALREADY_EXISTS用户已经存在不能重复注册
225 PARENT_NOT_EXIST笔记本尚不存在不能在该笔记本下创建笔记
231 RESOURCE_ALREADY_EXIST该笔记或者附件已经存在不能重复创建
304 NOTE_ALREADY_DELETED笔记已经被删除
307 INVALID_APPLICATION无效的第三方应用未经过用户授权或者授权
失败便通过 OpenAPI访问用户数据这个一般是使用测试环境得到了
access_token利用该 access_token访问了线上环境这两套环境是独
立的Access_token不能共用
但是如果第三方应用未经过用户授权
示例当查看笔记路径错误时
error 209
message Required note does not exist path=5AB0C6B33BD12FE89D12134E
附录 C 访问 OAuth Server的类库与包
ActionScriptFlash
oauth-as3 httpcodegooglecompoauth-as3
A flex oauth client
httpwwwarcgiscomhomeitemhtmlid=ff6ffa302ad04a7194999f2ad08250d7
CC++
QTweetLib httpgithubcomminimoogQTweetLib
libOAuth httpliboauthsourceforgenet
clojure
clj-oauth httpgithubcommattreplclj-oauth
net
oauth-dot-net httpcodegooglecompoauth-dot-net
DotNetOpenAuth httpwwwdotnetopenauthnet
Erlang
erlang-oauth httpgithubcomtimerlang-oauth
java
Scrible httpgithubcomfernandezpablo85scribe-java
oauth-signpost httpcodegooglecompoauth-signpost
javascript
oauth in js httpoauthgooglecodecomsvncodejavascript
Objective-CCocoa amp iPhone programming
OAuthCore httpbitbucketorgatebitsoauthcore
MPOAuthConnection httpcodegooglecompmpoauthconnection
Objective-C OAuth httpoauthgooglecodecomsvncodeobj-c
Perl
NetOAuth httpoauthgooglecodecomsvncodeperl
PHP
tmhOAuth httpgithubcomthemattharristmhOAuth
oauth-php httpcodegooglecompoauth-php
Python
python-oauth2 httpgithubcombrosnerpython-oauth2
Qt
qOauth httpgithubcomayoyqoauth
Ruby
Oauth ruby gem httpoauthrubyforgeorg
Scala
DataBinder Dispatch httpdispatchdatabindernetAbout
附录 D Oauth签名加密 oauth_signature
1 加密内容是
a 请求方法名例如 GET POST等 加密时方法名大写并进行特殊替换
(详见 3)
b url (query param之前的部分不包括 )Http或者 https需要全部小
写 http如果带有 80端口或者 https带有 443端口需要将其省略
其他端口则不能省略例如
Httplocal9999requestToken
httplocal9999requestToken
Httplocal80requestToken
httplocalrequestToken
Httpslocal443requestToken
httpslocal requestToken
c 参数(query param中的或者 header中的 key-value对) 首先将这些参数
进行特殊替换后按字典序排序升序排列如果两个 key相同则以
value特殊替换后字典序为准key与 value之间使用rdquo=rdquo连接如果
value==null则使用rdquordquo替代两个参数对之间使用rdquoamprdquo连接连接后形成
的最终字符串的开头和结尾没有rdquoamprdquo
d 字典序字符串比较大小伪代码
Int compare(string a string b)
Int min_len = min(len(a) len(b))
For I to min_len
If (a[i] = b[i])
Return a[i] ndash b[i]
Return len(a) ndash len(b)
将以上 abc三部分进行特殊替换后使用amp连接最终形成的字符串的
开头和结尾都没有rdquoamprdquo这就是加密内容
2 加密的 key是 consumerSecret + amp + TokenSecret 如果 TokenSecret还没有
得到则使用rdquordquo consumerSecret和 TokenSecret需先做特殊替换然后
再进行签名
3 特殊替换是将 String进行 URL编码后将rdquo+rdquo替换为rdquo20rdquo将rdquordquo替换
为rdquo2Ardquo将rdquo7Erdquo替换为rdquo~rdquo
4 签名方法可以使用 HMAC-SHA1PLAINTEXT RSA_SHA1三种其中
PLAINTEXT为 2中的 key 该方法不提倡使用
得到签名内容后使用 Base64进行编码编码后的字符串即为 oauth_signature
ldquolast_modify_timerdquo ldquo1323310978120rdquo 用户最后修改时间单位毫秒
ldquodefault_notebookrdquo ldquoAB384D734rdquo 该应用的默认笔记本
注对于每个第三方应用都分别在用户的笔记空间中对应一个默认笔记本
笔记本名在申请应用时指定在使用 OpenAPI创建笔记时如果第三方应用
不指定笔记本则自动创建在该默认笔记本中
笔记本操作 API
查看用户全部笔记本
URLhttp[baseURL]ywsopennotebookalljson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数无
返回结果操作成功时 http状态为 200并返回笔记本列表失败时 http状
态为 500并返回错误码和错误信息详见附录 B
结果示例
[
ldquopathrdquo ldquo4AF64012E9864Crdquo 笔记本的路径
ldquonamerdquo ldquo笔记本 1rdquo 笔记本的名称
ldquonotes_numrdquo ldquo3rdquo 该笔记本中笔记的数目
ldquocreate_timerdquo ldquo1323310917rdquo 笔记本的创建时间单位秒
ldquomodify_timerdquo ldquo1323310949rdquo 笔记本的最后修改时间单位秒
ldquopathrdquo ldquo5AB0C6B33BD1162rdquo
ldquonamerdquo ldquo笔记本 2rdquo
ldquonotes_numrdquo ldquo10rdquo
ldquocreate_timerdquo ldquo1323311244rdquo
ldquomodify_timerdquo ldquo1323310349rdquo
]
列出笔记本下的笔记
URLhttp[baseURL]ywsopennotebooklistjson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
notebook 笔记本路径 是 String
返回结果操作成功时 http状态为 200并返回该笔记本下的笔记列表(只
有笔记路径笔记内容需要通过笔记接口获取)失败时 http状态 500并返
回错误码和错误信息详见附录 B
结果示例
[
ldquo4AF64012E9864C123TDE3DCrdquo 笔记路径
ldquo4AF64012E9864CDC12FTDE3rdquo
ldquo4AF64012E9864CFE23TDE3Crdquo
]
创建笔记本
URL http[baseURL]ywsopennotebookcreatejson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
name 笔记本名称 是 String
返回结果操作成功时 http状态 200并返回新创建笔记本的路径失败时
http状态 500并返回错误码和错误信息详见附录 B
结果示例
ldquopathrdquo ldquo4AF64012E9864Crdquo
删除笔记本
URL http[baseURL]ywsopennotebookdeletejson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
notebook 笔记本路径 是 String
返回结果操作成功时 http状态 200无返回数据失败时 http状态 500并
返回错误码和错误信息详见附录 B
笔记操作 API
创建笔记
URL http[baseURL]ywsopennotecreatejson
请求方式POST
Content-Typemultipartform-data
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
source 笔记来源 URL 否 String
author 笔记作者 否 String
title 笔记标题 否 String
content 笔记正文(笔记格式见附录 A) 是 String
notebook 该新建笔记所属的笔记本路径 否 String
返回结果操作成功时 http状态为 200并返回新建笔记的路径失败时 http
状态为 500并返回错误码和错误信息详见附录 B
结果示例
ldquopathrdquo ldquo4AF64012E9864CFE89D12134Erdquo
注如果第三方应用没有指定 notebook则在该第三方应用对应的默认笔记
本中创建该笔记
查看笔记
URL http[baseURL]ywsopennotegetjson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
path 笔记路径 是 String
返回结果操作成功时 http状态为 200并返回该笔记的相关信息失败时
http状态为 500并返回错误码和错误信息详见附录 B
结果示例
ldquotitlerdquo ldquo工作记录rdquo 笔记标题
ldquoauthorrdquo ldquoTomrdquo 笔记作者
ldquosourcerdquo ldquohttpnoteyoudaocomrdquo 笔记来源 URL
ldquosizerdquo ldquo1024rdquo 笔记大小包括笔记正文及附件
ldquocreate_timerdquo ldquo1323310917rdquo 笔记的创建时间单位秒
ldquomodify_timerdquo ldquo1323310949rdquo 笔记的最后修改时间单位秒
ldquocontentrdquo ldquoltpgtThis is a test noteltpgt 笔记正文
修改笔记
URL http[baseURL]ywsopennoteupdatejson
请求方式POST
Content-Typemultipartform-data
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
path 修改笔记的路径 是 String
source 修改后的笔记来源 URL 否 String
author 修改后的笔记作者 否 String
title 修改后的笔记标题 否 String
content 修改后的笔记正文(笔记格式见
附录 A)
是 String
返回结果操作成功时 http 状态为 200无返回结果失败时 http 状态为
500并返回错误码和错误信息详见附录 B
移动笔记
URL http[baseURL]ywsopennotemovejson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
path 想要移动的笔记原路径 是 String
notebook 目标笔记本的路径 是 String
返回结果操作成功时 http状态为 200返回移动后的笔记路径失败时 http
状态为 500并返回错误码和错误信息详见附录 B
结果示例
ldquopathrdquo ldquo5AB0C6B33BD1162FE89D12134Erdquo
删除笔记
URL http[baseURL]ywsopennotedeletejson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
path 想要删除的笔记原路径 是 String
返回结果操作成功时 http 状态为 200无返回结果失败时 http 状态为
500并返回错误码和错误信息详见附录 B
附件操作 API
上传附件或图片
URLhttp[baseURL]ywsopenresourceuploadjson
请求方式POST
Content-Typemultipartform-data
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
file 上传的附件文件(包括附件的文
件名类型大小数据等)
是 Multipart File附件大
小限制 25M
返回结果操作成功时 http状态为 200对于图片返回该图片的链接 URL
对于普通附件服务器会为该附件生成一个图标文件因此返回结果包括该
附件对应的链接 URL以及图标的 URL失败时 http状态为 500并返回错误码
和错误信息详见附录 B
示例
图片附件
url httpbaseURLywsopenresource28d83f547f3055
普通附件
url httpbaseURLywsopenresource28d83f547f3055 附件 URL
src httpbaseURLywsopenresource297f2bd6fa2795 图标 URL
需要注意的是在附件上传完成后使用者应该紧接着更新对应的笔记否
则不被任何笔记引用的附件将被定期的空间回收所删除
下载附件图片图标
URLhttp[baseURL]ywsopenresourcedownload
请求方式GET
是否需要用户认证是 (关于登录授权参见请求用户授权)
返回结果操作成功时response返回附件及图片的二进制流失败时 http
状态为 500并返回错误码和错误信息详见附录 B
备注
1 当打开笔记时对于笔记中的附件及图片链接只需要添加用户的 OAuth
认证信息即可以获取对应的附件及图片同理在上传附件后返回的附
件及图片链接也可以通过这种方式进行访问
2 附件及图片的下载支持断点续传
附录 A有道云笔记内容格式
笔记内容的格式采用类 HTML的标记语言绝大部分格式相关 tag均采用标
准的 HTML Tag唯一需要不同的是附件及图片 Tag在格式上图片 Tag与标准的
img tag相同一个图片资源的标记如下
ltimg src=httpnoteyoudaocomywsopenresource227f2bd6fa2795441cgt
但是由于对应的接口需要用户认证因此在获取图片资源时需要加入 OAuth
的用户认证信息
附件通常以图标在笔记中进行显示因此我们扩展了图片 Tag ltimggt除了
img 本身的 src 属性额外加入了一个属性 path其中 src 对应着该附件的图标
URL而 path则为该附件的 URL如下所示
ltimg path=httpnoteyoudaocomywsopenresource219fe604c7c90642fd8f
src=httpnoteyoudaocomywsopenresource227f2bd6fa2795441cgt
同理也需要加入 OAuth的用户认证信息才可以正常访问附件资源及其图标
附录 B错误码及错误信息说明
同理当 Open API的请求在执行时出现任何异常或错误时系统将返回 Http
500应用程序可以根据此判断请求是否成功执行当应用程序在进行 OAuth认
证或者未经认证便调用 Open API时系统会返回 OAuth错误信息OAuth的
错误码与错误信息将以 json的格式进行返回各个错误码及错误信息说明如下
错误码 错误描述及可能原因
1001 token_rejectedconsumer没有找到consumerKey错误 consumer
没有创建或者 request token或者 access token 不存在于 server中
或者没有获得授权的 token或者 token过期
1002 parameter_rejected这个会返回具体原因 key是
oauth_parameters_rejected value是一个 parameter列表
1003 version_rejectedOAuth版本号不是 10
1004 timestamp_refusedtimestamp 非 5分钟内
1005 nonce_used5分钟内该 nonce被使用
1006 parameter_absent有些参数没有发送给 server
1007 signature_invalidoauth签名异常可能原因没有签名签名方法和
签名不一致等
1008 signature_method_rejectedoauth server没有提供该签名方法
1009 access_state_error获取 token时状态混乱详细的信息会告知当前的
状态 [AUTHORIZED | REQUEST | ACCESS | INVALID]
1010 consumer_rejected该 consumer在 server中不存在或者被禁掉
或者 consumerKey改变但是还没有反应到 server的数据库中
1011 accessor_rejected由 token得到的 accessor构造异常或者 accessor
中缺失某些属性或者转换失败
1012 callback_errorrequest token传来的 callback和以后的 callback不一致
1013 callback_domain_error当限定 callback后发来的 callback与原设置
的 callback的域不相同
1014 verifier_errorVerifier不一致错误
1015 permission_denied无授权的 token或者授权后没有获取过 access
token
同理当 Open API的请求在后台执行出现异常或错误时系统也将同时错
误码与错误信息以 json 的格式一同返回应用程序可以根据错误码得到相应的
原因常见的错误码说明如下
错误码 错误描述及可能原因
206 UNKNOWN_URI错误的 URI请求
207 AUTHENTICATION_FAILURE用户认证错误
209 RESOURCE_NOT_EXIST请求的资源(笔记本笔记附件等)不存在
210 USER_SPACE_FULL用户空间已满
214 INVALID_PARAMETER错误的传入参数必须的参数为空等
220 USER_NOT_EXISTS用户不存在
221 USER_ALREADY_EXISTS用户已经存在不能重复注册
225 PARENT_NOT_EXIST笔记本尚不存在不能在该笔记本下创建笔记
231 RESOURCE_ALREADY_EXIST该笔记或者附件已经存在不能重复创建
304 NOTE_ALREADY_DELETED笔记已经被删除
307 INVALID_APPLICATION无效的第三方应用未经过用户授权或者授权
失败便通过 OpenAPI访问用户数据这个一般是使用测试环境得到了
access_token利用该 access_token访问了线上环境这两套环境是独
立的Access_token不能共用
但是如果第三方应用未经过用户授权
示例当查看笔记路径错误时
error 209
message Required note does not exist path=5AB0C6B33BD12FE89D12134E
附录 C 访问 OAuth Server的类库与包
ActionScriptFlash
oauth-as3 httpcodegooglecompoauth-as3
A flex oauth client
httpwwwarcgiscomhomeitemhtmlid=ff6ffa302ad04a7194999f2ad08250d7
CC++
QTweetLib httpgithubcomminimoogQTweetLib
libOAuth httpliboauthsourceforgenet
clojure
clj-oauth httpgithubcommattreplclj-oauth
net
oauth-dot-net httpcodegooglecompoauth-dot-net
DotNetOpenAuth httpwwwdotnetopenauthnet
Erlang
erlang-oauth httpgithubcomtimerlang-oauth
java
Scrible httpgithubcomfernandezpablo85scribe-java
oauth-signpost httpcodegooglecompoauth-signpost
javascript
oauth in js httpoauthgooglecodecomsvncodejavascript
Objective-CCocoa amp iPhone programming
OAuthCore httpbitbucketorgatebitsoauthcore
MPOAuthConnection httpcodegooglecompmpoauthconnection
Objective-C OAuth httpoauthgooglecodecomsvncodeobj-c
Perl
NetOAuth httpoauthgooglecodecomsvncodeperl
PHP
tmhOAuth httpgithubcomthemattharristmhOAuth
oauth-php httpcodegooglecompoauth-php
Python
python-oauth2 httpgithubcombrosnerpython-oauth2
Qt
qOauth httpgithubcomayoyqoauth
Ruby
Oauth ruby gem httpoauthrubyforgeorg
Scala
DataBinder Dispatch httpdispatchdatabindernetAbout
附录 D Oauth签名加密 oauth_signature
1 加密内容是
a 请求方法名例如 GET POST等 加密时方法名大写并进行特殊替换
(详见 3)
b url (query param之前的部分不包括 )Http或者 https需要全部小
写 http如果带有 80端口或者 https带有 443端口需要将其省略
其他端口则不能省略例如
Httplocal9999requestToken
httplocal9999requestToken
Httplocal80requestToken
httplocalrequestToken
Httpslocal443requestToken
httpslocal requestToken
c 参数(query param中的或者 header中的 key-value对) 首先将这些参数
进行特殊替换后按字典序排序升序排列如果两个 key相同则以
value特殊替换后字典序为准key与 value之间使用rdquo=rdquo连接如果
value==null则使用rdquordquo替代两个参数对之间使用rdquoamprdquo连接连接后形成
的最终字符串的开头和结尾没有rdquoamprdquo
d 字典序字符串比较大小伪代码
Int compare(string a string b)
Int min_len = min(len(a) len(b))
For I to min_len
If (a[i] = b[i])
Return a[i] ndash b[i]
Return len(a) ndash len(b)
将以上 abc三部分进行特殊替换后使用amp连接最终形成的字符串的
开头和结尾都没有rdquoamprdquo这就是加密内容
2 加密的 key是 consumerSecret + amp + TokenSecret 如果 TokenSecret还没有
得到则使用rdquordquo consumerSecret和 TokenSecret需先做特殊替换然后
再进行签名
3 特殊替换是将 String进行 URL编码后将rdquo+rdquo替换为rdquo20rdquo将rdquordquo替换
为rdquo2Ardquo将rdquo7Erdquo替换为rdquo~rdquo
4 签名方法可以使用 HMAC-SHA1PLAINTEXT RSA_SHA1三种其中
PLAINTEXT为 2中的 key 该方法不提倡使用
得到签名内容后使用 Base64进行编码编码后的字符串即为 oauth_signature
列出笔记本下的笔记
URLhttp[baseURL]ywsopennotebooklistjson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
notebook 笔记本路径 是 String
返回结果操作成功时 http状态为 200并返回该笔记本下的笔记列表(只
有笔记路径笔记内容需要通过笔记接口获取)失败时 http状态 500并返
回错误码和错误信息详见附录 B
结果示例
[
ldquo4AF64012E9864C123TDE3DCrdquo 笔记路径
ldquo4AF64012E9864CDC12FTDE3rdquo
ldquo4AF64012E9864CFE23TDE3Crdquo
]
创建笔记本
URL http[baseURL]ywsopennotebookcreatejson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
name 笔记本名称 是 String
返回结果操作成功时 http状态 200并返回新创建笔记本的路径失败时
http状态 500并返回错误码和错误信息详见附录 B
结果示例
ldquopathrdquo ldquo4AF64012E9864Crdquo
删除笔记本
URL http[baseURL]ywsopennotebookdeletejson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
notebook 笔记本路径 是 String
返回结果操作成功时 http状态 200无返回数据失败时 http状态 500并
返回错误码和错误信息详见附录 B
笔记操作 API
创建笔记
URL http[baseURL]ywsopennotecreatejson
请求方式POST
Content-Typemultipartform-data
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
source 笔记来源 URL 否 String
author 笔记作者 否 String
title 笔记标题 否 String
content 笔记正文(笔记格式见附录 A) 是 String
notebook 该新建笔记所属的笔记本路径 否 String
返回结果操作成功时 http状态为 200并返回新建笔记的路径失败时 http
状态为 500并返回错误码和错误信息详见附录 B
结果示例
ldquopathrdquo ldquo4AF64012E9864CFE89D12134Erdquo
注如果第三方应用没有指定 notebook则在该第三方应用对应的默认笔记
本中创建该笔记
查看笔记
URL http[baseURL]ywsopennotegetjson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
path 笔记路径 是 String
返回结果操作成功时 http状态为 200并返回该笔记的相关信息失败时
http状态为 500并返回错误码和错误信息详见附录 B
结果示例
ldquotitlerdquo ldquo工作记录rdquo 笔记标题
ldquoauthorrdquo ldquoTomrdquo 笔记作者
ldquosourcerdquo ldquohttpnoteyoudaocomrdquo 笔记来源 URL
ldquosizerdquo ldquo1024rdquo 笔记大小包括笔记正文及附件
ldquocreate_timerdquo ldquo1323310917rdquo 笔记的创建时间单位秒
ldquomodify_timerdquo ldquo1323310949rdquo 笔记的最后修改时间单位秒
ldquocontentrdquo ldquoltpgtThis is a test noteltpgt 笔记正文
修改笔记
URL http[baseURL]ywsopennoteupdatejson
请求方式POST
Content-Typemultipartform-data
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
path 修改笔记的路径 是 String
source 修改后的笔记来源 URL 否 String
author 修改后的笔记作者 否 String
title 修改后的笔记标题 否 String
content 修改后的笔记正文(笔记格式见
附录 A)
是 String
返回结果操作成功时 http 状态为 200无返回结果失败时 http 状态为
500并返回错误码和错误信息详见附录 B
移动笔记
URL http[baseURL]ywsopennotemovejson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
path 想要移动的笔记原路径 是 String
notebook 目标笔记本的路径 是 String
返回结果操作成功时 http状态为 200返回移动后的笔记路径失败时 http
状态为 500并返回错误码和错误信息详见附录 B
结果示例
ldquopathrdquo ldquo5AB0C6B33BD1162FE89D12134Erdquo
删除笔记
URL http[baseURL]ywsopennotedeletejson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
path 想要删除的笔记原路径 是 String
返回结果操作成功时 http 状态为 200无返回结果失败时 http 状态为
500并返回错误码和错误信息详见附录 B
附件操作 API
上传附件或图片
URLhttp[baseURL]ywsopenresourceuploadjson
请求方式POST
Content-Typemultipartform-data
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
file 上传的附件文件(包括附件的文
件名类型大小数据等)
是 Multipart File附件大
小限制 25M
返回结果操作成功时 http状态为 200对于图片返回该图片的链接 URL
对于普通附件服务器会为该附件生成一个图标文件因此返回结果包括该
附件对应的链接 URL以及图标的 URL失败时 http状态为 500并返回错误码
和错误信息详见附录 B
示例
图片附件
url httpbaseURLywsopenresource28d83f547f3055
普通附件
url httpbaseURLywsopenresource28d83f547f3055 附件 URL
src httpbaseURLywsopenresource297f2bd6fa2795 图标 URL
需要注意的是在附件上传完成后使用者应该紧接着更新对应的笔记否
则不被任何笔记引用的附件将被定期的空间回收所删除
下载附件图片图标
URLhttp[baseURL]ywsopenresourcedownload
请求方式GET
是否需要用户认证是 (关于登录授权参见请求用户授权)
返回结果操作成功时response返回附件及图片的二进制流失败时 http
状态为 500并返回错误码和错误信息详见附录 B
备注
1 当打开笔记时对于笔记中的附件及图片链接只需要添加用户的 OAuth
认证信息即可以获取对应的附件及图片同理在上传附件后返回的附
件及图片链接也可以通过这种方式进行访问
2 附件及图片的下载支持断点续传
附录 A有道云笔记内容格式
笔记内容的格式采用类 HTML的标记语言绝大部分格式相关 tag均采用标
准的 HTML Tag唯一需要不同的是附件及图片 Tag在格式上图片 Tag与标准的
img tag相同一个图片资源的标记如下
ltimg src=httpnoteyoudaocomywsopenresource227f2bd6fa2795441cgt
但是由于对应的接口需要用户认证因此在获取图片资源时需要加入 OAuth
的用户认证信息
附件通常以图标在笔记中进行显示因此我们扩展了图片 Tag ltimggt除了
img 本身的 src 属性额外加入了一个属性 path其中 src 对应着该附件的图标
URL而 path则为该附件的 URL如下所示
ltimg path=httpnoteyoudaocomywsopenresource219fe604c7c90642fd8f
src=httpnoteyoudaocomywsopenresource227f2bd6fa2795441cgt
同理也需要加入 OAuth的用户认证信息才可以正常访问附件资源及其图标
附录 B错误码及错误信息说明
同理当 Open API的请求在执行时出现任何异常或错误时系统将返回 Http
500应用程序可以根据此判断请求是否成功执行当应用程序在进行 OAuth认
证或者未经认证便调用 Open API时系统会返回 OAuth错误信息OAuth的
错误码与错误信息将以 json的格式进行返回各个错误码及错误信息说明如下
错误码 错误描述及可能原因
1001 token_rejectedconsumer没有找到consumerKey错误 consumer
没有创建或者 request token或者 access token 不存在于 server中
或者没有获得授权的 token或者 token过期
1002 parameter_rejected这个会返回具体原因 key是
oauth_parameters_rejected value是一个 parameter列表
1003 version_rejectedOAuth版本号不是 10
1004 timestamp_refusedtimestamp 非 5分钟内
1005 nonce_used5分钟内该 nonce被使用
1006 parameter_absent有些参数没有发送给 server
1007 signature_invalidoauth签名异常可能原因没有签名签名方法和
签名不一致等
1008 signature_method_rejectedoauth server没有提供该签名方法
1009 access_state_error获取 token时状态混乱详细的信息会告知当前的
状态 [AUTHORIZED | REQUEST | ACCESS | INVALID]
1010 consumer_rejected该 consumer在 server中不存在或者被禁掉
或者 consumerKey改变但是还没有反应到 server的数据库中
1011 accessor_rejected由 token得到的 accessor构造异常或者 accessor
中缺失某些属性或者转换失败
1012 callback_errorrequest token传来的 callback和以后的 callback不一致
1013 callback_domain_error当限定 callback后发来的 callback与原设置
的 callback的域不相同
1014 verifier_errorVerifier不一致错误
1015 permission_denied无授权的 token或者授权后没有获取过 access
token
同理当 Open API的请求在后台执行出现异常或错误时系统也将同时错
误码与错误信息以 json 的格式一同返回应用程序可以根据错误码得到相应的
原因常见的错误码说明如下
错误码 错误描述及可能原因
206 UNKNOWN_URI错误的 URI请求
207 AUTHENTICATION_FAILURE用户认证错误
209 RESOURCE_NOT_EXIST请求的资源(笔记本笔记附件等)不存在
210 USER_SPACE_FULL用户空间已满
214 INVALID_PARAMETER错误的传入参数必须的参数为空等
220 USER_NOT_EXISTS用户不存在
221 USER_ALREADY_EXISTS用户已经存在不能重复注册
225 PARENT_NOT_EXIST笔记本尚不存在不能在该笔记本下创建笔记
231 RESOURCE_ALREADY_EXIST该笔记或者附件已经存在不能重复创建
304 NOTE_ALREADY_DELETED笔记已经被删除
307 INVALID_APPLICATION无效的第三方应用未经过用户授权或者授权
失败便通过 OpenAPI访问用户数据这个一般是使用测试环境得到了
access_token利用该 access_token访问了线上环境这两套环境是独
立的Access_token不能共用
但是如果第三方应用未经过用户授权
示例当查看笔记路径错误时
error 209
message Required note does not exist path=5AB0C6B33BD12FE89D12134E
附录 C 访问 OAuth Server的类库与包
ActionScriptFlash
oauth-as3 httpcodegooglecompoauth-as3
A flex oauth client
httpwwwarcgiscomhomeitemhtmlid=ff6ffa302ad04a7194999f2ad08250d7
CC++
QTweetLib httpgithubcomminimoogQTweetLib
libOAuth httpliboauthsourceforgenet
clojure
clj-oauth httpgithubcommattreplclj-oauth
net
oauth-dot-net httpcodegooglecompoauth-dot-net
DotNetOpenAuth httpwwwdotnetopenauthnet
Erlang
erlang-oauth httpgithubcomtimerlang-oauth
java
Scrible httpgithubcomfernandezpablo85scribe-java
oauth-signpost httpcodegooglecompoauth-signpost
javascript
oauth in js httpoauthgooglecodecomsvncodejavascript
Objective-CCocoa amp iPhone programming
OAuthCore httpbitbucketorgatebitsoauthcore
MPOAuthConnection httpcodegooglecompmpoauthconnection
Objective-C OAuth httpoauthgooglecodecomsvncodeobj-c
Perl
NetOAuth httpoauthgooglecodecomsvncodeperl
PHP
tmhOAuth httpgithubcomthemattharristmhOAuth
oauth-php httpcodegooglecompoauth-php
Python
python-oauth2 httpgithubcombrosnerpython-oauth2
Qt
qOauth httpgithubcomayoyqoauth
Ruby
Oauth ruby gem httpoauthrubyforgeorg
Scala
DataBinder Dispatch httpdispatchdatabindernetAbout
附录 D Oauth签名加密 oauth_signature
1 加密内容是
a 请求方法名例如 GET POST等 加密时方法名大写并进行特殊替换
(详见 3)
b url (query param之前的部分不包括 )Http或者 https需要全部小
写 http如果带有 80端口或者 https带有 443端口需要将其省略
其他端口则不能省略例如
Httplocal9999requestToken
httplocal9999requestToken
Httplocal80requestToken
httplocalrequestToken
Httpslocal443requestToken
httpslocal requestToken
c 参数(query param中的或者 header中的 key-value对) 首先将这些参数
进行特殊替换后按字典序排序升序排列如果两个 key相同则以
value特殊替换后字典序为准key与 value之间使用rdquo=rdquo连接如果
value==null则使用rdquordquo替代两个参数对之间使用rdquoamprdquo连接连接后形成
的最终字符串的开头和结尾没有rdquoamprdquo
d 字典序字符串比较大小伪代码
Int compare(string a string b)
Int min_len = min(len(a) len(b))
For I to min_len
If (a[i] = b[i])
Return a[i] ndash b[i]
Return len(a) ndash len(b)
将以上 abc三部分进行特殊替换后使用amp连接最终形成的字符串的
开头和结尾都没有rdquoamprdquo这就是加密内容
2 加密的 key是 consumerSecret + amp + TokenSecret 如果 TokenSecret还没有
得到则使用rdquordquo consumerSecret和 TokenSecret需先做特殊替换然后
再进行签名
3 特殊替换是将 String进行 URL编码后将rdquo+rdquo替换为rdquo20rdquo将rdquordquo替换
为rdquo2Ardquo将rdquo7Erdquo替换为rdquo~rdquo
4 签名方法可以使用 HMAC-SHA1PLAINTEXT RSA_SHA1三种其中
PLAINTEXT为 2中的 key 该方法不提倡使用
得到签名内容后使用 Base64进行编码编码后的字符串即为 oauth_signature
删除笔记本
URL http[baseURL]ywsopennotebookdeletejson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
notebook 笔记本路径 是 String
返回结果操作成功时 http状态 200无返回数据失败时 http状态 500并
返回错误码和错误信息详见附录 B
笔记操作 API
创建笔记
URL http[baseURL]ywsopennotecreatejson
请求方式POST
Content-Typemultipartform-data
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
source 笔记来源 URL 否 String
author 笔记作者 否 String
title 笔记标题 否 String
content 笔记正文(笔记格式见附录 A) 是 String
notebook 该新建笔记所属的笔记本路径 否 String
返回结果操作成功时 http状态为 200并返回新建笔记的路径失败时 http
状态为 500并返回错误码和错误信息详见附录 B
结果示例
ldquopathrdquo ldquo4AF64012E9864CFE89D12134Erdquo
注如果第三方应用没有指定 notebook则在该第三方应用对应的默认笔记
本中创建该笔记
查看笔记
URL http[baseURL]ywsopennotegetjson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
path 笔记路径 是 String
返回结果操作成功时 http状态为 200并返回该笔记的相关信息失败时
http状态为 500并返回错误码和错误信息详见附录 B
结果示例
ldquotitlerdquo ldquo工作记录rdquo 笔记标题
ldquoauthorrdquo ldquoTomrdquo 笔记作者
ldquosourcerdquo ldquohttpnoteyoudaocomrdquo 笔记来源 URL
ldquosizerdquo ldquo1024rdquo 笔记大小包括笔记正文及附件
ldquocreate_timerdquo ldquo1323310917rdquo 笔记的创建时间单位秒
ldquomodify_timerdquo ldquo1323310949rdquo 笔记的最后修改时间单位秒
ldquocontentrdquo ldquoltpgtThis is a test noteltpgt 笔记正文
修改笔记
URL http[baseURL]ywsopennoteupdatejson
请求方式POST
Content-Typemultipartform-data
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
path 修改笔记的路径 是 String
source 修改后的笔记来源 URL 否 String
author 修改后的笔记作者 否 String
title 修改后的笔记标题 否 String
content 修改后的笔记正文(笔记格式见
附录 A)
是 String
返回结果操作成功时 http 状态为 200无返回结果失败时 http 状态为
500并返回错误码和错误信息详见附录 B
移动笔记
URL http[baseURL]ywsopennotemovejson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
path 想要移动的笔记原路径 是 String
notebook 目标笔记本的路径 是 String
返回结果操作成功时 http状态为 200返回移动后的笔记路径失败时 http
状态为 500并返回错误码和错误信息详见附录 B
结果示例
ldquopathrdquo ldquo5AB0C6B33BD1162FE89D12134Erdquo
删除笔记
URL http[baseURL]ywsopennotedeletejson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
path 想要删除的笔记原路径 是 String
返回结果操作成功时 http 状态为 200无返回结果失败时 http 状态为
500并返回错误码和错误信息详见附录 B
附件操作 API
上传附件或图片
URLhttp[baseURL]ywsopenresourceuploadjson
请求方式POST
Content-Typemultipartform-data
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
file 上传的附件文件(包括附件的文
件名类型大小数据等)
是 Multipart File附件大
小限制 25M
返回结果操作成功时 http状态为 200对于图片返回该图片的链接 URL
对于普通附件服务器会为该附件生成一个图标文件因此返回结果包括该
附件对应的链接 URL以及图标的 URL失败时 http状态为 500并返回错误码
和错误信息详见附录 B
示例
图片附件
url httpbaseURLywsopenresource28d83f547f3055
普通附件
url httpbaseURLywsopenresource28d83f547f3055 附件 URL
src httpbaseURLywsopenresource297f2bd6fa2795 图标 URL
需要注意的是在附件上传完成后使用者应该紧接着更新对应的笔记否
则不被任何笔记引用的附件将被定期的空间回收所删除
下载附件图片图标
URLhttp[baseURL]ywsopenresourcedownload
请求方式GET
是否需要用户认证是 (关于登录授权参见请求用户授权)
返回结果操作成功时response返回附件及图片的二进制流失败时 http
状态为 500并返回错误码和错误信息详见附录 B
备注
1 当打开笔记时对于笔记中的附件及图片链接只需要添加用户的 OAuth
认证信息即可以获取对应的附件及图片同理在上传附件后返回的附
件及图片链接也可以通过这种方式进行访问
2 附件及图片的下载支持断点续传
附录 A有道云笔记内容格式
笔记内容的格式采用类 HTML的标记语言绝大部分格式相关 tag均采用标
准的 HTML Tag唯一需要不同的是附件及图片 Tag在格式上图片 Tag与标准的
img tag相同一个图片资源的标记如下
ltimg src=httpnoteyoudaocomywsopenresource227f2bd6fa2795441cgt
但是由于对应的接口需要用户认证因此在获取图片资源时需要加入 OAuth
的用户认证信息
附件通常以图标在笔记中进行显示因此我们扩展了图片 Tag ltimggt除了
img 本身的 src 属性额外加入了一个属性 path其中 src 对应着该附件的图标
URL而 path则为该附件的 URL如下所示
ltimg path=httpnoteyoudaocomywsopenresource219fe604c7c90642fd8f
src=httpnoteyoudaocomywsopenresource227f2bd6fa2795441cgt
同理也需要加入 OAuth的用户认证信息才可以正常访问附件资源及其图标
附录 B错误码及错误信息说明
同理当 Open API的请求在执行时出现任何异常或错误时系统将返回 Http
500应用程序可以根据此判断请求是否成功执行当应用程序在进行 OAuth认
证或者未经认证便调用 Open API时系统会返回 OAuth错误信息OAuth的
错误码与错误信息将以 json的格式进行返回各个错误码及错误信息说明如下
错误码 错误描述及可能原因
1001 token_rejectedconsumer没有找到consumerKey错误 consumer
没有创建或者 request token或者 access token 不存在于 server中
或者没有获得授权的 token或者 token过期
1002 parameter_rejected这个会返回具体原因 key是
oauth_parameters_rejected value是一个 parameter列表
1003 version_rejectedOAuth版本号不是 10
1004 timestamp_refusedtimestamp 非 5分钟内
1005 nonce_used5分钟内该 nonce被使用
1006 parameter_absent有些参数没有发送给 server
1007 signature_invalidoauth签名异常可能原因没有签名签名方法和
签名不一致等
1008 signature_method_rejectedoauth server没有提供该签名方法
1009 access_state_error获取 token时状态混乱详细的信息会告知当前的
状态 [AUTHORIZED | REQUEST | ACCESS | INVALID]
1010 consumer_rejected该 consumer在 server中不存在或者被禁掉
或者 consumerKey改变但是还没有反应到 server的数据库中
1011 accessor_rejected由 token得到的 accessor构造异常或者 accessor
中缺失某些属性或者转换失败
1012 callback_errorrequest token传来的 callback和以后的 callback不一致
1013 callback_domain_error当限定 callback后发来的 callback与原设置
的 callback的域不相同
1014 verifier_errorVerifier不一致错误
1015 permission_denied无授权的 token或者授权后没有获取过 access
token
同理当 Open API的请求在后台执行出现异常或错误时系统也将同时错
误码与错误信息以 json 的格式一同返回应用程序可以根据错误码得到相应的
原因常见的错误码说明如下
错误码 错误描述及可能原因
206 UNKNOWN_URI错误的 URI请求
207 AUTHENTICATION_FAILURE用户认证错误
209 RESOURCE_NOT_EXIST请求的资源(笔记本笔记附件等)不存在
210 USER_SPACE_FULL用户空间已满
214 INVALID_PARAMETER错误的传入参数必须的参数为空等
220 USER_NOT_EXISTS用户不存在
221 USER_ALREADY_EXISTS用户已经存在不能重复注册
225 PARENT_NOT_EXIST笔记本尚不存在不能在该笔记本下创建笔记
231 RESOURCE_ALREADY_EXIST该笔记或者附件已经存在不能重复创建
304 NOTE_ALREADY_DELETED笔记已经被删除
307 INVALID_APPLICATION无效的第三方应用未经过用户授权或者授权
失败便通过 OpenAPI访问用户数据这个一般是使用测试环境得到了
access_token利用该 access_token访问了线上环境这两套环境是独
立的Access_token不能共用
但是如果第三方应用未经过用户授权
示例当查看笔记路径错误时
error 209
message Required note does not exist path=5AB0C6B33BD12FE89D12134E
附录 C 访问 OAuth Server的类库与包
ActionScriptFlash
oauth-as3 httpcodegooglecompoauth-as3
A flex oauth client
httpwwwarcgiscomhomeitemhtmlid=ff6ffa302ad04a7194999f2ad08250d7
CC++
QTweetLib httpgithubcomminimoogQTweetLib
libOAuth httpliboauthsourceforgenet
clojure
clj-oauth httpgithubcommattreplclj-oauth
net
oauth-dot-net httpcodegooglecompoauth-dot-net
DotNetOpenAuth httpwwwdotnetopenauthnet
Erlang
erlang-oauth httpgithubcomtimerlang-oauth
java
Scrible httpgithubcomfernandezpablo85scribe-java
oauth-signpost httpcodegooglecompoauth-signpost
javascript
oauth in js httpoauthgooglecodecomsvncodejavascript
Objective-CCocoa amp iPhone programming
OAuthCore httpbitbucketorgatebitsoauthcore
MPOAuthConnection httpcodegooglecompmpoauthconnection
Objective-C OAuth httpoauthgooglecodecomsvncodeobj-c
Perl
NetOAuth httpoauthgooglecodecomsvncodeperl
PHP
tmhOAuth httpgithubcomthemattharristmhOAuth
oauth-php httpcodegooglecompoauth-php
Python
python-oauth2 httpgithubcombrosnerpython-oauth2
Qt
qOauth httpgithubcomayoyqoauth
Ruby
Oauth ruby gem httpoauthrubyforgeorg
Scala
DataBinder Dispatch httpdispatchdatabindernetAbout
附录 D Oauth签名加密 oauth_signature
1 加密内容是
a 请求方法名例如 GET POST等 加密时方法名大写并进行特殊替换
(详见 3)
b url (query param之前的部分不包括 )Http或者 https需要全部小
写 http如果带有 80端口或者 https带有 443端口需要将其省略
其他端口则不能省略例如
Httplocal9999requestToken
httplocal9999requestToken
Httplocal80requestToken
httplocalrequestToken
Httpslocal443requestToken
httpslocal requestToken
c 参数(query param中的或者 header中的 key-value对) 首先将这些参数
进行特殊替换后按字典序排序升序排列如果两个 key相同则以
value特殊替换后字典序为准key与 value之间使用rdquo=rdquo连接如果
value==null则使用rdquordquo替代两个参数对之间使用rdquoamprdquo连接连接后形成
的最终字符串的开头和结尾没有rdquoamprdquo
d 字典序字符串比较大小伪代码
Int compare(string a string b)
Int min_len = min(len(a) len(b))
For I to min_len
If (a[i] = b[i])
Return a[i] ndash b[i]
Return len(a) ndash len(b)
将以上 abc三部分进行特殊替换后使用amp连接最终形成的字符串的
开头和结尾都没有rdquoamprdquo这就是加密内容
2 加密的 key是 consumerSecret + amp + TokenSecret 如果 TokenSecret还没有
得到则使用rdquordquo consumerSecret和 TokenSecret需先做特殊替换然后
再进行签名
3 特殊替换是将 String进行 URL编码后将rdquo+rdquo替换为rdquo20rdquo将rdquordquo替换
为rdquo2Ardquo将rdquo7Erdquo替换为rdquo~rdquo
4 签名方法可以使用 HMAC-SHA1PLAINTEXT RSA_SHA1三种其中
PLAINTEXT为 2中的 key 该方法不提倡使用
得到签名内容后使用 Base64进行编码编码后的字符串即为 oauth_signature
本中创建该笔记
查看笔记
URL http[baseURL]ywsopennotegetjson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
path 笔记路径 是 String
返回结果操作成功时 http状态为 200并返回该笔记的相关信息失败时
http状态为 500并返回错误码和错误信息详见附录 B
结果示例
ldquotitlerdquo ldquo工作记录rdquo 笔记标题
ldquoauthorrdquo ldquoTomrdquo 笔记作者
ldquosourcerdquo ldquohttpnoteyoudaocomrdquo 笔记来源 URL
ldquosizerdquo ldquo1024rdquo 笔记大小包括笔记正文及附件
ldquocreate_timerdquo ldquo1323310917rdquo 笔记的创建时间单位秒
ldquomodify_timerdquo ldquo1323310949rdquo 笔记的最后修改时间单位秒
ldquocontentrdquo ldquoltpgtThis is a test noteltpgt 笔记正文
修改笔记
URL http[baseURL]ywsopennoteupdatejson
请求方式POST
Content-Typemultipartform-data
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
path 修改笔记的路径 是 String
source 修改后的笔记来源 URL 否 String
author 修改后的笔记作者 否 String
title 修改后的笔记标题 否 String
content 修改后的笔记正文(笔记格式见
附录 A)
是 String
返回结果操作成功时 http 状态为 200无返回结果失败时 http 状态为
500并返回错误码和错误信息详见附录 B
移动笔记
URL http[baseURL]ywsopennotemovejson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
path 想要移动的笔记原路径 是 String
notebook 目标笔记本的路径 是 String
返回结果操作成功时 http状态为 200返回移动后的笔记路径失败时 http
状态为 500并返回错误码和错误信息详见附录 B
结果示例
ldquopathrdquo ldquo5AB0C6B33BD1162FE89D12134Erdquo
删除笔记
URL http[baseURL]ywsopennotedeletejson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
path 想要删除的笔记原路径 是 String
返回结果操作成功时 http 状态为 200无返回结果失败时 http 状态为
500并返回错误码和错误信息详见附录 B
附件操作 API
上传附件或图片
URLhttp[baseURL]ywsopenresourceuploadjson
请求方式POST
Content-Typemultipartform-data
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
file 上传的附件文件(包括附件的文
件名类型大小数据等)
是 Multipart File附件大
小限制 25M
返回结果操作成功时 http状态为 200对于图片返回该图片的链接 URL
对于普通附件服务器会为该附件生成一个图标文件因此返回结果包括该
附件对应的链接 URL以及图标的 URL失败时 http状态为 500并返回错误码
和错误信息详见附录 B
示例
图片附件
url httpbaseURLywsopenresource28d83f547f3055
普通附件
url httpbaseURLywsopenresource28d83f547f3055 附件 URL
src httpbaseURLywsopenresource297f2bd6fa2795 图标 URL
需要注意的是在附件上传完成后使用者应该紧接着更新对应的笔记否
则不被任何笔记引用的附件将被定期的空间回收所删除
下载附件图片图标
URLhttp[baseURL]ywsopenresourcedownload
请求方式GET
是否需要用户认证是 (关于登录授权参见请求用户授权)
返回结果操作成功时response返回附件及图片的二进制流失败时 http
状态为 500并返回错误码和错误信息详见附录 B
备注
1 当打开笔记时对于笔记中的附件及图片链接只需要添加用户的 OAuth
认证信息即可以获取对应的附件及图片同理在上传附件后返回的附
件及图片链接也可以通过这种方式进行访问
2 附件及图片的下载支持断点续传
附录 A有道云笔记内容格式
笔记内容的格式采用类 HTML的标记语言绝大部分格式相关 tag均采用标
准的 HTML Tag唯一需要不同的是附件及图片 Tag在格式上图片 Tag与标准的
img tag相同一个图片资源的标记如下
ltimg src=httpnoteyoudaocomywsopenresource227f2bd6fa2795441cgt
但是由于对应的接口需要用户认证因此在获取图片资源时需要加入 OAuth
的用户认证信息
附件通常以图标在笔记中进行显示因此我们扩展了图片 Tag ltimggt除了
img 本身的 src 属性额外加入了一个属性 path其中 src 对应着该附件的图标
URL而 path则为该附件的 URL如下所示
ltimg path=httpnoteyoudaocomywsopenresource219fe604c7c90642fd8f
src=httpnoteyoudaocomywsopenresource227f2bd6fa2795441cgt
同理也需要加入 OAuth的用户认证信息才可以正常访问附件资源及其图标
附录 B错误码及错误信息说明
同理当 Open API的请求在执行时出现任何异常或错误时系统将返回 Http
500应用程序可以根据此判断请求是否成功执行当应用程序在进行 OAuth认
证或者未经认证便调用 Open API时系统会返回 OAuth错误信息OAuth的
错误码与错误信息将以 json的格式进行返回各个错误码及错误信息说明如下
错误码 错误描述及可能原因
1001 token_rejectedconsumer没有找到consumerKey错误 consumer
没有创建或者 request token或者 access token 不存在于 server中
或者没有获得授权的 token或者 token过期
1002 parameter_rejected这个会返回具体原因 key是
oauth_parameters_rejected value是一个 parameter列表
1003 version_rejectedOAuth版本号不是 10
1004 timestamp_refusedtimestamp 非 5分钟内
1005 nonce_used5分钟内该 nonce被使用
1006 parameter_absent有些参数没有发送给 server
1007 signature_invalidoauth签名异常可能原因没有签名签名方法和
签名不一致等
1008 signature_method_rejectedoauth server没有提供该签名方法
1009 access_state_error获取 token时状态混乱详细的信息会告知当前的
状态 [AUTHORIZED | REQUEST | ACCESS | INVALID]
1010 consumer_rejected该 consumer在 server中不存在或者被禁掉
或者 consumerKey改变但是还没有反应到 server的数据库中
1011 accessor_rejected由 token得到的 accessor构造异常或者 accessor
中缺失某些属性或者转换失败
1012 callback_errorrequest token传来的 callback和以后的 callback不一致
1013 callback_domain_error当限定 callback后发来的 callback与原设置
的 callback的域不相同
1014 verifier_errorVerifier不一致错误
1015 permission_denied无授权的 token或者授权后没有获取过 access
token
同理当 Open API的请求在后台执行出现异常或错误时系统也将同时错
误码与错误信息以 json 的格式一同返回应用程序可以根据错误码得到相应的
原因常见的错误码说明如下
错误码 错误描述及可能原因
206 UNKNOWN_URI错误的 URI请求
207 AUTHENTICATION_FAILURE用户认证错误
209 RESOURCE_NOT_EXIST请求的资源(笔记本笔记附件等)不存在
210 USER_SPACE_FULL用户空间已满
214 INVALID_PARAMETER错误的传入参数必须的参数为空等
220 USER_NOT_EXISTS用户不存在
221 USER_ALREADY_EXISTS用户已经存在不能重复注册
225 PARENT_NOT_EXIST笔记本尚不存在不能在该笔记本下创建笔记
231 RESOURCE_ALREADY_EXIST该笔记或者附件已经存在不能重复创建
304 NOTE_ALREADY_DELETED笔记已经被删除
307 INVALID_APPLICATION无效的第三方应用未经过用户授权或者授权
失败便通过 OpenAPI访问用户数据这个一般是使用测试环境得到了
access_token利用该 access_token访问了线上环境这两套环境是独
立的Access_token不能共用
但是如果第三方应用未经过用户授权
示例当查看笔记路径错误时
error 209
message Required note does not exist path=5AB0C6B33BD12FE89D12134E
附录 C 访问 OAuth Server的类库与包
ActionScriptFlash
oauth-as3 httpcodegooglecompoauth-as3
A flex oauth client
httpwwwarcgiscomhomeitemhtmlid=ff6ffa302ad04a7194999f2ad08250d7
CC++
QTweetLib httpgithubcomminimoogQTweetLib
libOAuth httpliboauthsourceforgenet
clojure
clj-oauth httpgithubcommattreplclj-oauth
net
oauth-dot-net httpcodegooglecompoauth-dot-net
DotNetOpenAuth httpwwwdotnetopenauthnet
Erlang
erlang-oauth httpgithubcomtimerlang-oauth
java
Scrible httpgithubcomfernandezpablo85scribe-java
oauth-signpost httpcodegooglecompoauth-signpost
javascript
oauth in js httpoauthgooglecodecomsvncodejavascript
Objective-CCocoa amp iPhone programming
OAuthCore httpbitbucketorgatebitsoauthcore
MPOAuthConnection httpcodegooglecompmpoauthconnection
Objective-C OAuth httpoauthgooglecodecomsvncodeobj-c
Perl
NetOAuth httpoauthgooglecodecomsvncodeperl
PHP
tmhOAuth httpgithubcomthemattharristmhOAuth
oauth-php httpcodegooglecompoauth-php
Python
python-oauth2 httpgithubcombrosnerpython-oauth2
Qt
qOauth httpgithubcomayoyqoauth
Ruby
Oauth ruby gem httpoauthrubyforgeorg
Scala
DataBinder Dispatch httpdispatchdatabindernetAbout
附录 D Oauth签名加密 oauth_signature
1 加密内容是
a 请求方法名例如 GET POST等 加密时方法名大写并进行特殊替换
(详见 3)
b url (query param之前的部分不包括 )Http或者 https需要全部小
写 http如果带有 80端口或者 https带有 443端口需要将其省略
其他端口则不能省略例如
Httplocal9999requestToken
httplocal9999requestToken
Httplocal80requestToken
httplocalrequestToken
Httpslocal443requestToken
httpslocal requestToken
c 参数(query param中的或者 header中的 key-value对) 首先将这些参数
进行特殊替换后按字典序排序升序排列如果两个 key相同则以
value特殊替换后字典序为准key与 value之间使用rdquo=rdquo连接如果
value==null则使用rdquordquo替代两个参数对之间使用rdquoamprdquo连接连接后形成
的最终字符串的开头和结尾没有rdquoamprdquo
d 字典序字符串比较大小伪代码
Int compare(string a string b)
Int min_len = min(len(a) len(b))
For I to min_len
If (a[i] = b[i])
Return a[i] ndash b[i]
Return len(a) ndash len(b)
将以上 abc三部分进行特殊替换后使用amp连接最终形成的字符串的
开头和结尾都没有rdquoamprdquo这就是加密内容
2 加密的 key是 consumerSecret + amp + TokenSecret 如果 TokenSecret还没有
得到则使用rdquordquo consumerSecret和 TokenSecret需先做特殊替换然后
再进行签名
3 特殊替换是将 String进行 URL编码后将rdquo+rdquo替换为rdquo20rdquo将rdquordquo替换
为rdquo2Ardquo将rdquo7Erdquo替换为rdquo~rdquo
4 签名方法可以使用 HMAC-SHA1PLAINTEXT RSA_SHA1三种其中
PLAINTEXT为 2中的 key 该方法不提倡使用
得到签名内容后使用 Base64进行编码编码后的字符串即为 oauth_signature
source 修改后的笔记来源 URL 否 String
author 修改后的笔记作者 否 String
title 修改后的笔记标题 否 String
content 修改后的笔记正文(笔记格式见
附录 A)
是 String
返回结果操作成功时 http 状态为 200无返回结果失败时 http 状态为
500并返回错误码和错误信息详见附录 B
移动笔记
URL http[baseURL]ywsopennotemovejson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
path 想要移动的笔记原路径 是 String
notebook 目标笔记本的路径 是 String
返回结果操作成功时 http状态为 200返回移动后的笔记路径失败时 http
状态为 500并返回错误码和错误信息详见附录 B
结果示例
ldquopathrdquo ldquo5AB0C6B33BD1162FE89D12134Erdquo
删除笔记
URL http[baseURL]ywsopennotedeletejson
请求方式POST
Content-Typeapplicationx-www-form-urlencoded
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
path 想要删除的笔记原路径 是 String
返回结果操作成功时 http 状态为 200无返回结果失败时 http 状态为
500并返回错误码和错误信息详见附录 B
附件操作 API
上传附件或图片
URLhttp[baseURL]ywsopenresourceuploadjson
请求方式POST
Content-Typemultipartform-data
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
file 上传的附件文件(包括附件的文
件名类型大小数据等)
是 Multipart File附件大
小限制 25M
返回结果操作成功时 http状态为 200对于图片返回该图片的链接 URL
对于普通附件服务器会为该附件生成一个图标文件因此返回结果包括该
附件对应的链接 URL以及图标的 URL失败时 http状态为 500并返回错误码
和错误信息详见附录 B
示例
图片附件
url httpbaseURLywsopenresource28d83f547f3055
普通附件
url httpbaseURLywsopenresource28d83f547f3055 附件 URL
src httpbaseURLywsopenresource297f2bd6fa2795 图标 URL
需要注意的是在附件上传完成后使用者应该紧接着更新对应的笔记否
则不被任何笔记引用的附件将被定期的空间回收所删除
下载附件图片图标
URLhttp[baseURL]ywsopenresourcedownload
请求方式GET
是否需要用户认证是 (关于登录授权参见请求用户授权)
返回结果操作成功时response返回附件及图片的二进制流失败时 http
状态为 500并返回错误码和错误信息详见附录 B
备注
1 当打开笔记时对于笔记中的附件及图片链接只需要添加用户的 OAuth
认证信息即可以获取对应的附件及图片同理在上传附件后返回的附
件及图片链接也可以通过这种方式进行访问
2 附件及图片的下载支持断点续传
附录 A有道云笔记内容格式
笔记内容的格式采用类 HTML的标记语言绝大部分格式相关 tag均采用标
准的 HTML Tag唯一需要不同的是附件及图片 Tag在格式上图片 Tag与标准的
img tag相同一个图片资源的标记如下
ltimg src=httpnoteyoudaocomywsopenresource227f2bd6fa2795441cgt
但是由于对应的接口需要用户认证因此在获取图片资源时需要加入 OAuth
的用户认证信息
附件通常以图标在笔记中进行显示因此我们扩展了图片 Tag ltimggt除了
img 本身的 src 属性额外加入了一个属性 path其中 src 对应着该附件的图标
URL而 path则为该附件的 URL如下所示
ltimg path=httpnoteyoudaocomywsopenresource219fe604c7c90642fd8f
src=httpnoteyoudaocomywsopenresource227f2bd6fa2795441cgt
同理也需要加入 OAuth的用户认证信息才可以正常访问附件资源及其图标
附录 B错误码及错误信息说明
同理当 Open API的请求在执行时出现任何异常或错误时系统将返回 Http
500应用程序可以根据此判断请求是否成功执行当应用程序在进行 OAuth认
证或者未经认证便调用 Open API时系统会返回 OAuth错误信息OAuth的
错误码与错误信息将以 json的格式进行返回各个错误码及错误信息说明如下
错误码 错误描述及可能原因
1001 token_rejectedconsumer没有找到consumerKey错误 consumer
没有创建或者 request token或者 access token 不存在于 server中
或者没有获得授权的 token或者 token过期
1002 parameter_rejected这个会返回具体原因 key是
oauth_parameters_rejected value是一个 parameter列表
1003 version_rejectedOAuth版本号不是 10
1004 timestamp_refusedtimestamp 非 5分钟内
1005 nonce_used5分钟内该 nonce被使用
1006 parameter_absent有些参数没有发送给 server
1007 signature_invalidoauth签名异常可能原因没有签名签名方法和
签名不一致等
1008 signature_method_rejectedoauth server没有提供该签名方法
1009 access_state_error获取 token时状态混乱详细的信息会告知当前的
状态 [AUTHORIZED | REQUEST | ACCESS | INVALID]
1010 consumer_rejected该 consumer在 server中不存在或者被禁掉
或者 consumerKey改变但是还没有反应到 server的数据库中
1011 accessor_rejected由 token得到的 accessor构造异常或者 accessor
中缺失某些属性或者转换失败
1012 callback_errorrequest token传来的 callback和以后的 callback不一致
1013 callback_domain_error当限定 callback后发来的 callback与原设置
的 callback的域不相同
1014 verifier_errorVerifier不一致错误
1015 permission_denied无授权的 token或者授权后没有获取过 access
token
同理当 Open API的请求在后台执行出现异常或错误时系统也将同时错
误码与错误信息以 json 的格式一同返回应用程序可以根据错误码得到相应的
原因常见的错误码说明如下
错误码 错误描述及可能原因
206 UNKNOWN_URI错误的 URI请求
207 AUTHENTICATION_FAILURE用户认证错误
209 RESOURCE_NOT_EXIST请求的资源(笔记本笔记附件等)不存在
210 USER_SPACE_FULL用户空间已满
214 INVALID_PARAMETER错误的传入参数必须的参数为空等
220 USER_NOT_EXISTS用户不存在
221 USER_ALREADY_EXISTS用户已经存在不能重复注册
225 PARENT_NOT_EXIST笔记本尚不存在不能在该笔记本下创建笔记
231 RESOURCE_ALREADY_EXIST该笔记或者附件已经存在不能重复创建
304 NOTE_ALREADY_DELETED笔记已经被删除
307 INVALID_APPLICATION无效的第三方应用未经过用户授权或者授权
失败便通过 OpenAPI访问用户数据这个一般是使用测试环境得到了
access_token利用该 access_token访问了线上环境这两套环境是独
立的Access_token不能共用
但是如果第三方应用未经过用户授权
示例当查看笔记路径错误时
error 209
message Required note does not exist path=5AB0C6B33BD12FE89D12134E
附录 C 访问 OAuth Server的类库与包
ActionScriptFlash
oauth-as3 httpcodegooglecompoauth-as3
A flex oauth client
httpwwwarcgiscomhomeitemhtmlid=ff6ffa302ad04a7194999f2ad08250d7
CC++
QTweetLib httpgithubcomminimoogQTweetLib
libOAuth httpliboauthsourceforgenet
clojure
clj-oauth httpgithubcommattreplclj-oauth
net
oauth-dot-net httpcodegooglecompoauth-dot-net
DotNetOpenAuth httpwwwdotnetopenauthnet
Erlang
erlang-oauth httpgithubcomtimerlang-oauth
java
Scrible httpgithubcomfernandezpablo85scribe-java
oauth-signpost httpcodegooglecompoauth-signpost
javascript
oauth in js httpoauthgooglecodecomsvncodejavascript
Objective-CCocoa amp iPhone programming
OAuthCore httpbitbucketorgatebitsoauthcore
MPOAuthConnection httpcodegooglecompmpoauthconnection
Objective-C OAuth httpoauthgooglecodecomsvncodeobj-c
Perl
NetOAuth httpoauthgooglecodecomsvncodeperl
PHP
tmhOAuth httpgithubcomthemattharristmhOAuth
oauth-php httpcodegooglecompoauth-php
Python
python-oauth2 httpgithubcombrosnerpython-oauth2
Qt
qOauth httpgithubcomayoyqoauth
Ruby
Oauth ruby gem httpoauthrubyforgeorg
Scala
DataBinder Dispatch httpdispatchdatabindernetAbout
附录 D Oauth签名加密 oauth_signature
1 加密内容是
a 请求方法名例如 GET POST等 加密时方法名大写并进行特殊替换
(详见 3)
b url (query param之前的部分不包括 )Http或者 https需要全部小
写 http如果带有 80端口或者 https带有 443端口需要将其省略
其他端口则不能省略例如
Httplocal9999requestToken
httplocal9999requestToken
Httplocal80requestToken
httplocalrequestToken
Httpslocal443requestToken
httpslocal requestToken
c 参数(query param中的或者 header中的 key-value对) 首先将这些参数
进行特殊替换后按字典序排序升序排列如果两个 key相同则以
value特殊替换后字典序为准key与 value之间使用rdquo=rdquo连接如果
value==null则使用rdquordquo替代两个参数对之间使用rdquoamprdquo连接连接后形成
的最终字符串的开头和结尾没有rdquoamprdquo
d 字典序字符串比较大小伪代码
Int compare(string a string b)
Int min_len = min(len(a) len(b))
For I to min_len
If (a[i] = b[i])
Return a[i] ndash b[i]
Return len(a) ndash len(b)
将以上 abc三部分进行特殊替换后使用amp连接最终形成的字符串的
开头和结尾都没有rdquoamprdquo这就是加密内容
2 加密的 key是 consumerSecret + amp + TokenSecret 如果 TokenSecret还没有
得到则使用rdquordquo consumerSecret和 TokenSecret需先做特殊替换然后
再进行签名
3 特殊替换是将 String进行 URL编码后将rdquo+rdquo替换为rdquo20rdquo将rdquordquo替换
为rdquo2Ardquo将rdquo7Erdquo替换为rdquo~rdquo
4 签名方法可以使用 HMAC-SHA1PLAINTEXT RSA_SHA1三种其中
PLAINTEXT为 2中的 key 该方法不提倡使用
得到签名内容后使用 Base64进行编码编码后的字符串即为 oauth_signature
500并返回错误码和错误信息详见附录 B
附件操作 API
上传附件或图片
URLhttp[baseURL]ywsopenresourceuploadjson
请求方式POST
Content-Typemultipartform-data
支持格式JSON
是否需要用户认证是 (关于登录授权参见请求用户授权)
请求参数
参数名 参数说明 是否必须 数据类型限制
file 上传的附件文件(包括附件的文
件名类型大小数据等)
是 Multipart File附件大
小限制 25M
返回结果操作成功时 http状态为 200对于图片返回该图片的链接 URL
对于普通附件服务器会为该附件生成一个图标文件因此返回结果包括该
附件对应的链接 URL以及图标的 URL失败时 http状态为 500并返回错误码
和错误信息详见附录 B
示例
图片附件
url httpbaseURLywsopenresource28d83f547f3055
普通附件
url httpbaseURLywsopenresource28d83f547f3055 附件 URL
src httpbaseURLywsopenresource297f2bd6fa2795 图标 URL
需要注意的是在附件上传完成后使用者应该紧接着更新对应的笔记否
则不被任何笔记引用的附件将被定期的空间回收所删除
下载附件图片图标
URLhttp[baseURL]ywsopenresourcedownload
请求方式GET
是否需要用户认证是 (关于登录授权参见请求用户授权)
返回结果操作成功时response返回附件及图片的二进制流失败时 http
状态为 500并返回错误码和错误信息详见附录 B
备注
1 当打开笔记时对于笔记中的附件及图片链接只需要添加用户的 OAuth
认证信息即可以获取对应的附件及图片同理在上传附件后返回的附
件及图片链接也可以通过这种方式进行访问
2 附件及图片的下载支持断点续传
附录 A有道云笔记内容格式
笔记内容的格式采用类 HTML的标记语言绝大部分格式相关 tag均采用标
准的 HTML Tag唯一需要不同的是附件及图片 Tag在格式上图片 Tag与标准的
img tag相同一个图片资源的标记如下
ltimg src=httpnoteyoudaocomywsopenresource227f2bd6fa2795441cgt
但是由于对应的接口需要用户认证因此在获取图片资源时需要加入 OAuth
的用户认证信息
附件通常以图标在笔记中进行显示因此我们扩展了图片 Tag ltimggt除了
img 本身的 src 属性额外加入了一个属性 path其中 src 对应着该附件的图标
URL而 path则为该附件的 URL如下所示
ltimg path=httpnoteyoudaocomywsopenresource219fe604c7c90642fd8f
src=httpnoteyoudaocomywsopenresource227f2bd6fa2795441cgt
同理也需要加入 OAuth的用户认证信息才可以正常访问附件资源及其图标
附录 B错误码及错误信息说明
同理当 Open API的请求在执行时出现任何异常或错误时系统将返回 Http
500应用程序可以根据此判断请求是否成功执行当应用程序在进行 OAuth认
证或者未经认证便调用 Open API时系统会返回 OAuth错误信息OAuth的
错误码与错误信息将以 json的格式进行返回各个错误码及错误信息说明如下
错误码 错误描述及可能原因
1001 token_rejectedconsumer没有找到consumerKey错误 consumer
没有创建或者 request token或者 access token 不存在于 server中
或者没有获得授权的 token或者 token过期
1002 parameter_rejected这个会返回具体原因 key是
oauth_parameters_rejected value是一个 parameter列表
1003 version_rejectedOAuth版本号不是 10
1004 timestamp_refusedtimestamp 非 5分钟内
1005 nonce_used5分钟内该 nonce被使用
1006 parameter_absent有些参数没有发送给 server
1007 signature_invalidoauth签名异常可能原因没有签名签名方法和
签名不一致等
1008 signature_method_rejectedoauth server没有提供该签名方法
1009 access_state_error获取 token时状态混乱详细的信息会告知当前的
状态 [AUTHORIZED | REQUEST | ACCESS | INVALID]
1010 consumer_rejected该 consumer在 server中不存在或者被禁掉
或者 consumerKey改变但是还没有反应到 server的数据库中
1011 accessor_rejected由 token得到的 accessor构造异常或者 accessor
中缺失某些属性或者转换失败
1012 callback_errorrequest token传来的 callback和以后的 callback不一致
1013 callback_domain_error当限定 callback后发来的 callback与原设置
的 callback的域不相同
1014 verifier_errorVerifier不一致错误
1015 permission_denied无授权的 token或者授权后没有获取过 access
token
同理当 Open API的请求在后台执行出现异常或错误时系统也将同时错
误码与错误信息以 json 的格式一同返回应用程序可以根据错误码得到相应的
原因常见的错误码说明如下
错误码 错误描述及可能原因
206 UNKNOWN_URI错误的 URI请求
207 AUTHENTICATION_FAILURE用户认证错误
209 RESOURCE_NOT_EXIST请求的资源(笔记本笔记附件等)不存在
210 USER_SPACE_FULL用户空间已满
214 INVALID_PARAMETER错误的传入参数必须的参数为空等
220 USER_NOT_EXISTS用户不存在
221 USER_ALREADY_EXISTS用户已经存在不能重复注册
225 PARENT_NOT_EXIST笔记本尚不存在不能在该笔记本下创建笔记
231 RESOURCE_ALREADY_EXIST该笔记或者附件已经存在不能重复创建
304 NOTE_ALREADY_DELETED笔记已经被删除
307 INVALID_APPLICATION无效的第三方应用未经过用户授权或者授权
失败便通过 OpenAPI访问用户数据这个一般是使用测试环境得到了
access_token利用该 access_token访问了线上环境这两套环境是独
立的Access_token不能共用
但是如果第三方应用未经过用户授权
示例当查看笔记路径错误时
error 209
message Required note does not exist path=5AB0C6B33BD12FE89D12134E
附录 C 访问 OAuth Server的类库与包
ActionScriptFlash
oauth-as3 httpcodegooglecompoauth-as3
A flex oauth client
httpwwwarcgiscomhomeitemhtmlid=ff6ffa302ad04a7194999f2ad08250d7
CC++
QTweetLib httpgithubcomminimoogQTweetLib
libOAuth httpliboauthsourceforgenet
clojure
clj-oauth httpgithubcommattreplclj-oauth
net
oauth-dot-net httpcodegooglecompoauth-dot-net
DotNetOpenAuth httpwwwdotnetopenauthnet
Erlang
erlang-oauth httpgithubcomtimerlang-oauth
java
Scrible httpgithubcomfernandezpablo85scribe-java
oauth-signpost httpcodegooglecompoauth-signpost
javascript
oauth in js httpoauthgooglecodecomsvncodejavascript
Objective-CCocoa amp iPhone programming
OAuthCore httpbitbucketorgatebitsoauthcore
MPOAuthConnection httpcodegooglecompmpoauthconnection
Objective-C OAuth httpoauthgooglecodecomsvncodeobj-c
Perl
NetOAuth httpoauthgooglecodecomsvncodeperl
PHP
tmhOAuth httpgithubcomthemattharristmhOAuth
oauth-php httpcodegooglecompoauth-php
Python
python-oauth2 httpgithubcombrosnerpython-oauth2
Qt
qOauth httpgithubcomayoyqoauth
Ruby
Oauth ruby gem httpoauthrubyforgeorg
Scala
DataBinder Dispatch httpdispatchdatabindernetAbout
附录 D Oauth签名加密 oauth_signature
1 加密内容是
a 请求方法名例如 GET POST等 加密时方法名大写并进行特殊替换
(详见 3)
b url (query param之前的部分不包括 )Http或者 https需要全部小
写 http如果带有 80端口或者 https带有 443端口需要将其省略
其他端口则不能省略例如
Httplocal9999requestToken
httplocal9999requestToken
Httplocal80requestToken
httplocalrequestToken
Httpslocal443requestToken
httpslocal requestToken
c 参数(query param中的或者 header中的 key-value对) 首先将这些参数
进行特殊替换后按字典序排序升序排列如果两个 key相同则以
value特殊替换后字典序为准key与 value之间使用rdquo=rdquo连接如果
value==null则使用rdquordquo替代两个参数对之间使用rdquoamprdquo连接连接后形成
的最终字符串的开头和结尾没有rdquoamprdquo
d 字典序字符串比较大小伪代码
Int compare(string a string b)
Int min_len = min(len(a) len(b))
For I to min_len
If (a[i] = b[i])
Return a[i] ndash b[i]
Return len(a) ndash len(b)
将以上 abc三部分进行特殊替换后使用amp连接最终形成的字符串的
开头和结尾都没有rdquoamprdquo这就是加密内容
2 加密的 key是 consumerSecret + amp + TokenSecret 如果 TokenSecret还没有
得到则使用rdquordquo consumerSecret和 TokenSecret需先做特殊替换然后
再进行签名
3 特殊替换是将 String进行 URL编码后将rdquo+rdquo替换为rdquo20rdquo将rdquordquo替换
为rdquo2Ardquo将rdquo7Erdquo替换为rdquo~rdquo
4 签名方法可以使用 HMAC-SHA1PLAINTEXT RSA_SHA1三种其中
PLAINTEXT为 2中的 key 该方法不提倡使用
得到签名内容后使用 Base64进行编码编码后的字符串即为 oauth_signature
是否需要用户认证是 (关于登录授权参见请求用户授权)
返回结果操作成功时response返回附件及图片的二进制流失败时 http
状态为 500并返回错误码和错误信息详见附录 B
备注
1 当打开笔记时对于笔记中的附件及图片链接只需要添加用户的 OAuth
认证信息即可以获取对应的附件及图片同理在上传附件后返回的附
件及图片链接也可以通过这种方式进行访问
2 附件及图片的下载支持断点续传
附录 A有道云笔记内容格式
笔记内容的格式采用类 HTML的标记语言绝大部分格式相关 tag均采用标
准的 HTML Tag唯一需要不同的是附件及图片 Tag在格式上图片 Tag与标准的
img tag相同一个图片资源的标记如下
ltimg src=httpnoteyoudaocomywsopenresource227f2bd6fa2795441cgt
但是由于对应的接口需要用户认证因此在获取图片资源时需要加入 OAuth
的用户认证信息
附件通常以图标在笔记中进行显示因此我们扩展了图片 Tag ltimggt除了
img 本身的 src 属性额外加入了一个属性 path其中 src 对应着该附件的图标
URL而 path则为该附件的 URL如下所示
ltimg path=httpnoteyoudaocomywsopenresource219fe604c7c90642fd8f
src=httpnoteyoudaocomywsopenresource227f2bd6fa2795441cgt
同理也需要加入 OAuth的用户认证信息才可以正常访问附件资源及其图标
附录 B错误码及错误信息说明
同理当 Open API的请求在执行时出现任何异常或错误时系统将返回 Http
500应用程序可以根据此判断请求是否成功执行当应用程序在进行 OAuth认
证或者未经认证便调用 Open API时系统会返回 OAuth错误信息OAuth的
错误码与错误信息将以 json的格式进行返回各个错误码及错误信息说明如下
错误码 错误描述及可能原因
1001 token_rejectedconsumer没有找到consumerKey错误 consumer
没有创建或者 request token或者 access token 不存在于 server中
或者没有获得授权的 token或者 token过期
1002 parameter_rejected这个会返回具体原因 key是
oauth_parameters_rejected value是一个 parameter列表
1003 version_rejectedOAuth版本号不是 10
1004 timestamp_refusedtimestamp 非 5分钟内
1005 nonce_used5分钟内该 nonce被使用
1006 parameter_absent有些参数没有发送给 server
1007 signature_invalidoauth签名异常可能原因没有签名签名方法和
签名不一致等
1008 signature_method_rejectedoauth server没有提供该签名方法
1009 access_state_error获取 token时状态混乱详细的信息会告知当前的
状态 [AUTHORIZED | REQUEST | ACCESS | INVALID]
1010 consumer_rejected该 consumer在 server中不存在或者被禁掉
或者 consumerKey改变但是还没有反应到 server的数据库中
1011 accessor_rejected由 token得到的 accessor构造异常或者 accessor
中缺失某些属性或者转换失败
1012 callback_errorrequest token传来的 callback和以后的 callback不一致
1013 callback_domain_error当限定 callback后发来的 callback与原设置
的 callback的域不相同
1014 verifier_errorVerifier不一致错误
1015 permission_denied无授权的 token或者授权后没有获取过 access
token
同理当 Open API的请求在后台执行出现异常或错误时系统也将同时错
误码与错误信息以 json 的格式一同返回应用程序可以根据错误码得到相应的
原因常见的错误码说明如下
错误码 错误描述及可能原因
206 UNKNOWN_URI错误的 URI请求
207 AUTHENTICATION_FAILURE用户认证错误
209 RESOURCE_NOT_EXIST请求的资源(笔记本笔记附件等)不存在
210 USER_SPACE_FULL用户空间已满
214 INVALID_PARAMETER错误的传入参数必须的参数为空等
220 USER_NOT_EXISTS用户不存在
221 USER_ALREADY_EXISTS用户已经存在不能重复注册
225 PARENT_NOT_EXIST笔记本尚不存在不能在该笔记本下创建笔记
231 RESOURCE_ALREADY_EXIST该笔记或者附件已经存在不能重复创建
304 NOTE_ALREADY_DELETED笔记已经被删除
307 INVALID_APPLICATION无效的第三方应用未经过用户授权或者授权
失败便通过 OpenAPI访问用户数据这个一般是使用测试环境得到了
access_token利用该 access_token访问了线上环境这两套环境是独
立的Access_token不能共用
但是如果第三方应用未经过用户授权
示例当查看笔记路径错误时
error 209
message Required note does not exist path=5AB0C6B33BD12FE89D12134E
附录 C 访问 OAuth Server的类库与包
ActionScriptFlash
oauth-as3 httpcodegooglecompoauth-as3
A flex oauth client
httpwwwarcgiscomhomeitemhtmlid=ff6ffa302ad04a7194999f2ad08250d7
CC++
QTweetLib httpgithubcomminimoogQTweetLib
libOAuth httpliboauthsourceforgenet
clojure
clj-oauth httpgithubcommattreplclj-oauth
net
oauth-dot-net httpcodegooglecompoauth-dot-net
DotNetOpenAuth httpwwwdotnetopenauthnet
Erlang
erlang-oauth httpgithubcomtimerlang-oauth
java
Scrible httpgithubcomfernandezpablo85scribe-java
oauth-signpost httpcodegooglecompoauth-signpost
javascript
oauth in js httpoauthgooglecodecomsvncodejavascript
Objective-CCocoa amp iPhone programming
OAuthCore httpbitbucketorgatebitsoauthcore
MPOAuthConnection httpcodegooglecompmpoauthconnection
Objective-C OAuth httpoauthgooglecodecomsvncodeobj-c
Perl
NetOAuth httpoauthgooglecodecomsvncodeperl
PHP
tmhOAuth httpgithubcomthemattharristmhOAuth
oauth-php httpcodegooglecompoauth-php
Python
python-oauth2 httpgithubcombrosnerpython-oauth2
Qt
qOauth httpgithubcomayoyqoauth
Ruby
Oauth ruby gem httpoauthrubyforgeorg
Scala
DataBinder Dispatch httpdispatchdatabindernetAbout
附录 D Oauth签名加密 oauth_signature
1 加密内容是
a 请求方法名例如 GET POST等 加密时方法名大写并进行特殊替换
(详见 3)
b url (query param之前的部分不包括 )Http或者 https需要全部小
写 http如果带有 80端口或者 https带有 443端口需要将其省略
其他端口则不能省略例如
Httplocal9999requestToken
httplocal9999requestToken
Httplocal80requestToken
httplocalrequestToken
Httpslocal443requestToken
httpslocal requestToken
c 参数(query param中的或者 header中的 key-value对) 首先将这些参数
进行特殊替换后按字典序排序升序排列如果两个 key相同则以
value特殊替换后字典序为准key与 value之间使用rdquo=rdquo连接如果
value==null则使用rdquordquo替代两个参数对之间使用rdquoamprdquo连接连接后形成
的最终字符串的开头和结尾没有rdquoamprdquo
d 字典序字符串比较大小伪代码
Int compare(string a string b)
Int min_len = min(len(a) len(b))
For I to min_len
If (a[i] = b[i])
Return a[i] ndash b[i]
Return len(a) ndash len(b)
将以上 abc三部分进行特殊替换后使用amp连接最终形成的字符串的
开头和结尾都没有rdquoamprdquo这就是加密内容
2 加密的 key是 consumerSecret + amp + TokenSecret 如果 TokenSecret还没有
得到则使用rdquordquo consumerSecret和 TokenSecret需先做特殊替换然后
再进行签名
3 特殊替换是将 String进行 URL编码后将rdquo+rdquo替换为rdquo20rdquo将rdquordquo替换
为rdquo2Ardquo将rdquo7Erdquo替换为rdquo~rdquo
4 签名方法可以使用 HMAC-SHA1PLAINTEXT RSA_SHA1三种其中
PLAINTEXT为 2中的 key 该方法不提倡使用
得到签名内容后使用 Base64进行编码编码后的字符串即为 oauth_signature
或者没有获得授权的 token或者 token过期
1002 parameter_rejected这个会返回具体原因 key是
oauth_parameters_rejected value是一个 parameter列表
1003 version_rejectedOAuth版本号不是 10
1004 timestamp_refusedtimestamp 非 5分钟内
1005 nonce_used5分钟内该 nonce被使用
1006 parameter_absent有些参数没有发送给 server
1007 signature_invalidoauth签名异常可能原因没有签名签名方法和
签名不一致等
1008 signature_method_rejectedoauth server没有提供该签名方法
1009 access_state_error获取 token时状态混乱详细的信息会告知当前的
状态 [AUTHORIZED | REQUEST | ACCESS | INVALID]
1010 consumer_rejected该 consumer在 server中不存在或者被禁掉
或者 consumerKey改变但是还没有反应到 server的数据库中
1011 accessor_rejected由 token得到的 accessor构造异常或者 accessor
中缺失某些属性或者转换失败
1012 callback_errorrequest token传来的 callback和以后的 callback不一致
1013 callback_domain_error当限定 callback后发来的 callback与原设置
的 callback的域不相同
1014 verifier_errorVerifier不一致错误
1015 permission_denied无授权的 token或者授权后没有获取过 access
token
同理当 Open API的请求在后台执行出现异常或错误时系统也将同时错
误码与错误信息以 json 的格式一同返回应用程序可以根据错误码得到相应的
原因常见的错误码说明如下
错误码 错误描述及可能原因
206 UNKNOWN_URI错误的 URI请求
207 AUTHENTICATION_FAILURE用户认证错误
209 RESOURCE_NOT_EXIST请求的资源(笔记本笔记附件等)不存在
210 USER_SPACE_FULL用户空间已满
214 INVALID_PARAMETER错误的传入参数必须的参数为空等
220 USER_NOT_EXISTS用户不存在
221 USER_ALREADY_EXISTS用户已经存在不能重复注册
225 PARENT_NOT_EXIST笔记本尚不存在不能在该笔记本下创建笔记
231 RESOURCE_ALREADY_EXIST该笔记或者附件已经存在不能重复创建
304 NOTE_ALREADY_DELETED笔记已经被删除
307 INVALID_APPLICATION无效的第三方应用未经过用户授权或者授权
失败便通过 OpenAPI访问用户数据这个一般是使用测试环境得到了
access_token利用该 access_token访问了线上环境这两套环境是独
立的Access_token不能共用
但是如果第三方应用未经过用户授权
示例当查看笔记路径错误时
error 209
message Required note does not exist path=5AB0C6B33BD12FE89D12134E
附录 C 访问 OAuth Server的类库与包
ActionScriptFlash
oauth-as3 httpcodegooglecompoauth-as3
A flex oauth client
httpwwwarcgiscomhomeitemhtmlid=ff6ffa302ad04a7194999f2ad08250d7
CC++
QTweetLib httpgithubcomminimoogQTweetLib
libOAuth httpliboauthsourceforgenet
clojure
clj-oauth httpgithubcommattreplclj-oauth
net
oauth-dot-net httpcodegooglecompoauth-dot-net
DotNetOpenAuth httpwwwdotnetopenauthnet
Erlang
erlang-oauth httpgithubcomtimerlang-oauth
java
Scrible httpgithubcomfernandezpablo85scribe-java
oauth-signpost httpcodegooglecompoauth-signpost
javascript
oauth in js httpoauthgooglecodecomsvncodejavascript
Objective-CCocoa amp iPhone programming
OAuthCore httpbitbucketorgatebitsoauthcore
MPOAuthConnection httpcodegooglecompmpoauthconnection
Objective-C OAuth httpoauthgooglecodecomsvncodeobj-c
Perl
NetOAuth httpoauthgooglecodecomsvncodeperl
PHP
tmhOAuth httpgithubcomthemattharristmhOAuth
oauth-php httpcodegooglecompoauth-php
Python
python-oauth2 httpgithubcombrosnerpython-oauth2
Qt
qOauth httpgithubcomayoyqoauth
Ruby
Oauth ruby gem httpoauthrubyforgeorg
Scala
DataBinder Dispatch httpdispatchdatabindernetAbout
附录 D Oauth签名加密 oauth_signature
1 加密内容是
a 请求方法名例如 GET POST等 加密时方法名大写并进行特殊替换
(详见 3)
b url (query param之前的部分不包括 )Http或者 https需要全部小
写 http如果带有 80端口或者 https带有 443端口需要将其省略
其他端口则不能省略例如
Httplocal9999requestToken
httplocal9999requestToken
Httplocal80requestToken
httplocalrequestToken
Httpslocal443requestToken
httpslocal requestToken
c 参数(query param中的或者 header中的 key-value对) 首先将这些参数
进行特殊替换后按字典序排序升序排列如果两个 key相同则以
value特殊替换后字典序为准key与 value之间使用rdquo=rdquo连接如果
value==null则使用rdquordquo替代两个参数对之间使用rdquoamprdquo连接连接后形成
的最终字符串的开头和结尾没有rdquoamprdquo
d 字典序字符串比较大小伪代码
Int compare(string a string b)
Int min_len = min(len(a) len(b))
For I to min_len
If (a[i] = b[i])
Return a[i] ndash b[i]
Return len(a) ndash len(b)
将以上 abc三部分进行特殊替换后使用amp连接最终形成的字符串的
开头和结尾都没有rdquoamprdquo这就是加密内容
2 加密的 key是 consumerSecret + amp + TokenSecret 如果 TokenSecret还没有
得到则使用rdquordquo consumerSecret和 TokenSecret需先做特殊替换然后
再进行签名
3 特殊替换是将 String进行 URL编码后将rdquo+rdquo替换为rdquo20rdquo将rdquordquo替换
为rdquo2Ardquo将rdquo7Erdquo替换为rdquo~rdquo
4 签名方法可以使用 HMAC-SHA1PLAINTEXT RSA_SHA1三种其中
PLAINTEXT为 2中的 key 该方法不提倡使用
得到签名内容后使用 Base64进行编码编码后的字符串即为 oauth_signature
304 NOTE_ALREADY_DELETED笔记已经被删除
307 INVALID_APPLICATION无效的第三方应用未经过用户授权或者授权
失败便通过 OpenAPI访问用户数据这个一般是使用测试环境得到了
access_token利用该 access_token访问了线上环境这两套环境是独
立的Access_token不能共用
但是如果第三方应用未经过用户授权
示例当查看笔记路径错误时
error 209
message Required note does not exist path=5AB0C6B33BD12FE89D12134E
附录 C 访问 OAuth Server的类库与包
ActionScriptFlash
oauth-as3 httpcodegooglecompoauth-as3
A flex oauth client
httpwwwarcgiscomhomeitemhtmlid=ff6ffa302ad04a7194999f2ad08250d7
CC++
QTweetLib httpgithubcomminimoogQTweetLib
libOAuth httpliboauthsourceforgenet
clojure
clj-oauth httpgithubcommattreplclj-oauth
net
oauth-dot-net httpcodegooglecompoauth-dot-net
DotNetOpenAuth httpwwwdotnetopenauthnet
Erlang
erlang-oauth httpgithubcomtimerlang-oauth
java
Scrible httpgithubcomfernandezpablo85scribe-java
oauth-signpost httpcodegooglecompoauth-signpost
javascript
oauth in js httpoauthgooglecodecomsvncodejavascript
Objective-CCocoa amp iPhone programming
OAuthCore httpbitbucketorgatebitsoauthcore
MPOAuthConnection httpcodegooglecompmpoauthconnection
Objective-C OAuth httpoauthgooglecodecomsvncodeobj-c
Perl
NetOAuth httpoauthgooglecodecomsvncodeperl
PHP
tmhOAuth httpgithubcomthemattharristmhOAuth
oauth-php httpcodegooglecompoauth-php
Python
python-oauth2 httpgithubcombrosnerpython-oauth2
Qt
qOauth httpgithubcomayoyqoauth
Ruby
Oauth ruby gem httpoauthrubyforgeorg
Scala
DataBinder Dispatch httpdispatchdatabindernetAbout
附录 D Oauth签名加密 oauth_signature
1 加密内容是
a 请求方法名例如 GET POST等 加密时方法名大写并进行特殊替换
(详见 3)
b url (query param之前的部分不包括 )Http或者 https需要全部小
写 http如果带有 80端口或者 https带有 443端口需要将其省略
其他端口则不能省略例如
Httplocal9999requestToken
httplocal9999requestToken
Httplocal80requestToken
httplocalrequestToken
Httpslocal443requestToken
httpslocal requestToken
c 参数(query param中的或者 header中的 key-value对) 首先将这些参数
进行特殊替换后按字典序排序升序排列如果两个 key相同则以
value特殊替换后字典序为准key与 value之间使用rdquo=rdquo连接如果
value==null则使用rdquordquo替代两个参数对之间使用rdquoamprdquo连接连接后形成
的最终字符串的开头和结尾没有rdquoamprdquo
d 字典序字符串比较大小伪代码
Int compare(string a string b)
Int min_len = min(len(a) len(b))
For I to min_len
If (a[i] = b[i])
Return a[i] ndash b[i]
Return len(a) ndash len(b)
将以上 abc三部分进行特殊替换后使用amp连接最终形成的字符串的
开头和结尾都没有rdquoamprdquo这就是加密内容
2 加密的 key是 consumerSecret + amp + TokenSecret 如果 TokenSecret还没有
得到则使用rdquordquo consumerSecret和 TokenSecret需先做特殊替换然后
再进行签名
3 特殊替换是将 String进行 URL编码后将rdquo+rdquo替换为rdquo20rdquo将rdquordquo替换
为rdquo2Ardquo将rdquo7Erdquo替换为rdquo~rdquo
4 签名方法可以使用 HMAC-SHA1PLAINTEXT RSA_SHA1三种其中
PLAINTEXT为 2中的 key 该方法不提倡使用
得到签名内容后使用 Base64进行编码编码后的字符串即为 oauth_signature
Scrible httpgithubcomfernandezpablo85scribe-java
oauth-signpost httpcodegooglecompoauth-signpost
javascript
oauth in js httpoauthgooglecodecomsvncodejavascript
Objective-CCocoa amp iPhone programming
OAuthCore httpbitbucketorgatebitsoauthcore
MPOAuthConnection httpcodegooglecompmpoauthconnection
Objective-C OAuth httpoauthgooglecodecomsvncodeobj-c
Perl
NetOAuth httpoauthgooglecodecomsvncodeperl
PHP
tmhOAuth httpgithubcomthemattharristmhOAuth
oauth-php httpcodegooglecompoauth-php
Python
python-oauth2 httpgithubcombrosnerpython-oauth2
Qt
qOauth httpgithubcomayoyqoauth
Ruby
Oauth ruby gem httpoauthrubyforgeorg
Scala
DataBinder Dispatch httpdispatchdatabindernetAbout
附录 D Oauth签名加密 oauth_signature
1 加密内容是
a 请求方法名例如 GET POST等 加密时方法名大写并进行特殊替换
(详见 3)
b url (query param之前的部分不包括 )Http或者 https需要全部小
写 http如果带有 80端口或者 https带有 443端口需要将其省略
其他端口则不能省略例如
Httplocal9999requestToken
httplocal9999requestToken
Httplocal80requestToken
httplocalrequestToken
Httpslocal443requestToken
httpslocal requestToken
c 参数(query param中的或者 header中的 key-value对) 首先将这些参数
进行特殊替换后按字典序排序升序排列如果两个 key相同则以
value特殊替换后字典序为准key与 value之间使用rdquo=rdquo连接如果
value==null则使用rdquordquo替代两个参数对之间使用rdquoamprdquo连接连接后形成
的最终字符串的开头和结尾没有rdquoamprdquo
d 字典序字符串比较大小伪代码
Int compare(string a string b)
Int min_len = min(len(a) len(b))
For I to min_len
If (a[i] = b[i])
Return a[i] ndash b[i]
Return len(a) ndash len(b)
将以上 abc三部分进行特殊替换后使用amp连接最终形成的字符串的
开头和结尾都没有rdquoamprdquo这就是加密内容
2 加密的 key是 consumerSecret + amp + TokenSecret 如果 TokenSecret还没有
得到则使用rdquordquo consumerSecret和 TokenSecret需先做特殊替换然后
再进行签名
3 特殊替换是将 String进行 URL编码后将rdquo+rdquo替换为rdquo20rdquo将rdquordquo替换
为rdquo2Ardquo将rdquo7Erdquo替换为rdquo~rdquo
4 签名方法可以使用 HMAC-SHA1PLAINTEXT RSA_SHA1三种其中
PLAINTEXT为 2中的 key 该方法不提倡使用
得到签名内容后使用 Base64进行编码编码后的字符串即为 oauth_signature
(详见 3)
b url (query param之前的部分不包括 )Http或者 https需要全部小
写 http如果带有 80端口或者 https带有 443端口需要将其省略
其他端口则不能省略例如
Httplocal9999requestToken
httplocal9999requestToken
Httplocal80requestToken
httplocalrequestToken
Httpslocal443requestToken
httpslocal requestToken
c 参数(query param中的或者 header中的 key-value对) 首先将这些参数
进行特殊替换后按字典序排序升序排列如果两个 key相同则以
value特殊替换后字典序为准key与 value之间使用rdquo=rdquo连接如果
value==null则使用rdquordquo替代两个参数对之间使用rdquoamprdquo连接连接后形成
的最终字符串的开头和结尾没有rdquoamprdquo
d 字典序字符串比较大小伪代码
Int compare(string a string b)
Int min_len = min(len(a) len(b))
For I to min_len
If (a[i] = b[i])
Return a[i] ndash b[i]
Return len(a) ndash len(b)
将以上 abc三部分进行特殊替换后使用amp连接最终形成的字符串的
开头和结尾都没有rdquoamprdquo这就是加密内容
2 加密的 key是 consumerSecret + amp + TokenSecret 如果 TokenSecret还没有
得到则使用rdquordquo consumerSecret和 TokenSecret需先做特殊替换然后
再进行签名
3 特殊替换是将 String进行 URL编码后将rdquo+rdquo替换为rdquo20rdquo将rdquordquo替换
为rdquo2Ardquo将rdquo7Erdquo替换为rdquo~rdquo
4 签名方法可以使用 HMAC-SHA1PLAINTEXT RSA_SHA1三种其中
PLAINTEXT为 2中的 key 该方法不提倡使用
得到签名内容后使用 Base64进行编码编码后的字符串即为 oauth_signature
PLAINTEXT为 2中的 key 该方法不提倡使用
得到签名内容后使用 Base64进行编码编码后的字符串即为 oauth_signature