通过有道云笔记的开放API,第三方应用可以对有道云笔记的数据进行安全的访问与修改,而不需要搭设和维护云存储服务,这降低了第三方的开发与运营成本,从而将更多的精力专注于应用本身。
由于有道云笔记中的数据均为用户个人数据,因此必须通过OAuth用户授权后,才可以使用OpenAPI,目前有道云笔记OpenAPI使用OAuth 2.0的授权方式
oauth_authorize(GET)
参数
client_idString
- 应用申请的consumer key
redirect_uriString
- 用户授权成功之后的跳转地址,在申请consumerKey的时候会要求填入domains,只要该参数值属于所填的domains(没有domain的时候采用home page)中的任意一个即可。如果该应用没有domain信息,则该参数需要填固定的http://note.youdao.com/redirect 网址才能通过认证。
stateString
- 授权完成后会回传该参数,应用可以进行验证,可以使用时间戳
response_typeString
- 当前只支持code
displayString
- 默认会根据userAgent进行自动适配,可选值web/mobile,用于适配pc或mobile设备
返回
返回示例
错误返回示例
返回http状态500并返回错误码和错误信息
请输入错误举例
oauth_access(GET)
参数
client_idString
- 应用申请的consumer key
client_secretString
- 对应的consumer secret
redirect_uriString
- 之前在authorize接口中使用的callback url
codeString
- 用户授权后得到的code
grant_typeString
- 当前只支持authorization_code
返回
返回示例
调用成功返回access token,否则返回出错信息。
举例:{"accessToken":"b43de33483491bc86090d6a707d6c3d3"}
错误返回示例
返回http状态500并返回错误码和错误信息
请输入错误举例
get_user(GET)
参数
oauth_tokenString
- 用户的access token
返回
返回示例
用户的有道云笔记账号信息,包括id,用户名(user),用户总空间大小(total_size),已使用空间大小(used_size),注册时间(register_time),上次登录时间(last_login_time),最后修改时间(last_modify_time)以及默认笔记本(default_notebook)。
其中用户id对于同一个应用来说是唯一的,对于不同的应用用户id可能不同;此外系统会为每个应用生成一个默认笔记本,笔记本名通常为“来自app的名字”,在创建笔记时如果不指定笔记本,则会自动创建在该默认笔记本中
举例:{"id":"id value","user":"user value","total_size":"total_size value","used_size":"used_size value","register_time":"register_time value","last_login_time":"last_login_time value","last_modify_time":"last_modify_time value","default_notebook":"default_notebook value"}
错误返回示例
返回http状态500并返回错误码和错误信息
举例{"error":"error value","message":"message value"}
get_all_notebooks(POST)
参数
oauth_tokenString
- 用户的access token
返回
返回示例
用户笔记本的数组,每个元素对应用户的一个笔记本,笔记本信息包括:笔记本路径(path),笔记本名称(name),笔记本中的笔记数(notes_num),笔记本组名(group),创建时间(create_time),修改时间(modify_time)。
其中笔记本的路径通常为/notebookId的格式,对一个用户来说路径是唯一的;笔记本组起到对笔记本分类的作用,笔记本组相同的笔记本会在客户端中归为一组,例如有两个笔记本“工作计划”和“工作备忘”可以都被设置为“工作”笔记本组。
举例:["path value","name value","notes_num value","group value","create_time value","modify_time value"]
错误返回示例
返回http状态500并返回错误码和错误信息
请输入错误举例
create_notebook(POST)
参数
oauth_tokenString
- 用户的access token
nameString
- 笔记本名称
groupString
- 笔记本组,笔记本组起到对笔记本分类的作用,笔记本组相同的笔记本会在客户端中归为一组,例如有两个笔记本“工作计划”和“工作备忘”可以都被设置为“工作”笔记本组。
create_timeString
- 由于用户创建笔记本的时间可能与同步时间不同,因此可以指定用户创建笔记本的时间,不指定时则使用同步时的系统时间,使用unix时间,单位为秒
返回
返回示例
新建的笔记本信息
举例:{"path":"path value","name":"name value","notes_num":"notes_num value","group":"group value","create_time":"create_time value","modify_time":"modify_time value"}
错误返回示例
返回http状态500并返回错误码和错误信息
举例{"error":"error value","message":"message value"}
delete_notebook(POST)
参数
oauth_tokenString
- 用户的access token
notebookString
- 删除笔记本的路径
modify_timeString
- 由于用户删除笔记本的时间可能与同步时间不同,因此可以指定用户删除笔记本的时间,不指定时则使用同步时的系统时间,使用unix时间,单位为秒
返回
返回示例
错误返回示例
操作成功时http状态200,无返回数据;失败时http状态500并返回错误码和错误信息
举例{"error":"error value","message":"message value"}
list_note(POST)
参数
oauth_tokenString
- 用户的access token
notebookString
- 获取该笔记本路径下的笔记,不指定时获取所有笔记
productString
- 按照笔记的创建来源进行过滤,例如如果想获取所有本app创建的笔记,则可以在该参数中指定“app名称”,不指定时获取全部笔记
beginString
- 分页参数,当前页第一篇笔记的index,全部笔记的index从0开始
lenString
- 分页参数,一页获取的笔记数目,默认为20
返回
返回示例
笔记列表,每个元素对应一篇笔记的信息,包含有笔记路径(path),笔记标题(title),作者(author),来源url(source),笔记大小bytes(size),缩略图url(thumbnail),摘要(summary),创建时间(create_time),修改时间(modify_time),不包含笔记正文
举例:["path value","title value","author value","source value","size value","thumbnail value","summary value","create_time value","modify_time value","content value"]
错误返回示例
返回http状态500并返回错误码和错误信息
举例{"error":"error value","message":"message value"}
get_note(POST)
参数
oauth_tokenString
- 用户的access token
pathString
- 笔记路径
返回
返回示例
笔记的全部信息,包含有笔记路径(path),笔记标题(title),作者(author),来源url(source),笔记大小bytes(size),缩略图url(thumbnail),摘要(summary),创建时间(create_time),修改时间(modify_time)以及正文(content)
笔记正文采用类似html的标记语言,应用可以采用web view进行渲染,但是需要处理图片及附件。笔记中图片和附件均采用img标签的格式进行标记,在src中就是图片的url或者附件的图标,但是由于这些内容属于用户的数据,因此也需要添加对应的用户认证信息后才可以获取,此外对于附件来说,附件的url放置在img的path属性中,可以采用同样的方式进行下载
举例:{"path":"path value","title":"title value","author":"author value","source":"source value","size":"size value","thumbnail":"thumbnail value","summary":"summary value","create_time":"create_time value","modify_time":"modify_time value","content":"content value"}
错误返回示例
请输入错误说明
请输入错误举例
create_note(POST)
参数
oauth_tokenString
- 用户的access token
contentString
- 笔记正文,笔记正文采用类似html的标记语言,如果有图片或者附件,需要提前通过resource接口上传图片或附件。笔记中图片和附件均采用img标签的格式进行标记,在src中就是图片的url或者附件的图标url,对于附件来说,附件的url放置在img的path属性中
notebookString
- 该新建笔记所属的笔记本路径,如果不指定则在该应用的默认笔记本下创建
titleString
- 笔记标题
sourceString
- 笔记来源URL
authorString
- 笔记作者
read_onlyString
- 笔记只读属性,由于第三方应用可能在笔记中保存了自己可以解析的数据格式,因此可以设置该属性让其他客户端无法编辑该笔记
create_timeString
- 由于用户创建笔记的时间可能与同步时间不同,因此可以指定用户创建笔记的时间,不指定时则使用同步时的系统时间,使用unix时间,单位为秒
返回
返回示例
新建笔记的路径
举例:{"path":"path value"}
错误返回示例
返回http状态500并返回错误码和错误信息
请输入错误举例
update_note(POST)
参数
oauth_tokenString
- 用户的access token
pathString
- 待修改笔记的路径
titleString
- 修改后的笔记标题
contentString
- 修改后的笔记正文
sourceString
- 修改后的笔记来源URL
authorString
- 修改后的笔记作者
modify_timeString
- 由于用户修改笔记的时间可能与同步时间不同,因此可以指定用户修改笔记的时间,不指定时则使用同步时的系统时间,使用unix时间,单位为秒
返回
返回示例
错误返回示例
返回http状态500并返回错误码和错误信息
举例{"error":"error value","message":"message value"}
move_note(POST)
参数
oauth_tokenString
- 用户的access token
pathString
- 待移动的笔记原路径
notebookString
- 目标笔记本的路径
返回
返回示例
移动后的笔记路径
举例:{"path":"path value"}
错误返回示例
返回http状态500并返回错误码和错误信息
举例{"error":"error value","message":"message value"}
delete_note(POST)
参数
oauth_tokenString
- 用户的access token
pathString
- 待删除的笔记路径
modify_timeString
- 由于用户删除笔记的时间可能与同步时间不同,因此可以指定用户删除笔记的时间,不指定时则使用同步时的系统时间,使用unix时间,单位为秒
返回
返回示例
错误返回示例
返回http状态500并返回错误码和错误信息
举例{"error":"error value","message":"message value"}
upload_resource(POST)
参数
oauth_tokenString
- 用户的access token
fileString
- 上传的文件, Multipart File格式,文件大小限制25M
create_timeString
- 用户创建附件的时间,由于用户创建附件的时间与同步时间可能不同,不指定时则使用同步时的系统时间,unix时间,单位为秒
返回
返回示例
上传的resource的url,对于附件,还会包含一个src字段,该字段对应附件的图标url,是由系统根据附件类型生成的,用于在正文中进行展示
resource不能独立于笔记存在,在上传resource后,需要将resource加入到对应的笔记中才可,关于笔记正文的格式参见创建/修改笔记接口
举例:{"url":"url value","src":"src value"}
错误返回示例
需要注意的是,在附件上传完成后,使用者应该紧接着更新对应的笔记,否则不被任何笔记引用的附件将被定期的空间回收所删除。
请输入错误举例
download_resource(GET)
参数
oauth_tokenString
- 用户的access token
resourceIdString
- resource的id,在正文中返回的resource url已经包含了resourceId和version
versionString
- resource的version,在正文中返回的resource url已经包含了resourceId和version
返回
返回示例
错误返回示例
返回http状态500并返回错误码和错误信息
举例{"error":"error value","message":"message value"}
download_thumbnail(GET)
参数
oauth_tokenString
- 用户的access token
wString
- 缩略图的宽度,默认70像素
hString
- 缩略图的高度,默认70像素
返回
返回示例
错误返回示例
返回http状态500并返回错误码和错误信息
举例{"error":"error value","message":"message value"}
publish(POST)
参数
oauth_tokenString
- 用户的access token
pathString
- 待共享的笔记路径
返回
返回示例
共享笔记的链接
举例:{"url":"url value"}
错误返回示例
返回http状态500并返回错误码和错误信息
请输入错误举例