上传和下载文件

大约 10 分钟

上传和下载文件

对于附件类型的消息，如图片、语音、视频或其他类型文件，发送消息前需上传文件。你可以将文件上传到自己的服务器，也可以上传至环信服务器。若你将文件上传至自己的服务器，需注意以下两点：

  • 对于图片，发送图片消息时不存在图片缩略图。这是因为图片上传至环信服务器时，环信服务器会自动生成缩略图，发送图片消息时无需传入缩略图 URL 地址。
  • 对于视频，你需要将视频和缩略图均上传至你的服务器，发送视频消息时需传入这两个文件的 URL 地址。

本文介绍如何调用 RESTful API 将文件上传到环信服务器、下载图片、语音、视频或其他类型的文件以及下载图片和视频文件的缩略图。

前提条件

要调用环信即时通讯 REST API，请确保满足以下要求：

公共参数

请求参数

参数类型是否必需描述
hostString是环信即时通讯 IM 分配的用于访问 RESTful API 的域名。详见 获取环信即时通讯 IM 的信息。
org_nameString是环信即时通讯 IM 为每个公司（组织）分配的唯一标识。详见 获取环信即时通讯 IM 的信息。
app_nameString是你在环信即时通讯云控制台创建应用时填入的应用名称。详见 获取环信即时通讯 IM 的信息。

响应参数

参数类型描述
actionString请求方法。
organizationString环信即时通讯 IM 为每个公司（组织）分配的唯一标识，与请求参数 org_name 相同。
applicationString应用在系统内的唯一标识。该标识由系统生成，开发者无需关心。
applicationNameString你在环信即时通讯云控制台创建应用时填入的应用名称，与请求参数 app_name 相同。
uriString请求 URL。
pathString请求路径，属于请求 URL 的一部分，开发者无需关注。
entitiesJSON响应实体。
timestampLongHTTP 响应的 Unix 时间戳，单位为毫秒。
durationInt从发送 HTTP 请求到响应的时长，单位为毫秒。

认证方式

环信即时通讯 REST API 要求 Bearer HTTP 认证。每次发送 HTTP 请求时，都必须在请求头部填入如下 Authorization 字段：

Authorization: Bearer YourAppToken

为提高项目的安全性，环信使用 Token（动态密钥）对即将登录即时通讯系统的用户进行鉴权。本文涉及的所有消息管理 REST API 都需要使用 App Token 的鉴权方式，详见 使用 App Token 鉴权。

上传文件

对于附件类型的消息，如图片、语音、视频或其他类型文件，发送消息前需上传文件。图片和视频存在缩略图，文件上传详情如下：

  • 图片：可调用文件上传接口上传原图，环信服务器会自动为图片生成缩略图。若上传的图片在 10 KB 以内，缩略图与原图等同；若图片超过 10 KB，环信服务器会根据你在请求中设置的图片高度和宽度，即 thumbnail-height 和 thumbnail-width 参数，生成缩略图。若这两个参数未传，则图片的高度和宽度均默认为 170 像素。
  • 视频：环信服务器不会自动为视频文件生成缩略图。若需要视频缩略图，需先调用文件上传接口上传缩略图。然后，再次调用文件上传接口上传视频源文件。上传视频文件时，无需传 thumbnail-height 和 thumbnail-width 参数。上传视频缩略图时，若图片在 10 KB 以内，视频缩略图即为上传的图片。如果图片超过 10 KB，而且设置了这两个参数，视频缩略图的高度和宽度取决于这两个参数的设置。若这两个参数未传，则图片的高度和宽度均默认为 170 像素。

同时，为了保证聊天文件的安全，我们的 API 保证了以下几点：

  • 上传文件的大小不能超过 10 MB，超过会上传失败。
  • 支持对上传的文件限制访问。要使用该功能，请联系商务开通。该功能开启后，你需要从文件上传响应中返回的 share-secret 通过密钥才能下载被限制访问的文件。消息回调（包含发送前回调和发送后回调）和获取历史消息涉及下载文件时，都需要在下载 URL 中拼接密钥，才能正常下载文件，拼接规则为：{{url}}?share-secret={{secret}}。

HTTP 请求

POST https://{host}/{org_name}/{app_name}/chatfiles

路径参数

参数及说明详见 公共参数。

请求 header

参数类型是否必需描述
Content-TypeString否内容类型： multipart/form-data。上传文件会自动填充该请求头。
AuthorizationString是App 管理员的鉴权 token，格式为 Bearer YourAppToken，其中 Bearer 为固定字符，后面为英文空格和获取到的 app token。
restrict-accessBool否是否限制访问该文件：
- true：是。用户需要通过响应 body 中获取的文件访问密钥（share-secret）才能下载该文件。
- false：否。表示不限制访问。用户可以直接下载该文件。

提示

要使用文件访问限制功能，请联系商务开通。

请求 body

参数类型是否必需描述
fileString是文件本地路径。
thumbnail-heightInt否缩略图的高度，单位为像素。
- 若上传的原图或视频缩略图小于 10 KB，上传的图片即为缩略图。
- 若上传的图片超过 10 KB，缩略图的高度取决于该参数的设置。
- 若不传该参数，缩略图的高度默认为 170 像素。你也可以在 环信即时通讯控制台open in new window的 服务概览 页面的 设置 区域修改该默认值。
thumbnail-widthInt否缩略图的宽度，单位为像素。
- 若上传的原图或视频缩略图小于 10 KB，图片原图即为缩略图。
- 若上传的图片超过 10 KB，缩略图的宽度取决于该参数的设置。
- 若不传该参数，缩略图的宽度默认为 170 像素。你也可以在 环信即时通讯控制台open in new window的 服务概览 页面的 设置 区域修改该默认值。

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200，表示请求成功，响应包体中包含以下字段：

