企业网盘API开发手册.docx
- 文档编号:5621367
- 上传时间:2022-12-29
- 格式:DOCX
- 页数:28
- 大小:28.29KB
企业网盘API开发手册.docx
《企业网盘API开发手册.docx》由会员分享,可在线阅读,更多相关《企业网盘API开发手册.docx(28页珍藏版)》请在冰豆网上搜索。
企业网盘API开发手册
企业网盘
API开发手册
1.
引言
1.1文档说明
RESTAPI是我们的官方底层接口。
企业网盘客户端应用程序和我们的 SDKs,是最直接的方式来访问API。
本文为参考文件,为开发人员提供技术和文档服务。
1.2版本
版本
更新时间
备注
V2.1.0
2014-08-27
最后修改版本
2.一般注意事项
2.1API编码格式
从企业网盘API传递给每一个字符串,需要UTF-8编码。
为获得最大的兼容性,规范 UnicodeNormalizationFormC (NFC)beforeUTF-8encoding。
3.错误处理
使用标准的HTTP错误代码语法错误返回。
任何额外的信息是包含在返回调用的内容中,采用JSON格式。
此处未列出的错误代码在RESTAPI方法错误部分列出。
3.1标准API错误
code
说明
400
Badinputparameter.Errormessageshouldindicatewhichoneandwhy.
401
Badorexpiredtoken.Thiscanhappeniftheuserrevokedorexpiredanaccesstoken.Tofix,youshouldre-authenticatetheuser.
403
BadOAuthrequest(wrongconsumerkey,badnonce,expiredtimestamp,...).Unfortunately,re-authenticatingtheuserwon'thelphere.
404
Fileorfoldernotfoundatthespecifiedpath.
405
Requestmethodnotexpected(generallyshouldbeGETorPOST).
503
Yourappismakingtoomanyrequestsandisbeingratelimited.503scantriggeronaper-apporper-userbasis.
507
Userisoverstoragequota.
5xx
Servererror.
4.API接口
4.1登陆与授权
4.1.1/oauth/request_token
4.1.1.1说明
认证的第一个步骤,包含一个授权requesttoken 到用于认证过程的其余部分。
此方法对应 获取XX的RequestToken 在OAuth的核心2.0规范.
4.1.1.2URL结构
4.1.1.3访问方法
POST
4.1.1.4参数
没有具体参数。
了解 ConsumerObtainsaRequestToken 在OAuth的核心2.0为规范说明,OAuth参数用于获取一个requesttoken。
由于这种方法是代表一个XX的用户,当签名或者发送一个请求,没有token或者secret将不能访问。
4.1.1.5返回值
一个requesttoken和相对应的requesttokensecret,,URL-encoded,这对token/secret意味着被使用在 /oauth/access_token 去完成验证过程和不能使用对其它任何API调用。
了解XX服务供应商发出RequestToken OAuth的核心2.0规范的额外内容,返回值可以提取requesttoken。
JSON响应样本
oauth_token_secret=b9q1n5il4lcc&oauth_token=mh7an9dkrg59
4.1.2/oauth/authorize
4.1.2.1说明
认证第二个步骤。
应用程序应该直接授权用户/oauth/authorize。
这不是一个API调用本身,而是让一个网络端点,用户登录企业网盘和选择是否批准申请,代表他们访问文件的权限。
页面服务 /oauth/authorize 应提交通过他们的Web浏览器的用户。
用户在这一步授权,为你应用程序获得一个accesstoken从/oauth/access_token。
此方法对应获取用户Authorization在OAuth的核心2.0规范。
4.1.2.2URL结构
4.1.2.3访问方法
GET
4.1.2.4参数
1.oauth_token - 必须的。
请求token获得通过 /oauth/request_token。
2.oauth_callback -在用户授权应用后,用户被重定向到应用服务的URL提供此参数。
3.user_name - 必须的。
用户名,用户被重定向到应用服务的URL提供此参数。
4.password - 必须的。
用户密码,用户被重定向到应用服务的URL提供此参数。
5.device_name - 必须的 用户设备名称。
6.device_type - 必须的 设备类型,如:
device_type{
WEB_DEVICE=1;//web端
SYSTEM_DEVICE=2;//系统设备
PC_DEVICE=3;//计算机设备
MOBILE_DEVICE=4;//移动设备
}
7.device_info - 必须的。
设备信息,设备对应唯一值,如硬盘序列号。
8.locale -企业网盘将使用本地的参数提供便于服务器翻译对应的语言,如果可能的话。
详细了解上述更多有关支持的语言环境。
4.1.2.5返回值
因为应用程序没有直接调用/oauth/authorize,没有直接的返回值。
这一步的重要性是在用户授权的应用程序后,可以使用其请求token通过检索一个访问token,通过/oauth/access_token API调用。
如果 oauth_callback 参数被省略,在应用程序必须找到一些其他方式确定何时授权步骤完成。
例如,这个应用程序能有用户的明确表示便于这一步完成,。
如果oauth_callback被指定,应用程序将当用户将被重定向到给定的,知道授权完成网址。
企业网盘将提供下面的返回值通过GET参数在网址:
1.oauth_token -这个请求token仅是授权。
请求的tokensecret没有被返回。
2.uid -用户的授权id在企业网盘。
4.1.3/oauth/access_token
4.1.3.1说明
认证第三个步骤。
在 /oauth/authorize 步骤完成后,这个应用程序能调用/oauth/access_token 获得访问token。
此方法对应 ObtaininganAccessToken 在OAuth的核心2.0规范。
4.1.3.2URL结构
4.1.3.3访问方法
POST
4.1.3.4参数
没有这种方法企业网盘的具体参数。
详细了解 ConsumerRequestsanAccessToken 在OAuth的核心2.0为规范说明用于取访问的参数token。
注意这个 oauth_token 和oauth_token_secret这种方法的要求token和tokensecret先前获得通过/oauth/request_token。
4.1.3.5返回值
一个访问token和相应的访问tokensecret,URL-encoded.返回时,授权过程已完成,可以用token和tokensecret来签名API。
详细了解 ServiceProviderGrantsanAccessToken在OAuth的核心2.0规范,当获取一个返回值accesstoken的说明。
如果您的应用程序配置一个应用程序文件夹内的工作,该文件夹也是在这一步中创建。
JSON响应样本
oauth_token_secret=95grkd9na7hm&oauth_token=ccl4li5n1q9b
4.2账户信息
4.2.1/account/info
4.2.1.1说明
获取用户的帐户信息。
4.2.1.2URL结构
4.2.1.3访问方法
GET
4.2.1.4参数
locale -用户错误消息和特定于语言文本将被转换为给定的语言环境。
4.2.1.5返回值
JSON响应样本
{
"display_name":
"JohnP.User",
"uid":
12345678,
"space":
104857600,
"used_space":
9028410,
"email":
"xxx@",
"phone":
"1388888888"
}
Returnvaluedefinitions
field
说明
display_name
用户的显示名称.
uid
用户唯一的企业网盘ID.
space
用户空间配额(字节).
used_space
用用户的已经使用的配额(字节).
用户电子邮件.
phone
development_api_user
4.3文件和元数据
4.3.1/files(GET)
4.3.1.1说明
下载文件接口。
4.3.1.2URL结构
1.root -指定的路径是相对于它的根,有效的值是企业网盘对应拼音。
2.path -您要检索的文件的路径。
4.3.1.3访问方法
GET
4.3.1.4参数
1.rev -要检索的文件的修订版本。
此信息默认为最新版本。
4.3.1.5返回值
指定的文件的内容为请求的修订版本。
4.3.1.6错误
404该文件找不到指定的路径,或在未找到指定的rev。
4.3.2/files_put
4.3.2.1说明
使用PUT上传文件。
此方法是在大多数情况下比使用/files(POST)更简单 .
4.3.2.2URL结构
1.root -指定的路径是相对于它的根目录,有效的值是企业网盘对应拼音。
2.path -要写入的文件的完整路径,这个参数将 不 指向一个文件夹。
3.param=val -此请求的的url编码参数。
他们不能不能发送请求主体中。
4.3.2.3访问方法
PUT
4.3.2.4参数
1.Thebodyoftherequest - 必须的。
要上传文件的内容。
由于整个PUT/POST的body会被视为该文件,任何参数必须将作为请求URL的一部分传递。
请求的URL应该签名,类似签名任何其他OAuth的请求URL。
2.locale -元数据上传成功返回将其size 基于给定的翻译语言环境.
3.overwrite -这个值,可以是true (默认)或者 false,确定发生了什么时,有已经是一个文件,在指定的路径。
如果true,这个村子的文件将被新文件覆盖。
如果false,这个新文件将自动重命名(例如"test.txt"可能自动重命名为"test
(1).txt"),这个新名字被包含在返回的元数据里面。
4.parent_rev -您要编辑的文件的修订版本。
如果 parent_rev 匹配最近的文件版本在用户的,那这个文件将被替换。
否则,这个新文件将被重命名(例如,"test.txt"可能被重命名为"test(conflictedcopy).txt")。
如果你指定一个不存在的版本号,这个文件将不会保存(返回error400)。
获取最近的版本 rev 通过调用 /metadata。
4.3.2.5返回值
这些是上传文件的元数据,在可用的返回元数据字段的详细信息。
JSON响应样本
{
"size":
"225.4KB",
"rev":
"35e97029684fe",
"thumb_exists":
false,
"bytes":
230783,
"modified":
"Tue,19Jul201121:
55:
38+0000",
"path":
"/Getting_Started.pdf",
"is_dir":
false,
"icon":
"page_white_acrobat",
"root":
"",
"mime_type":
"application/pdf",
"revision":
220823
}
4.3.2.6错误
411但是在企业网盘不支持分块编码上传。
说明:
我们 强烈推荐 提供 Content-Length 头,使服务器可以设置上传文件的大小验证,它已经收到整个文件的内容。
4.3.3/files(POST)
4.3.3.1说明
上传文件。
我们推荐你使用 /files_put 而因为其简单的接口。
4.3.3.2URL结构
1.root -指定的路径是相对于它的根。
有效的值是企业网盘对应拼音。
2.path -要写入的文件的完整路径。
这个参数不能指向一个文件夹。
4.3.3.3访问方法
POST
4.3.3.4参数
1.file - 必须的。
这个文件内容被上传,需要多部分上传(multipart/form-data),和这个filename这一领域的参数应设置为所需的目标文件名。
同时使用OAuth签名此请求,这个 file 参数应该设置为目标文件名,然后切换到文件的内容为multipart请求。
2.locale -用户错误消息和特定于语言文本将被转换为给定的语言环境。
3.overwrite -这个值可以是true (default)或者 false,确定指定的路径已存在的文件时,如果为 true,这个存在的文件将被新文件覆盖。
如果是 false,这个新文件将自动重命名(例如,"test.txt"可能被重命名为"test
(1).txt")。
这个新名字被包含在返回的元数据里面。
4.parent_rev -您正在编辑的文件的修订。
如果 parent_rev 匹配最近的文件版本在用户的企业网盘,那么这个文件将被替换。
否则,这个新文件将自动重命名(例如,"test.txt"可能重命名为"test(conflictedcopy).txt"),如果你指定一个版本不存在,那这个文件将不会保存(返回错误error400)。
获取最近的rev 通过调用接口/metadata。
4.3.3.5返回值
上传的文件的元数据。
在返回的更多信息可用的元数据字段。
JSON响应样本
{
"size":
"225.4KB",
"rev":
"35e97029684fe",
"thumb_exists":
false,
"bytes":
230783,
"modified":
"Tue,19Jul201121:
55:
38+0000",
"path":
"/Getting_Started.pdf",
"is_dir":
false,
"icon":
"page_white_acrobat",
"root":
"",
"mime_type":
"application/pdf",
"revision":
220823
}
4.3.3.6错误
400文件扩展名为企业网盘的忽略列表(e.g.thumbs.dbor.ds_store)。
404这个文件的parent_rev没有找到。
411分块编码,试图为这个上传,但不支持企业网盘。
4.3.4/files_sec
4.3.4.1说明
使用hash上传文件,实现秒传。
此方法能更快速的创建文件,如果文件已经被创建过一次/files(POST)或者/files_put。
4.3.4.2URL结构
1.root -指定的路径是相对于它的根。
有效的值是企业网盘对应英文。
2.path -要写入的文件的完整路径。
这个参数将不 指向一个文件夹。
4.3.4.3访问方法
POST/GET
4.3.4.4参数
1.hash - 必须的。
要上传文件的内容的hash值(sha1算法)。
任何参数必须将作为请求URL的一部分传递。
请求的URL应该签名,就像你签名任何其他OAuth的请求URL。
2.locale -元数据上传成功返回将其size基于给定的翻译语言环境。
3.overwrite -这个值,可以是 true (默认)或者 false,如果已经是一个文件存在,在指定的路径,如果true,这个文件将被新文件覆盖。
如果false,这个新文件将自动重命名(例如,"test.txt"可能自动重命名为"test
(1).txt")。
这个新名字被包含在返回的元数据里面。
4.parent_rev -您正在编辑的文件的修订。
如果 parent_rev 匹配最近的文件版本在用户的企业网盘,那么这个文件将被替换。
否则,这个新文件将自动重命名(例如,"test.txt"可能重命名为"test(conflictedcopy).txt"),如果你指定一个版本不存在,那这个文件将不会保存(返回错误error400)。
获取最近的rev 通过调用接口/metadata。
4.3.4.5返回值
JSON响应样本
{
"size":
"225.4KB",
"rev":
"35e97029684fe",
"thumb_exists":
false,
"bytes":
230783,
"modified":
"Tue,19Jul201121:
55:
38+0000",
"path":
"/Getting_Started.pdf",
"is_dir":
false,
"icon":
"page_white_acrobat",
"root":
"",
"mime_type":
"application/pdf",
"revision":
220823
}
4.3.4.6错误
303企业网盘要求客户端上传文件使用/files(POST)或者/files_put上传文件
我们 强烈推荐 提供 Content-Length 头,使服务器可以设置上传文件的大小验证,它已经收到整个文件的内容。
4.3.5/metadata
4.3.5.1说明
检索元数据文件和文件夹。
4.3.5.2URL结构
1.root -指定的路径是相对于它的根。
有效的值是企业网盘对应拼音。
2.path -要写入的文件的完整路径,这个参数将不能指向一个文件夹。
4.3.5.3访问方法
GET
4.3.5.4参数
1.file_limit -默认值为10,000,当查询一个目录,该服务将不会报告列表包含比file_limit更多文件和406(不接受)状态,而不是回应。
2.hash -每次调用/metadata在一个文件夹都将返回一个 hash 值,所产生的哈希所有在该响应中包含的元数据。
在最近调用的/metadata你应规定,通过此参数值,因此,如果没有发生了变化,将响应一个“304notmodify”状态码而不是完整的(可能非常大)的文件夹列表.这参数被忽略,如果指定的路径与文件关联或者如果list=false,两个用户之间共享一个文件夹为每个用户有相同的哈希。
3.list -这个字符串为 true 或者false。
true 是默认值,如果是 true,这个文件夹的元数据将包括一个contents属性,包含元数据条目内容的文件夹的列表。
如果 false,这个contents属性不会返回。
4.include_deleted -如果这个参数设置为true,那已经删除的文件和文件夹将被包含在元数据里面。
5.rev -如果包括一个特定的修订版号,然后只对修订的元数据将被返回。
6.locale -用户错误消息和特定于语言文本将被转换为给定的语言环境。
4.3.5.5返回值
文件或者文件夹的元数据对应给定的路径
如果
JSON响应样本
{
"size":
"225.4KB",
"rev":
"35e97029684fe",
"thumb_exists":
false,
"bytes":
230783,
"modified":
"Tue,19Jul201121:
55:
38+0000",
"path":
"/Getting_Started.pdf",
"is_dir":
false,
"icon":
"page_white_acrobat",
"root":
"",
"mime_type":
"application/pdf",
"revision":
220823,
"hash":
"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
}
JSON响应样本
返回值的一个文件夹,且 list 参数被设置 true。
(如果 list 是false 这个 contents键将简单省略结果)
{
"size":
"0bytes",
"hash":
"37eb1ba1849d4b0fb0b28caf7ef3af52",
"bytes":
0,
"thumb_exists":
false,
"rev":
"714f029684fe",
"modified":
"Wed,27Apr201122:
18:
51+0000",
"path":
"/Public",
"is_dir":
true,
"icon":
"folder_public",
"root":
"",
"contents":
[
{
"size":
"0bytes",
"rev":
"35c1f029684fe",
"thumb_exists":
false,
"bytes":
0,
"modified":
"Mon,18Jul201120:
13:
43+0000",
"path":
"/Public
- 配套讲稿:
如PPT文件的首页显示word图标,表示该PPT已包含配套word讲稿。双击word图标可打开word文档。
- 特殊限制:
部分文档作品中含有的国旗、国徽等图片,仅作为作品整体效果示例展示,禁止商用。设计者仅对作品中独创性部分享有著作权。
- 关 键 词:
- 企业 API 开发 手册