应用服务端调用 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、PATCH、GET、DELETE 方式。

服务地址

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

请求结构

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

请求 URL

请求 URL 路径遵循 RESTFUL 原则，围绕资源定义接口路径，通过 HTTP/HTTPS 方法类型来区分接口的 增删改查 行为。此外，一些向前兼容的接口允许在 URL 中添加 action 进行标注。

当前支持 POST、GET、PATCH、DELETE 四种操作类型的接口，对应资源的增删改查操作。

请求头

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

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

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' };
}

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

请求体

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

路径参数

当接口中有路径参数定义时，才添加路径参数。

路径参数一般表示该资源集合下的单个资源 ID，如：账号 ID、聊天室 ID。

查询参数

• GET、DELETE 请求必须使用查询参数，不能使用请求体参数。
• 查询参数为 key-value 形式，没有二级结构。所有参数和值需要经过 url 编码。
• 分页查询提供 page_token/offset、limit 两个分页查询参数（请参考分页接口说明）。
• 当查询参数出现 Array 类型时，每个参数以逗号进行拼接，如 https://open.yunxinapi.com/im/v2/accounts?account_ids=account1%2Caccount2。

请求体参数

• 请求体的数据类型为 Content-Type=application/json; charset=utf-8。
• 请求体参数一般用于 POST、PATCH 请求，GET、DELETE 请求禁止使用。
• Array 类型的参数需要以 JSONArray 的形式接收。
• 参数格式为 JSON 格式，如果接口参数较多，并且具有结构信息，使用二级结构表示。
• 一些 JSON 格式但是内容可自定义的参数定义为 String 类型，要求 JSON 格式。传参时需要添加引号，例如：{payload:"{\"pushTitle\":\"title\"}"}。主要涉及以下参数：
  • push_payload
  • antispam_bussiness_id
  • antispam_extension
  • antispam_custom_message
  • antispam_cheating

响应概述

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

如调用成功，则返回状态码 200。如调用异常，则会返回相应的错误码，请参考各 API 文档中的错误码部分。

响应头

响应头（Header）参数为 公共请求参数，应用服务端请求网易云信 IM 服务端后，网易云信服务端会返回结果，响应的 Header 包括参数。

响应体

响应体（Body）中的响应参数包括返回码（code）、错误描述（msg）和响应内容（data）。

查询类型说明

分页接口

• 分页查询必须提供 page_token/offset、limit 两个分页查询参数。
  • 当分页接口具有偏移量语义的，使用 offset+limit，并在查询结束后返回下一次查询的 offset。
  • 当分页接口具有标识符语义的，使用 page_token+limit，并在查询结束后返回下一次查询的 next_token。
• page_token 和 offset 返回的是本次查询最后一条记录的位置，page_token 或者 offset 均为非必填参数，为空时，默认从第一条记录开始查询。

分页查询参数：

分页资源响应参数：

其中 has_more、items 必须返回，而 next_token 可以替换为 offset。

批量接口

• 当批量参数在 请求体参数 出现时，参数类型为 Array，以 JSONArray 形式接收。
• 当批量参数在 查询参数 出现时，每个参数值以逗号进行拼接，如 account_ids=account1,account2,account3。

批量资源响应参数：

批量请求下，部分成功，部分失败，或全部失败，都返回 200，内部返回失败列表，失败列表包含每一条错误码（code）与错误信息（msg）。

• success_list：成功请求的对象列表。
• failed_list：单个失败的原因列表，每个失败原因包含三个部分：错误请求的资源标识（如账号 ID、用户 ID 等），error_code，error_msg。

错误码

具体错误码和排查指引请参考各 API 文档中的错误码部分及 错误码。