API 参考
圈组

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有效期5 分钟(用CurTime计算),建议每次请求都生成新的CheckSum,同时请确认发起请求的服务器是与标准时间同步的,比如有NTP服务。
  • CheckSum检验失败时会返回 414 错误码,更多错误码信息请参见状态码
  • 请妥善保管用于计算CheckSumAppSecret,可在应用服务器存储和使用,但不应存储或传递到客户端,也不应在网页等前端代码中嵌入。
  • 由于网络原因,网易云信服务器可能会重复请求,开发者请注意进行去重操作。

CheckSum计算示例

计算CheckSum的示例代码如下:

Java
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' };
}
Node.js
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。表示调用异常的具体状态码及相应的排查指引请参见状态码

状态码的含义均为开放式,不同接口返回的相同状态码,含义可能略有不同。因此不建议您针对状态码开发业务逻辑。如果对状态码存在依赖,会有风险。

此文档是否对你有帮助?
有帮助
去反馈
  • 请求概述
  • 请求头(Header)
  • Header参数
  • CheckSum计算示例
  • 请求体(Body)
  • 返回结果