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

请求概述

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

• 请求方式：应用服务端向 IM 服务端发起的请求支持 POST、PATCH、GET、DELETE 方式。

• 服务地址：网易云信 IM 服务端 API 的接入地址为 https://open.yunxinapi.com/。

  上述接入地址的域名（open.yunxinapi.com）属于国内数据中心域名。如果您的应用主要服务于海外用户，需将域名设置为海外数据中心域名（open-sg.yunxinapi.com），相应的海外接入地址为 https://open-sg.yunxinapi.com/。更多海外数据中心接入相关说明，请参见接入海外数据中心。

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

  组成部分	说明
  URL	指向具体的业务请求，请参见各 API 文档
  Header	请求头，包含云信 App Key、CheckSum 等在内的公共请求参数，用于鉴权。应用服务端请求 IM 服务端的所有 API 调用均采用相同的 Header 公共请求参数配置
  Body	请求体，包含 API 对应的业务参数，具体参见各 API 文档的请求参数小节

请求 URL

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

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

请求 Header

调用 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

传入 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=accid1%2Caccid2%2Caccid3

请求体参数

• 请求体的数据类型为 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。表示调用异常的具体错误码及相应的排查指引。

响应 Header

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

响应 Body

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

错误码

服务端 API 中分别列了涉及的错误码。

注意说明

对于 GET 请求，若需要查询获取多个资源信息，可以使用批量接口或分页接口。

分页接口

• 分页查询必须提供 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=accid1,accid2,accid3。

批量资源响应参数：

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

• success_list：成功请求的对象列表。
• failed_list：单个失败的原因列表，每个失败原因包含三个部分：错误请求的 id，error_code，error_msg。