====== 文件上传下载 ======

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

新版文档地址：[[ccim:rest:message|消息管理]]

----

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

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

----

====== REST API  ======
文件上传下载集成过程中，需要使用到的 REST API 文档详细说明，可以通过使用文档中嵌入的[[http://api-docs.easemob.com/|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 ===

^{{:im:server:basics:post.png?nolink&90|}}^**/{org_name}/{app_name}/chatfiles**^

=== Request Headers ===

^参数^说明^
|restrict-access|true|
|Authorization|Bearer ${token}|

=== Response Body ===

在返回值中查看entities字段包含的信息
^参数^说明^
|uuid|文件唯一ID，指定是哪个文件，发送消息时需要用到|
|type|文件类型|
|share-secret|上传成功后返回，发送消息时需要用到|

=== 请求示例 ===

<code php>
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
</code>

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

=== 可能返回的结果示例 ===

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

<code json>
{
    "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"
}
</code>

**返回值401，未授权[无token、token错误、token过期]**
<code json>
{
  "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"
}
</code>

如果返回结果是<wrap em>429、503</wrap>或者其他<wrap em>5xx</wrap>，有可能代表该接口被限流了，请稍微暂停一下并重试。详见[[im:450errorcode:45restastrict|接口限流说明]]

[[http://api-docs.easemob.com/|使用 Easemob REST API 在线测试]]
----

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

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

=== HTTP Request ===

^{{:im:server:basics:get.png?nolink&90|}}^**/{org_name}/{app_name}/chatfiles/{uuid}**^

=== Request Headers ===

^参数^说明^
|Content-Type|application/json|
|Authorization|Bearer ${token}|
|share-secret|share-secret|

=== 请求示例 ===

<code php>
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'
</code>
=== 可能返回的结果示例 ===

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

<code json>
{
//语音/图片文件信息
}
</code>

**返回值401，未授权[无token、token错误、token过期]**
<code json>
{
  "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"
}
</code>

如果返回结果是<wrap em>429、503</wrap>或者其他<wrap em>5xx</wrap>，有可能代表该接口被限流了，请稍微暂停一下并重试。详见[[im:450errorcode:45restastrict|接口限流说明]]

[[http://api-docs.easemob.com/|使用 Easemob REST API 在线测试]]
----

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

^{{:im:server:basics:get.png?nolink&90|}}^**/{org_name}/{app_name}/chatfiles/{file_uuid}**^
需要在请求时对应填写{file_uuid}，需要获取文件返回的 uuid 。

=== Request Headers ===

^参数^说明^
|Content-Type|application/json|
|Authorization|Bearer ${token}|

=== 请求示例 ===

<code php>
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'
</code>

=== 可能返回的结果示例 ===

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

<code json>
{
//缩略图信息
}
</code>

**返回值401，未授权[无token、token错误、token过期]**
<code json>
{
  "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"
}
</code>

如果返回结果是<wrap em>429、503</wrap>或者其他<wrap em>5xx</wrap>，有可能代表该接口被限流了，请稍微暂停一下并重试。详见[[im:450errorcode:45restastrict|接口限流说明]]

[[http://api-docs.easemob.com/|使用 Easemob REST API 在线测试]]


----
<WRAP group>
<WRAP half column>
上一页：[[im:server:basics:chatrecord|聊天记录]]
</WRAP>

<WRAP half column>
下一页：[[im:server:basics:conferencemanage|会议管理]]
</WRAP>
</WRAP>