请求结构 - NERoom 房间组件

开发者中心

NERoom 房间组件

服务端 API

请求结构

更新时间： 2024/11/04 15:22:15

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

请求概述

服务端请求流程.png

通信协议：NERoom 服务端 API 使用 HTTP 或者 HTTPS 网络请求协议。
请求方式：应用服务端向 NERoom 服务端发起的所有请求都支持 POST、 PUT、GET等方式。
服务地址：网易云信 NERoom 服务端 API 的接入地址为 https://roomkit.netease.im。

上述服务地址的域名（roomkit.netease.im）属于国内数据中心域名。如果您的应用主要服务于海外用户，需将域名设置为海外数据中心域名（roomkit-sg.netease.im）。

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

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

每篇 API 文档均给出了请求示例供您参考，请在发起请求前自行编码。接口调用成功会显示返回参数，调用失败则显示相应报错，您可以根据错误码分析排查。

参数名称	类型	是否必选	示例	描述
AppKey	String	是	b2e***fcc155e7d26c4	网易云信控制台为应用分配的 AppKey。获取方法请参见创建应用并获取 AppKey。
Nonce	String	是	8dfdb33d2840	随机数，最大长度 128 个字符。
CurTime	String	是	1443592222	当前UTC时间戳，从 1970 年 1 月 1 日 0 点 0 分0 秒开始到现在（指发起请求瞬间的前后 5 分钟内）的秒数。数据类型为 String。
CheckSum	String	是	b404199cdb06d20xxxdc61016d	CheckSum = sha1(AppSecret + Nonce + CurTime)。将 AppSecret、Nonce 和 CurTime 三个参数拼接的字符串经过 SHA1 哈希计算，并将结果转化成 16 进制字符。CheckSum 的值为 String 格式，小写。出于安全性考虑，每个 CheckSum 的有效期为 CurTime 时间开始之后的 5 分钟内。建议每次请求都生成新的 CheckSum，同时请确认发起请求的服务器与标准时间同步，例如 NTP 服务。 CheckSum 检验失败时会返回 401 错误码，更多错误码信息请参见错误码。

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

CheckSum 计算

您可以参考以下代码计算 CheckSum：

Java

javaimport java.security.MessageDigest;
import java.nio.charset.StandardCharsets;

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(StandardCharsets.UTF_8));
            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);
}

字符编码

请求及返回结果均使用 UTF-8 字符集编码。

此文档是否对你有帮助？

有帮助

去反馈

请求概述
Header
CheckSum 计算
字符编码

请求概述

Header

CheckSum 计算

字符编码