钉钉开发文档

管理钉盘文件

更新时间: 2019-2-13

钉盘是为企业提供文件云端存储和分享能力的产品,每个注册团队默认免费赠送100G空间。
钉盘为聊天、考勤、审批、日志等应用提供文件服务,包括上传、下载、在线预览、长期存储、权限管理、阅读统计等服务。
同时钉盘也提供开放的API接口,供企业自建应用或ISV接入,提供强大的文件服务。

名词解释


  1. spaceId:钉盘以space作为文件存储容器,可类比电脑上的C盘、E盘等。例如在钉钉内,每一个群文件对应一个space,企业钉盘中的公共区、共享文件夹、我的文件等也分别对应一个space。
  2. fileId:文件在钉盘内的唯一性标识。
  3. 自定义空间:针对企业或ISV的个性化需求,钉盘在企业下开辟了自定义空间来供企业或ISV使用。每个企业可以自定义若干存储空间,每个微应用可以使用一个自定义存储空间,该空间在钉钉客户端不可见,在电脑管理后台可以查看其占用企业空间的情况。
  4. 钉盘权限:区别于普通文件存储,钉盘提供完善的权限管理服务,文件的上传、下载、查看等操作需要在权限允许的条件下执行。
  5. 存储服务器 & 钉盘服务器:存储服务器提供文件的存储服务,存储服务器上以mediaId唯一标识文件。钉盘服务器提供文件的目录关系、权限管理等服务。钉盘系统以fileId唯一标识文件,存储服务器内文件可添加到钉盘文件系统。
  6. 企业空间容量:钉盘存储空间属于有限资源,超出部分需付费购买。钉盘为企业免费提供100G空间,微应用使用的自定义空间将占用企业空间。

钉盘接口使用场景

场景一: 把文件保存到用户钉盘

  1. 服务端调用接口/file/upload/single上传文件获取mediaId
  2. 客户端调用jsapi biz.chooseSpaceDir获取用户选择的钉盘空间获取spaceId
  3. 服务端使用mediaId和spaceId调用接口/cspace/add把文件保存到用户空间

场景二: 给用户发钉盘文件消息

  1. 服务端调用接口/file/upload/single上传文件获取mediaId
  2. 服务端调用接口/cspace/add_to_single_chat把钉盘文件当做消息内容发送给用户

场景三: 企业自建应用使用自定义钉盘空间存储文件

  1. 调用接口/cspace/get_custom_space获取自建应用的自定义空间
  2. 调用接口/cspace/grant_custom_space授权用户访问自建应用的自定义空间
  3. 调用jsapi biz.util.uploadAttachment上传本地文件到自建应用自定义的钉盘空间里
  4. 用户访问时先通过/cspace/grant_custom_space授权下载权限,然后使用jsapi biz.cspace.preview预览钉盘文件

发送钉盘文件给指定用户

将文件发送给指定用户,用户将收到以微应用名义发送的一条文件消息。
请求方式:POST(HTTPS)
请求地址https://oapi.dingtalk.com/cspace/add_to_single_chat?access_token=ACCESS_TOKEN&agent_id=AGENT_ID&userid=USERID&media_id=MEDIA_ID&file_name=FILE_NAME

注意:浏览器可能会转义某些字符导致请求失败,调试时请使用curl或者代码模拟请求。

参数说明

参数 参数类型 必须 说明
access_token String 调用接口凭证
agent_id String 文件发送者微应用的agentId
userid String 文件接收人的userid
media_id String 调用钉盘上传文件接口得到的mediaid,需要utf-8 urlEncode
file_name String 文件名(需包含扩展名),需要utf-8 urlEncode

SDK请求示例(JAVA)

OapiCspaceAddToSingleChatRequest request = new OapiCspaceAddToSingleChatRequest();
request.setAgentId("135717601");
request.setUserid("01376814877479");
request.setMediaId("#iAEAAqRmaWxlA6h5dW5kaXNrMATOC7DaowXNCW0GzQlXB85a863FCM4AAXTG");
request.setFileName("test");
DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/cspace/add_to_single_chat?"+WebUtils.buildQuery(request.getTextParams(),"utf-8"));
OapiCspaceAddToSingleChatResponse response = client.execute(request, accessToken);

返回结果:

{
    "errcode":0,
    "errmsg":"ok"
}
参数 说明
errcode 错误码
errmsg 错误信息

新增文件到用户钉盘

