API调用方式 - IM 即时通讯

IM 即时通讯

API 参考

群组

高级群

聊天室

圈组

更新时间： 2023/03/15 14:36:14

应用服务端调用 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 文档的请求参数小节

调用 IM 服务端 API 的请求，都需要在 Header 中传入CheckSum进行鉴权。

Header 参数为公共请求参数，应用服务端请求云信 IM 服务端，都需在Header 中配置如下参数。

参数	参数说明
`AppKey`	通过云信控制台获取，详见获取 App key
`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 错误码，更多错误码信息请参见状态码。

请妥善保管用于计算CheckSum的AppSecret，可在应用服务器存储和使用，但不应存储或传递到客户端，也不应在网页等前端代码中嵌入。

CheckSum计算示例

计算CheckSum的示例代码如下：

Java

import 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);
}