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

新版文档地址：消息管理

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

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

{{url}}?share-secret={{secret}}
    

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

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

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

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 在文件上传成功后会返回。

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 中包括这个的时候，就会返回缩略图，否则返回原始大图。

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

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

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 在线测试