将mediaId指定的文件添加到用户指定的钉盘目录下,该mediaId可由本页提供的上传接口获取。该功能需要调用客户端JSAPI (例如移动端 dd.biz.cspace.chooseSpaceDir) 唤起钉钉客户端页面,由用户选择要添加到的钉盘目录。
请求方式:GET(HTTPS)
请求地址https://oapi.dingtalk.com/cspace/add?access_token=ACCESS_TOKEN&agent_id=AGENT_ID&code=CODE&media_id=MEDIA_ID&space_id=SPACE_ID&folder_id=FOLDER_ID&name=NAME&overwrite=OVERWRITE

注意:浏览器可能会转义某些字符导致请求失败,调试时请使用curl或者代码模拟请求。

参数说明

参数 参数类型 必须 说明
access_token String 调用接口凭证
agent_id String 微应用的agentId
code String 如果是微应用,code值为微应用免登授权码,如果是服务窗应用,code值为服务窗免登授权码。code为临时授权码,只能消费一次,下次请求需要重新获取新的code
media_id String 调用钉盘上传文件接口得到的mediaid,需要utf-8 urlEncode
space_id String 调用钉盘选择控件后获取的用户钉盘空间ID
folder_id String 调用钉盘选择控件后获取的用户钉盘文件夹ID
name String 上传文件的名称,不能包含非法字符,需要utf-8 urlEncode
overwrite Boolean 遇到同名文件是否覆盖,若不覆盖,则会自动重命名本次新增的文件,默认为false

SDK请求示例(JAVA)

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/cspace/add");
OapiCspaceAddRequest request = new OapiCspaceAddRequest();
request.setAgentId("135717601");
request.setCode("test");
request.setMediaId("#add");
request.setSpaceId("01376814877479");
request.setFolderId("/test/");
request.setName("test");
request.setOverwrite(true);
request.setHttpMethod("GET");
OapiCspaceAddResponse response = client.execute(request,accessToken);

返回结果
正确时返回示例如下:

{
    "errcode":0,
    "errmsg":"success",
    "dentry":"{\"contentType\":\"document\",\"createTime\":1451560026000,\"creator\":{\"account\":\"X\",\"site\":0},\"extension\":\"txt\",\"id\":\"54301\",\"modifiedTime\":1451560026000,\"modifier\":{\"account\":\"X\",\"site\":0},\"name\":\"1.txt\",\"parentId\":0,\"path\":\"\/1.txt\",\"size\":9,\"type\":\"file\",\"version\":\"0\"}"
}
参数 说明
errcode 错误码
errmsg 错误信息
dentry 文件的详细信息

获取企业下的自定义空间

针对企业或ISV的个性化需求,我们在企业下开辟了自定义空间来供企业或ISV使用。每个企业可以自定义若干存储空间,每个存储空间不能有重名的文件(全路径),不同存储空间可以存在同名文件;不同存储空间的文件是隔离的,不会相互影响。企业下的自定义空间属于企业,共享使用企业的容量,其中的文件只有企业内部人员才可能有权限访问,访问需要企业或ISV进行授权。每个企业可以自定义若干存储空间,如使用preview空间来存放需要预览的文件。每个ISV的微应用在企业下对应一个自定义空间;这些存储空间在钉钉客户端不可见,在电脑管理后台可以查看其占用企业空间的情况。

请求方式:GET(HTTPS)
请求地址https://oapi.dingtalk.com/cspace/get_custom_space?access_token=ACCESS_TOKEN&domain=DOMAIN&agent_id=AGENT_ID

NOTICE:浏览器可能会转义某些字符导致请求失败,调试时请使用curl或者代码模拟请求

参数说明

参数 参数类型 必须 说明
access_token String 调用接口凭证
domain String 企业调用时传入,需要为10个字节以内的字符串,仅可包含字母和数字,大小写不敏感
agent_id String ISV调用时传入,微应用的agentId

SDK请求示例(JAVA)

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/cspace/get_custom_space");
OapiCspaceGetCustomSpaceRequest request = new OapiCspaceGetCustomSpaceRequest();
request.setAgentId("135717601");
request.setDomain("test");
request.setHttpMethod("GET");
OapiCspaceGetCustomSpaceResponse response = client.execute(request,accessToken);

返回结果
正确时返回示例如下:

{
    "errcode":0,
    "errmsg":"ok",
    "spaceid":"xxxx"
}
参数 说明
errcode 错误码
errmsg 错误信息
spaceid 获取到的空间id

授权用户访问企业自定义空间

企业或ISV可授权企业下指定人员访问其使用的自定义空间。授权类型包括上传和下载, 预览权限等同于下载权限。