参数类型描述
entitiesJSON Array响应数据。
- uuidString文件 ID，即时通讯服务分配给该文件的唯一标识符。该参数在发送消息时需用到。
- typeString文件类型，为固定值 chatfile。
- share-secretString文件访问密钥。你需要自行保存 share-secret，以便 下载文件时使用。

其他参数及说明详见 公共参数。

如果返回的 HTTP 状态码非 200，表示请求失败。你可以参考 响应状态码 了解可能的原因。

示例

请求示例

# 将 <YourAppToken> 替换为你在服务端生成的 App Token，将 file 的路径替换为待上传文件所在的本地完整路径
curl L -X POST 'https://XXXX/XXXX/XXXX/chatfiles'  \
-H 'Authorization: Bearer <YourAppToken>'   \
-H 'Content-Type: multipart/form-data; boundary=---WebKitFormBoundary7MA4YWxkTrZu0gW'   \
-H 'restrict-access: true'   \
-F 'file="@/Users/test/9.2/easemob/image/IMG_2953.JPG"'

响应示例

{
  "action": "post",
  "application": "8be024f0-XXXX-XXXX-b697-5d598d5f8402",
  "path": "/chatfiles",
  "uri": "https://XXXX/XXXX/XXXX/chatfiles",
  "entities": [
    {
      "uuid": "5fd74830-XXXX-XXXX-822a-81ea50bb049d",
      "type": "chatfile",
      "share-secret": "X9dXXXX7Yc"
    }
  ],
  "timestamp": 1554371126338,
  "duration": 0,
  "organization": "XXXX",
  "applicationName": "XXXX"
}

下载文件

你可利用该方法下载图片、语音、视频或其他类型的文件。

提示

如果上传文件时设置了文件访问限制（restrict-access 设置为 true），需要在下载请求头中包含文件上传响应中返回的 share-secret 和当前登录用户的 token 才能下载文件。

HTTP 请求

GET https://{host}/{org_name}/{app_name}/chatfiles/{file_uuid}

路径参数

参数类型是否必需描述
file_uuidString是服务器为文件生成的 UUID。

其他参数及描述详见 公共参数。

请求 header

参数类型是否必需描述
AcceptString是内容类型。请填 application/octet-stream，表示下载二进制数据流格式的文件。
AuthorizationString是App 管理员的鉴权 token，格式为 Bearer YourAppToken，其中 Bearer 为固定字符，后面为英文空格和获取到的 app token。
share-secretString否文件访问密钥。若上传文件时限制了访问，下载该文件时则需要该访问密钥。成功上传文件后，从 文件上传 的响应 body 中获取该密钥。

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200，表示请求成功。参数及说明详见 公共参数。

如果返回的 HTTP 状态码非 200，表示请求失败。你可以参考 响应状态码 了解可能的原因。

示例

请求示例

以下载图片为例：

# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -X GET -H 'Accept: application/octet-stream' -H 'Authorization: Bearer <YourAppToken>' -H 'share-secret: f0Vr-uyyEeiHpHmsu53XXXXXXXXZYgyLkdfsZ4xo2Z0cSBnB' 'https://XXXX/XXXX/XXXX/chatfiles/7f456bf0-XXXX-XXXX-b630-777db304f26c'-o /Users/test/easemob/image/image.JPG

提示

上述请求示例中，/Users/test/easemob/image/image.JPG 为环信即时通讯 IM 的本地文件路径，使用时请替换为自己的文件路径，否则会请求失败。

响应示例

{
  //语音/图片文件内容
}

下载缩略图

收到图片或视频消息，你可以先下载图片或视频的缩略图，需要时再下载图片或视频原文件。下载缩略图与下载原文件的唯一区别是前者在请求 header 中多了 thumbnail: true。当服务器收到包含该字段的请求 header 时，返回缩略图，否则返回原文件。

HTTP 请求

GET https://{host}/{org_name}/{app_name}/chatfiles/{file_uuid}

路径参数

参数类型是否必需描述
file_uuidString是服务器为缩略图文件生成的 UUID。

其他参数及说明详见 公共参数。

请求 header

参数类型是否必需描述
AcceptString是内容类型。请填 application/octet-stream，表示下载二进制数据流格式的文件。
AuthorizationString是App 管理员的鉴权 token，格式为 Bearer YourAppToken，其中 Bearer 为固定字符，后面为英文空格和获取到的 app token。
thumbnailBool否是否下载缩略图：
  • true：是，下载缩略图。
  • false：否，下载原文件。

注意

若该参数为空，下载原文件。

share-secretString否缩略图访问密钥。若上传图片时限制了访问（restrict-access 设置为 true），下载缩略图时则需要该访问密钥。成功上传图片后，从 文件上传 的响应 body 中获取该密钥。

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200，表示请求成功。参数及描述详见 公共参数。

如果返回的 HTTP 状态码非 200，表示请求失败。你可以参考 响应状态码 了解可能的原因。

示例

请求示例

# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -X GET -H 'Accept: application/octet-stream' -H 'Authorization: Bearer <YourAppToken>' -H 'share-secret: f0Vr-uyyEeiHpHmsu53XXXXXXXXZYgyLkdfsZ4xo2Z0cSBnB' -H 'thumbnail: true' 'https://XXXX/XXXX/XXXX/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"
}