圈组

API 调用方式

更新时间: 2025/05/30 10:55:40

应用服务端调用 API 向网易云信 IM 服务端发起的请求需遵循固定的请求结构和请求方式。

请求概述

应用服务端调用 API 向网易云信 IM 服务端发起的请求需遵循固定的请求结构和请求方式。

sequenceDiagram
    autonumber
    participant app as 应用服务器
    participant server as 网易云信 IM 服务端

    app->>server: HTTPS 请求
    Note over app,server: 请求体(请求参数)<br>请求头(CheckSum 及其他公共参数)
    server->>server: 校验通过
    server-->>app: 响应信息(JSON 数据,UTF-8 编码)

请求方式

  • 通信协议:IM 服务端 API 是简单的 HTTP/HTTPS 接口,适配各种语言。

  • 请求方式:应用服务端向 IM 服务端发起的所有请求都只支持 POST 方式。

服务地址

为保障业务稳定性,网易云信 IM 服务提供了主备域名机制。当主域名发生故障时,您可以使用备用域名继续访问 API 服务。有关海外业务接入相关说明,请参考 接入海外数据中心

服务区域 主域名 备用域名
国内 api.yunxinapi.com api-cn-bak.yunxinapi.com
海外 api-sg.yunxinapi.com api-sg-bak.yunxinapi.com

为确保服务的高可用性,网易云信建议:

  • 配置多域名访问:在业务系统中同时配置主备域名,当检测到主域名无法访问时,自动切换至备用域名。

  • 使用 SDK 自动切换功能:如果您使用 Java 开发语言,强烈建议通过网易云信提供的 Server SDK 接入,该 SDK 已内置多域名自动故障切换能力,无需您手动实现域名切换逻辑。

  • 定期检查域名可用性:建议在应用中实现定期检查域名可用性的机制,以便及时发现并应对可能的域名访问问题。

请求结构

IM 服务端 API 请求结构主要由下表所示三部分组成。

组成部分
说明
URL 指向具体的业务请求,请参考各 API 文档。 如果您的应用主要服务于海外用户,需将 URL 中的国内数据中心域名(api.yunxinapi.com)替换为海外数据中心域名(api-sg.yunxinapi.com)。详情请参考上文 服务地址
Header 请求头,包含网易云信 App Key、CheckSum 等在内的 公共请求参数,用于鉴权。应用服务端请求 IM 服务端的所有 API 调用均采用 相同 的 Header 公共请求参数配置
Body 请求体,包含 API 对应的业务参数,具体参考各 API 文档的 请求参数 小节

请求头参数

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

参数名称 类型 是否必选 描述
AppKey String 通过网易云信控制台获取,请参考 获取 App key
Nonce String 随机数(最大长度 128 个字符)。
CurTime String 当前 UTC 时间戳,从 1970 年 1 月 1 日 0 时 0 分 0 秒开始到 现在 的秒数。该时间用于计算 CheckSum 的有效期,请确保与标准时间同步。
CheckSum String SHA1(AppSecret + Nonce + CurTime),将该三个参数拼接的字符串进行 SHA1 哈希计算从而生成 16 进制字符(小写)。
  • 出于安全性考虑,每个 CheckSum有效期5 分钟,即服务端接收到请求的时间与请求中的 CurTime 相差不能超过 5 分钟,建议每次请求都生成新的 CheckSum,同时 请确认 发起请求的服务器是与标准时间同步的,例如有 NTP 服务。
  • CheckSum 检验失败时会返回 414 错误码。更多错误码信息请参考 状态码
Content-Type String 请求体的数据类型,类型均为 application/x-www-form-urlencoded;charset=utf-8

CheckSum 计算示例

调用 IM 服务端 API 的请求,都需要在请求头(Header)中传入 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
JavaScriptconst { 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);
}
  • 请妥善保管用于计算 CheckSumAppSecret,可在应用服务器存储和使用,但不应存储或传递到客户端,也不应在网页等前端代码中嵌入。
  • 由于网络原因,网易云信服务器可能会重复请求,开发者请注意进行去重操作。

请求体参数

传入请求体(Body)的 具体业务参数 请参考各 API 文档。以注册 IM 账号为例,对应的业务参数配置说明请参考 注册 IM 账号

请求参数(即传入 Body 的具体业务参数)无论为何类型,实际传入时都需要转为 String 格式,否则将报错。具体的案例请参考 新手指南中的常见问题

响应概述

调用 IM 服务端 API 的返回类型均为 JSON,同时进行 UTF-8 编码。

如调用成功,则返回状态码 200。表示调用异常的具体状态码及相应的排查指引请参考 状态码

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

此文档是否对你有帮助?
有帮助
去反馈
  • 请求概述
  • 请求方式
  • 服务地址
  • 请求结构
  • 请求头参数
  • CheckSum 计算示例
  • 请求体参数
  • 响应概述