请求方式:GET(HTTPS)
请求地址https://oapi.dingtalk.com/cspace/grant_custom_space?access_token=ACCESS_TOKEN&domain=DOMAIN&agent_id=AGENT_ID&type=TYPE&userid=USERID&path=PATH&fileids=FILEIDS&duration=DURATION

注意:浏览器可能会转义某些字符导致请求失败,调试时请使用curl或者代码模拟请求。

参数说明

参数 参数类型 必须 说明
access_token String 调用接口凭证
agent_id String ISV调用时传入,授权访问指定微应用的自定义空间
domain String 企业调用时传入,授权访问该domain的自定义空间
type String 权限类型,目前支持上传和下载,上传请传add,下载请传download
userid String 企业用户userid
path String 授权访问的路径,如授权访问所有文件传"/",授权访问/doc文件夹传"/doc/",需要utf-8 urlEncode, type=add时必须传递
fileids String 授权访问的文件id列表,id之间用英文逗号隔开,如"fileId1,fileId2", type=download时必须传递
duration Integer 权限有效时间,有效范围为0~3600秒,超出此范围或不传默认为30秒

SDK请求示例(JAVA)

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/cspace/grant_custom_space");
OapiCspaceGrantCustomSpaceRequest request = new OapiCspaceGrantCustomSpaceRequest();
request.setAgentId("135717601");
request.setDomain("test");
request.setType("add");
request.setUserid("01376814877479");
request.setPath("/test/");
request.setDuration(10000L);
request.setHttpMethod("GET");
OapiCspaceGrantCustomSpaceResponse response = client.execute(request,accessToken);�
{
    "errcode":0,
    "errmsg":"ok"
}
参数 说明
errcode 错误码
errmsg 错误信息

接口示例

授权上传,传入需要上传的路径。如在根目录下上传一个文件:

https://oapi.dingtalk.com/cspace/grant_custom_space?access_token=ACCESS_TOKEN&domain=preview&type=add&userid=USERID&path=/

授权下载,传入需要下载的文件id列表。如授权下载xxx和yyy两个文件:

https://oapi.dingtalk.com/cspace/grant_custom_space?access_token=ACCESS_TOKEN&domain=preview&type=download&userid=USERID&fileids=xxx,yyy

文件上传

钉盘提供接口将文件上传至存储服务器。提供两种上传方式:分块上传和单步上传。 分块上传支持将文件分片上传,并由commit步骤完成数据提交,可实现较大文件的上传,最多支持8M * 10000。单步上传流程较简单,最大支持8M文件上传。

单步文件上传

单步文件上传,标准 http multipart 上传,文件大小不得超过8M。
请求方式:POST(HTTPS)
请求地址https://oapi.dingtalk.com/file/upload/single?access_token=ACCESS_TOKEN&agent_id=AGENT_ID&file_size=FILE_SIZE

注意:浏览器可能会转义某些字符导致请求失败,调试时请使用curl或者代码模拟请求。
注意:请保证自己的机器有足够的出口带宽,否则可能导致上传异常缓慢。

参数说明

参数 参数类型 必须 说明
access_token String 调用接口凭证
agent_id String 微应用的agentId
file_size Integer 文件大小

SDK请求示例(JAVA)

OapiFileUploadSingleRequest request = new OapiFileUploadSingleRequest();
request.setFileSize(1000L);
request.setAgentId("135717601");
DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/file/upload/single?"+WebUtils.buildQuery(request.getTextParams(),"utf-8"));
// 必须重新new一个请求
request = new OapiFileUploadSingleRequest();
request.setFile(new FileItem("/Users/mxh/Downloads/test.png"));
OapiFileUploadSingleResponse response = client.execute(request,accessToken);

返回结果
正确时返回示例如下:

{
    "media_id": "xxxxxxxx",
    "errcode":0,
    "errmsg":"ok"
}
参数 说明
errcode 错误码
errmsg 错误信息
media_id 文件存储id

分块上传文件

开启分块上传事务

文件分块上传第一步,开启上传事务,该接口返回upload_id,钉盘服务器以upload_id唯一标识一个上传任务。分块最小需大于100KB,最大不超过8M,最多支持10000块。

请求方式:GET(HTTPS)
请求地址https://oapi.dingtalk.com/file/upload/transaction?access_token=ACCESS_TOKEN&agent_id=AGENT_ID&file_size=FILE_SIZE&chunk_numbers=CHUNK_NUMBERS

