文件上传下载

更新时间:2021-12-31 该文档已不再维护,请看新版 3.X 文档。

新版文档地址:消息管理


环信使用 REST 的方式来实现语音和图片等文件的上传下载。同时,为了保证聊天文件的安全,我们的 API 保证了以下几点:

  • 只有 APP 的登录用户才能够上传文件。
  • 在上传文件的时候可以选择是否限制访问权限。
  • 如果选择限制的话,会在上传请求完成后返回一个 secret,只有知道这个 secret,并且是 APP 的注册用户,才能够下载文件。
  • 如果选择不限制的话,则只要是 APP 的注册用户就能够下载。
  • 如选择加secert限制的话,消息回调(包含发送前回调和发送后回调)、历史消息这些功能中涉及下载文件时,都需要在下载url中拼接secert,才能正常下载文件
  • 拼接规则如下:
{{url}}?share-secret={{secret}}
    

REST API

文件上传下载集成过程中,需要使用到的 REST API 文档详细说明,可以通过使用文档中嵌入的Easemob REST API进行在线测试。

名称请求描述
上传语音/图片文件/{org_name}/{app_name}/chatfiles上传语音/图片文件
下载语音/图片文件{org_name}/{app_name}/chatfiles/{filestream}下载语音/图片文件
下载缩略图/{org_name}/{app_name}/chatfiles/{file_uuid}下载缩略图

注意:上传文件大小不能超过 10M,超过会上传失败。 所需要的 HTTP Header: * Authorization – 获取到的token * restrict-access – 是否限制访问权限。 注意:这个 API 并没有考虑这个属性的值,而是有这个属性即可。最后,需要使用 HTTP multipart/form-data 形式。

HTTP Request

/{org_name}/{app_name}/chatfiles

Request Headers

参数说明
restrict-accesstrue
AuthorizationBearer ${token}

Response Body

在返回值中查看entities字段包含的信息

参数说明
uuid文件唯一ID,指定是哪个文件,发送消息时需要用到
type文件类型
share-secret上传成功后返回,发送消息时需要用到

请求示例

curl -X POST https://a1.easemob.com/easemob-demo/testapp/chatfiles -H 'Authorization: Bearer YWMtS1pRuFa-EemixAMhJgmGUAAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFp57yd7QBPGgDNLstNggrzgHV3JAbqbznTptqLhpG0fTOCaBFJZgduZA' -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW'  -H 'restrict-access: true' -F file=@/Users/test/9.2/Easemob/image/IMG_2953.JPG

注意:上述请求示例中-F file=@/Users/test/9.2/Easemob/image/IMG_2953.JPG,为环信本地文件路径,使用时请替换为自己的文件路径,否则会请求失败。

可能返回的结果示例

返回值200,表示成功上传文件

{
    "action": "post",
    "application": "8be024f0-e978-11e8-b697-5d598d5f8402",
    "path": "/chatfiles",
    "uri": "https://a1.easemob.com/easemob-demo/testapp/chatfiles",
    "entities": [
        {
            "uuid": "5fd74830-56be-11e9-822a-81ea50bb049d",
            "type": "chatfile",
            "share-secret": "X9dIOla-EemnFYUgtUZLGyqG9Y-S01eL_ysw27NqTV1_g7Yc"
        }
    ],
    "timestamp": 1554371126338,
    "duration": 0,
    "organization": "easemob-demo",
    "applicationName": "testapp"
}

返回值401,未授权[无token、token错误、token过期]

{
  "error": "auth_bad_access_token",
  "timestamp": 1542348025595,
  "duration": 0,
  "exception": "org.apache.usergrid.rest.exceptions.SecurityException",
  "error_description": "Unable to authenticate due to corrupt access token"
}

如果返回结果是429、503或者其他5xx,有可能代表该接口被限流了,请稍微暂停一下并重试。详见接口限流说明

使用 Easemob REST API 在线测试


这里需要注意的就是,需要在 HTTP header 中带上上面返回的 share-secret 和当前登录用户的 token 才能够下载,同时注意 header 中执行的 accept 的值需要设置成 application/octet-stream。

uuid 和 share-secret 在文件上传成功后会返回。

HTTP Request

/{org_name}/{app_name}/chatfiles/{uuid}

Request Headers

参数说明
Content-Typeapplication/json
AuthorizationBearer ${token}
share-secretshare-secret

请求示例

curl -X GET -H 'Accept: application/octet-stream' -H 'Authorization: Bearer YWMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw' -H 'share-secret: f0Vr-uyyEeiHpHmsu53Togur4ngZYgyLkdfsZ4xo2Z0cSBnB' 'http://a1.easemob.com/easemob-demo/testapp/chatfiles/7f456bf0-ecb2-11e8-b630-777db304f26c'

可能返回的结果示例

返回值200,表示下载文件成功

{
//语音/图片文件信息
}

返回值401,未授权[无token、token错误、token过期]

{
  "error": "auth_bad_access_token",
  "timestamp": 1542349596366,
  "duration": 0,
  "exception": "org.apache.usergrid.rest.exceptions.SecurityException",
  "error_description": "Unable to authenticate due to corrupt access token"
}

如果返回结果是429、503或者其他5xx,有可能代表该接口被限流了,请稍微暂停一下并重试。详见接口限流说明

使用 Easemob REST API 在线测试


环信支持在服务器端自动的创建图片的缩略图。可以先下载缩略图,当用户有需求的时候,再下载大图。 这里和下载大图唯一不同的就是 header 中多了一个“thumbnail: true”,当服务器看到过来的请求的 header 中包括这个的时候,就会返回缩略图,否则返回原始大图。

HTTP Request

/{org_name}/{app_name}/chatfiles/{file_uuid}

需要在请求时对应填写{file_uuid},需要获取文件返回的 uuid 。

Request Headers

参数说明
Content-Typeapplication/json
AuthorizationBearer ${token}

请求示例

curl -X GET -H 'Accept: application/octet-stream' -H 'Authorization: Bearer YWMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw' -H 'share-secret: f0Vr-uyyEeiHpHmsu53Togur4ngZYgyLkdfsZ4xo2Z0cSBnB' -H 'thumbnail: true' 'http://a1.easemob.com/easemob-demo/testapp/chatfiles/7f456bf0-ecb2-11e8-b630-777db304f26c'

可能返回的结果示例

返回值200,表示下载缩略图成功

{
//缩略图信息
}

返回值401,未授权[无token、token错误、token过期]

{
  "error": "auth_bad_access_token",
  "timestamp": 1542350943210,
  "duration": 0,
  "exception": "org.apache.usergrid.rest.exceptions.SecurityException",
  "error_description": "Unable to authenticate due to corrupt access token"
}

如果返回结果是429、503或者其他5xx,有可能代表该接口被限流了,请稍微暂停一下并重试。详见接口限流说明

使用 Easemob REST API 在线测试


上一页:聊天记录

下一页:会议管理