API 调用方式
更新时间: 2024/07/17 17:57:35
应用服务端调用 API 向云信 IM 服务端发起的请求需遵循固定的请求结构和请求方式。
请求概述
-
通信协议:IM 服务端 API 是简单的 HTTP/HTTPS 接口,适配各种语言。
-
请求方式:应用服务端向 IM 服务端发起的所有请求都只支持 POST 方式。
-
服务地址:网易云信 IM 服务端 API 的接入地址为
https://api.netease.im/nimserver
。上述接入地址的域名(
api.netease.im
)属于国内数据中心域名。如果您的应用主要服务于海外用户,需将域名设置为海外数据中心域名(api-sg.netease.im
),相应的海外接入地址为https://api-sg.netease.im/nimserver
。更多海外数据中心接入相关说明,请参见接入海外数据中心。 -
请求结构:IM 服务端 API 请求结构主要由下表所示三部分组成。
组成部分说明 URL 指向具体的业务请求,请参见各 API 文档
注意: 如果您的应用主要服务于海外用户,需将 URL 中的国内数据中心域名(api.netease.im
)替换为海外数据中心域名(api-sg.netease.im
)Header 请求头,包含云信 App Key、CheckSum 等在内的公共请求参数,用于鉴权。应用服务端请求 IM 服务端的所有 API 调用均采用相同的 Header 公共请求参数配置 Body 请求体,包含 API 对应的业务参数,具体参见各 API 文档的请求参数小节
请求头(Header)
调用 IM 服务端 API 的请求,都需要在 Header 中传入CheckSum
进行鉴权。
Header参数
Header 参数为公共请求参数,应用服务端请求云信 IM 服务端,都需在Header 中配置如下参数。
参数 |
参数说明 |
---|---|
AppKey |
通过云信控制台获取,详见获取 AppKey 和 AppSecret。 |
Nonce |
随机数(最大长度 128 个字符) |
CurTime |
当前 UTC 时间戳,从 1970 年 1 月 1 日 0 时 0 分 0 秒开始到 现在(指发起请求瞬间的前后 5 分钟内)的秒数(类型为 String) |
CheckSum |
SHA1(AppSecret + Nonce + CurTime),将该三个参数拼接的字符串进行 SHA1 哈希计算从而生成 16 进制字符(类型为 String,小写)
|
- 请妥善保管用于计算
CheckSum
的AppSecret
,可在应用服务器存储和使用,但不应存储或传递到客户端,也不应在网页等前端代码中嵌入。 - 由于网络原因,网易云信服务器可能会重复请求,开发者请注意进行去重操作。
`RequestId`:(可选)请求的唯一标识,即相同的 `RequestId` 表示同一个请求。随机数,最大长度 128 位字符。
- `RequestId` 字段是用来防止服务端接口被重复调用,为非必填参数,服务器所有接口都支持此功能。
- 去重原理:当同一个用户(`AppKey` 相同)在 60 秒内访问同一个接口,并且 `RequestId` 相同,则服务端认为是重复请求,为了防止服务端重复处理,对业务造成影响(如重发消息),服务端会直接返回上次保存在缓存中的结果(重复访问的响应体中会增加 `duplicate=true`的标识),而不做重复业务处理,需要注意的是服务端只缓存 `code=200` 的结果,对于状态码为 3XX、4XX、5XX 的结果不进行缓存。
- 适用场景:客户应用服务器调用云信服务端接口超时需要重试的场景(可以在 `HttpHeader` 中增加 `RequestId` 字段,重试请求的 `RequestId` 字段的值需与之前保持一致)。
CheckSum计算示例
计算CheckSum
的示例代码如下:
javaimport java.security.MessageDigest;
public class CheckSumBuilder {
// 计算并获取CheckSum
public static String getCheckSum(String appSecret, String nonce, String curTime) {
return encode("sha1", appSecret + nonce + curTime);
}
// 计算并获取md5值
public static String getMD5(String requestBody) {
return encode("md5", requestBody);
}
private static String encode(String algorithm, String value) {
if (value == null) {
return null;
}
try {
MessageDigest messageDigest
= MessageDigest.getInstance(algorithm);
messageDigest.update(value.getBytes());
return getFormattedText(messageDigest.digest());
} catch (Exception e) {
throw new RuntimeException(e);
}
}
private static String getFormattedText(byte[] bytes) {
int len = bytes.length;
StringBuilder buf = new StringBuilder(len * 2);
for (int j = 0; j < len; j++) {
buf.append(HEX_DIGITS[(bytes[j] >> 4) & 0x0f]);
buf.append(HEX_DIGITS[bytes[j] & 0x0f]);
}
return buf.toString();
}
private static final char[] HEX_DIGITS = { '0', '1', '2', '3', '4', '5',
'6', '7', '8', '9', 'a', 'b', 'c', 'd', 'e', 'f' };
}
const { SHA1 } = require("crypto-js");
function randString(x) {
let s = "";
while (s.length < x && x > 0) {
const v = Math.random() < 0.5 ? 32 : 0;
s += String.fromCharCode(
Math.round(Math.random() * (122 - v - (97 - v)) + (97 - v))
);
}
return s;
}
const [Nonce, CurTime] = [randString(20), new Date().getTime().toString().slice(0, 10)]
function CheckSum(AppSecret, Nonce, CurTime) {
return SHA1(AppSecret + Nonce + CurTime);
}
请求体(Body)
传入 Body 的具体业务参数请参见各 API 文档。以注册云信 IM 账号为例,对应的业务参数配置说明请参见注册云信IM账号。同时请求头的Content-Type
类型均为application/x-www-form-urlencoded;charset=utf-8
。
请求参数(即传入 Body 的具体业务参数)无论为何类型,实际传入时都需要转为 String 格式,否则将报错。具体的案例请参见新手指南中的常见问题。
返回结果
调用 IM 服务端 API 的返回类型均为 JSON,同时进行 UTF-8 编码。
如调用成功,则返回状态码200
。表示调用异常的具体状态码及相应的排查指引请参见状态码。
状态码的含义均为开放式,不同接口返回的相同状态码,含义可能略有不同。因此不建议您针对状态码开发业务逻辑。如果对状态码存在依赖,会有风险。