注意:浏览器可能会转义某些字符导致请求失败,调试时请使用curl或者代码模拟请求。

参数说明

参数 参数类型 必须 说明
access_token String 调用接口凭证
agent_id String 微应用的agentId
file_size Integer 文件大小
chunk_numbers Integer 文件总块数

SDK请求示例(JAVA)

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/file/upload/transaction");
OapiFileUploadTransactionRequest request = new OapiFileUploadTransactionRequest();
request.setAgentId("135717601");
request.setFileSize(1000L);
request.setChunkNumbers(1L);
request.setHttpMethod("GET");
OapiFileUploadTransactionResponse response = client.execute(request,accessToken);

返回结果
正确时返回示例如下:

{
    "upload_id": "xxxxxxxx",
    "errcode":0,
    "errmsg":"ok"
}
参数 说明
errcode 错误码
errmsg 错误信息
upload_id 上传事务id

上传文件块

文件分块上传中间环节,传输文件块,除最后一块外每块的大小不得小于100KB,最大不超过超过8M,使用标准 http multipart 上传。

请求方式:POST(HTTPS)
请求地址https://oapi.dingtalk.com/file/upload/chunk?access_token=ACCESS_TOKEN&agent_id=AGENT_ID&upload_id=UPLOAD_ID&chunk_sequence=CHUNK_SEQUENCE

注意:浏览器可能会转义某些字符导致请求失败,调试时请使用curl或者代码模拟请求。
注意:请保证自己的机器有足够的出口带宽,否则可能导致上传异常缓慢。

参数说明

参数 参数类型 必须 说明
access_token String 调用接口凭证
agent_id String 微应用的agentId
upload_id String 上传事务id,需要utf-8 urlEncode
chunk_sequence Integer 文件块号,从1开始计数

SDK请求示例(JAVA)

OapiFileUploadChunkRequest request = new OapiFileUploadChunkRequest();
request.setAgentId("135717601");
request.setChunkSequence(1L);
request.setUploadId("99F0F6DBB55A4C82822268192B5909F8_0#iAEAAqRmaWxlA6h5dW5kaXNrMATOC7DaowXNCW0GzQlXB85a863FCM4AAXTG");
DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/file/upload/chunk?"+WebUtils.buildQuery(request.getTextParams(),"utf-8"));
request = new OapiFileUploadChunkRequest();
request.setFile(new FileItem("/Users/mxh/Downloads/test.png"));
OapiFileUploadChunkResponse response = client.execute(request,accessToken);

返回结果
正确时返回示例如下:

{
    "errcode":0,
    "errmsg":"ok"
}
参数 说明
errcode 错误码
errmsg 错误信息

提交文件上传事务

文件分块上传最后一步,提交本次分块上传事务,默认情况下,系统会删除超过 24 小时没有提交的分块文件上传事务。

请求方式:GET(HTTPS)
请求地址https://oapi.dingtalk.com/file/upload/transaction?access_token=ACCESS_TOKEN&agent_id=AGENT_ID&file_size=FILE_SIZE&chunk_numbers=CHUNK_NUMBERS&upload_id=UPLOAD_ID

注意:浏览器可能会转义某些字符导致请求失败,调试时请使用curl或者代码模拟请求。

参数说明

参数 参数类型 必须 说明
access_token String 调用接口凭证
agent_id String 微应用的agentId
file_size Integer 文件大小
chunk_numbers Integer 文件总块数
upload_id String 上传事务id,需要utf-8 urlEncode

SDK请求示例(JAVA)

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/file/upload/transaction");
OapiFileUploadTransactionRequest request = new OapiFileUploadTransactionRequest();
request.setAgentId("135717601");
request.setFileSize(1000L);
request.setChunkNumbers(1L);
request.setUploadId("99F0F6DBB55A4C82822268192B5909F8_0#iAEAAqRmaWxlA6h5dW5kaXNrMATOC7DaowXNCW0GzQlXB85a863FCM4AAXTG");
request.setHttpMethod("GET");
OapiFileUploadTransactionResponse response = client.execute(request,accessToken);�

正确时返回示例如下:

{
    "media_id": "xxxxxxxx",
    "errcode":0,
    "errmsg":"ok"
}
参数 说明
errcode 错误码
errmsg 错误信息
media_id 文件存储id

以上内容是否对您有帮助:
在文档使用中是否遇到以下问题(多选):
  • 内容错误
  • 更新不及时
  • 链接错误
  • 缺少代码/图片示例
  • 太简单/步骤待完善
手机号
更多建议
提交成功,感谢您的反馈!