ZEGO 服务端 API 支持 HTTPS 网络请求协议,允许 GET 或 POST 方法。您可以通过以下方式调用服务端 API:
服务端 API 请求由不同内容构成,有固定的请求结构:
我们根据您的签名验证了请求后,会返回结果给您。接口调用成功会显示返回参数,调用失败则显示相应报错,您可以根据 全局返回码 分析排查。
以下为 StartMix
(开始混流)接口的请求结构为例:
https://rtc-api.zego.im/?Action=StartMix
&AppId=1234567890
&SignatureNonce=15215528852396
&Timestamp=1234567890
&Signature=7a2c0f11145fb760d607a07b54825013
&SignatureVersion=2.0
&IsTest=false
其中:
https
:指定了请求通信协议。rtc-api.zego.im
:指定了 ZEGO 服务端的接入地址。Action=StartMix
:指定了要调用的 API。此外,ZEGO 提供多种编程语言的示例代码,开发者可根据实际情况进行参考。以下是 StartMix
接口的 Node.js 代码:
const crypto = require('crypto');
const request = require('request');
//请将 AppId 修改为你的 appId,appId 为 number
var appId = ;
//请将 serverSecret 修改为你的 serverSecret,serverSecret 为 string
var serverSecret = "";
//Signature=md5(AppId + SignatureNonce + ServerSecret + Timestamp)
function GenerateSignature(appId, signatureNonce, serverSecret, timeStamp) {
const hash = crypto.createHash('md5'); //规定使用哈希算法中的 MD5 算法
var str = appId + signatureNonce + serverSecret + timeStamp;
hash.update(str);
//hash.digest('hex')表示输出的格式为 16 进制
return hash.digest('hex');
}
var signatureNonce = crypto.randomBytes(8).toString('hex');
var timeStamp = Math.round(Date.now() / 1000);
var sig = GenerateSignature(appId, signatureNonce, serverSecret, timeStamp);
//以下示例 将 streamId 为 "stream1" 的音视频流 与 streamId 为 "stream2" 的音视频流进行混流,混出 streamId 为 "stream3" 的音视频流
var url = `https://rtc-api.zego.im/?Action=StartMix&AppId=${appId}&SignatureNonce=${signatureNonce}&Timestamp=${timeStamp}&Signature=${sig}&SignatureVersion=2.0&IsTest=false`;
var body = {
'TaskId': '123',
'Sequence': 123,
'UserId': '123',
'MixInput': [
{
'StreamId': 'stream1',
'RectInfo': {
"Top": 70,
"Bottom": 160,
"Left": 100,
"Right": 260
},
},
{
'StreamId': 'stream2',
'RectInfo': {
"Top": 200,
"Bottom": 290,
"Left": 100,
"Right": 260
},
}
],
'MixOutput': [{
'StreamId': 'stream3',
'Width': 360,
'Height': 360,
'VideoBitrate': 12000,
'Fps': 15
}]
}
request({
url: url,
method: 'POST',
json: true,
headers: {
'content-type': 'application/json'
},
body: body
}, function (error, response, body) {
console.log(error)
console.log(response.statusCode)
if (!error && response.statusCode === 200) {
console.log(body.Data)
}
})
开发者需要根据自己的服务端所在地理区域,指定相应的接入地址,向 ZEGO 服务端发送请求。
为保障您的业务服务接入质量,请优先使用您的服务端所在地理区域的域名,作为接入地址,向 ZEGO 服务端发送请求。
ZEGO 支持如下地理区域的请求接入:
地理区域 | 接⼊地址 |
---|---|
中国⼤陆(上海) |
${PRODUCT}-api-sha.zego.im |
港澳台(⾹港) |
${PRODUCT}-api-hkg.zego.im |
欧洲(法兰克福) |
${PRODUCT}-api-fra.zego.im |
美⻄(加州) |
${PRODUCT}-api-lax.zego.im |
亚太(孟买) |
${PRODUCT}-api-bom.zego.im |
东南亚(新加坡) |
${PRODUCT}-api-sgp.zego.im |
统一接入地址(不区分区域) |
${PRODUCT}-api.zego.im |
其中,${PRODUCT}
为 ZEGO 提供的不同产品的不同服务,对应如下:
产品 | ${PRODUCT} 值 | 接入地址 |
---|---|---|
云通讯服务:
|
rtc | rtc-api.zego.im |
超级白板 |
|
|
|
cloudrecord | cloudrecord-api.zego.im |
ZEGO 服务端 API 的所有接口均通过 HTTPS 进行通信,提供安全的通信服务。
ZEGO 服务端 API 支持以下 HTTP 请求方法:
本节介绍了开发者调用 ZEGO 服务端 API 时使用的公共参数,包含了公共请求参数和公共返回参数。
公共请求参数是每个接口都需要使用到的请求参数。
参数 | 类型 | 是否必填 | 描述 |
---|---|---|---|
AppId |
Uint32 |
是 |
AppId,ZEGO 分配的用户唯一凭证。 |
Signature |
String |
是 |
签名,签名的生成请参考 3 签名机制。 |
SignatureNonce |
String |
是 |
随机字符串。 |
SignatureVersion |
String |
是 |
签名版本号,必须填写为 2.0。 |
Timestamp |
Int64 |
是 |
Unix 时间戳,单位为秒。最多允许 10 分钟的误差。 |
IsTest |
String |
是(2021-11-16 及之前创建的项目) |
是否为测试环境。取值如下:
针对 2021-11-16 及之前在 ZEGO 控制台 创建的项目:
|
否(2021-11-16 之后创建的项目) |
是否为测试环境。默认为正式环境,可忽略不填写。 针对 2021-11-16 之后在 ZEGO 控制台 创建的项目:从控制台申请的 AppId 和 AppSign 等信息都为正式环境。 |
请求示例:
https://rtc-api.zego.im/?Action=ForbidLiveStream
&AppId=1234567890
&SignatureNonce=15215528852396
&Timestamp=1234567890
&Signature=Pc5WB8gokVn0xfeu%2FZV%2BiNM1dgI%3D
&SignatureVersion=2.0
&IsTest=false
开发者可以在 服务端 API 校验 页面中,输入 URL 地址,验证签名信息、公共参数、以及 URL 格式是否合法。
API 返回结果采用统一格式,返回的数据格式为 JSON。
每次调用接口,无论成功与否,都会返回公共参数。
参数 | 类型 | 描述 |
---|---|---|
Code |
Number |
返回码。 |
Message |
String |
操作结果描述。 |
RequestId |
String |
请求 ID。 |
Data |
- |
响应数据。 |
返回示例:
{
"Code":0,
"Data":{
"MessageId":"1_1611647493487_29"
},
"Message":"success",
"RequestId":"2237080460466033406"
}
为保证 API 的安全调用,ZEGO 服务端会对每个 API 的访问请求进行身份验证。开发者在调用 API 时,都需要在请求中包含签名 Signature 信息。
每次调用接口都需要生成新的签名。
Signature 是通过对 AppId 和 ServerSecret 进行 md5 计算,来验证请求的发送者身份。AppId 用于标识访问者的身份,ServerSecret 用于加密签名字符串和服务器验证签名字符串的密钥,必须严格保密,防止泄漏。
开发者可到 ZEGO 控制台 在 “控制台 > 项目管理” 中,查看项目的 AppId;单击项目右侧的“查看”按钮,在 项目配置
中查看 ServerSecret 等信息。
参数 | 含义 |
---|---|
AppId |
应用 ID,即公共参数里的 AppId,从 ZEGO 控制台 获取。 |
SignatureNonce |
随机字符串,即公共参数里的 SignatureNonce,生成算法可参考 3.3 签名示例。 |
ServerSecret |
应⽤密钥,从 ZEGO 控制台 获取。 |
Timestamp |
当前 Unix 时间戳,单位为秒。生成算法可参考下方签名示例,最多允许 10 分钟的误差。 |
Signature = md5(AppId + SignatureNonce + ServerSecret + Timestamp)
签名采⽤ hex 编码(⼩写),⻓度为 32 个字符。
ZEGO 提供多种编程语言的签名示例代码,开发者可根据实际情况进行参考。
import (
"crypto/md5"
"crypto/rand"
"encoding/hex"
"fmt"
"log"
"time"
)
// Signature=md5(AppId + SignatureNonce + ServerSecret + Timestamp)
func GenerateSignature(appId uint32, signatureNonce string, serverSecret string, timestamp int64) (Signature string){
data := fmt.Sprintf("%d%s%s%d", appId, signatureNonce, serverSecret, timestamp)
h := md5.New()
h.Write([]byte(data))
return hex.EncodeToString(h.Sum(nil))
}
func main() {
/*生成16进制随机字符串(16位)*/
nonceByte := make([]byte, 8)
rand.Read(nonceByte)
signatureNonce := hex.EncodeToString(nonceByte)
log.Printf(signatureNonce)
appId := 12345 //使用你的appId和serverSecret
serverSecret := "9193cc662a4c0ec135ec71fb57194b38"
timestamp := time.Now().Unix()
/* appId:12345
signatureNonce:4fd24687296dd9f3
serverSecret:9193cc662a4c0ec135ec71fb57194b38
timestamp:1615186943 2021/03/08 15:02:23
signature:43e5cfcca828314675f91b001390566a
*/
log.Printf("signature:%v", GenerateSignature(uint32(appId), signatureNonce, serverSecret, timestamp))
}
# -*- coding: UTF-8 -*-
import secrets
import string
import hashlib
import time
#Signature=md5(AppId + SignatureNonce + ServerSecret + Timestamp)
def GenerateSignature(appId, signatureNonce, serverSecret, timestamp):
str1 = str(appId) + signatureNonce + serverSecret + str(timestamp)
hash = hashlib.md5()
hash.update(str1.encode("utf8"))
signature = hash.hexdigest()
return signature
def main():
#生成16进制随机字符串(16位)
signatureNonce = secrets.token_hex(8)
#使用你的appId和serverSecret
appId = 12345
serverSecret = "9193cc662a4c0ec135ec71fb57194b38"
#获得10位unix时间戳
timestamp = int(time.time())
print(GenerateSignature(appId,signatureNonce,serverSecret,timestamp))
if __name__ == '__main__':
main()
import java.security.MessageDigest;
import java.security.SecureRandom;
public class Md5{
/**
* 字节数组转16进制
* @param bytes 需要转换的byte数组
* @return 转换后的Hex字符串
*/
public static String bytesToHex(byte[] bytes) {
StringBuffer md5str = new StringBuffer();
//把数组每一字节换成16进制连成md5字符串
int digital;
for (int i = 0; i < bytes.length; i++) {
digital = bytes[i];
if (digital < 0) {
digital += 256;
}
if (digital < 16) {
md5str.append("0");
}
md5str.append(Integer.toHexString(digital));
}
return md5str.toString();
}
// Signature=md5(AppId + SignatureNonce + ServerSecret + Timestamp)
public static String GenerateSignature(long appId, String signatureNonce, String serverSecret, long timestamp){
String str = String.valueOf(appId) + signatureNonce + serverSecret + String.valueOf(timestamp);
String signature = "";
try{
//创建一个提供信息摘要算法的对象,初始化为md5算法对象
MessageDigest md = MessageDigest.getInstance("MD5");
//计算后获得字节数组
byte[] bytes = md.digest(str.getBytes("utf-8"));
//把数组每一字节换成16进制连成md5字符串
signature = bytesToHex(bytes);
}catch (Exception e) {
e.printStackTrace();
}
return signature;
}
public static void main(String[] args){
//生成16进制随机字符串(16位)
byte[] bytes = new byte[8];
//使用SecureRandom获取高强度安全随机数生成器
SecureRandom sr = new SecureRandom();
sr.nextBytes(bytes);
String signatureNonce = bytesToHex(bytes);
long appId = 12345L; //使用你的appId和serverSecret,数字后要添加大写L或小写l表示long类型
String serverSecret = "9193cc662a4c0ec135ec71fb57194b38";
long timestamp = System.currentTimeMillis() / 1000L;
System.out.println(GenerateSignature(appId,signatureNonce,serverSecret,timestamp));
}
}
<?php
function GenerateSignature($appId, $signatureNonce, $serverSecret, $timestamp)
{
$str = $appId.$signatureNonce.$serverSecret.$timestamp;
$signature = md5($str);
return $signature;
}
//生成16进制随机字符串(16位)
$signatureNonce = bin2hex(random_bytes(8));
//使用你的appId和serverSecret
$appId = 12345;
$serverSecret = "9193cc662a4c0ec135ec71fb57194b38";
$timestamp = time();
$signature = GenerateSignature($appId, $signatureNonce, $serverSecret, $timestamp);
echo $signature;
?>
const crypto = require('crypto');
//Signature=md5(AppId + SignatureNonce + ServerSecret + Timestamp)
function GenerateUASignature(appId, signatureNonce, serverSecret, timeStamp){
const hash = crypto.createHash('md5'); //规定使用哈希算法中的MD5算法
var str = appId + signatureNonce + serverSecret + timeStamp;
hash.update(str);
//hash.digest('hex')表示输出的格式为16进制
return hash.digest('hex');
}
var signatureNonce = crypto.randomBytes(8).toString('hex');
//使用你的appId和serverSecret
var appId = 12345;
var serverSecret = "9193cc662a4c0ec135ec71fb57194b38";
var timeStamp = Math.round(Date.now()/1000);
console.log(GenerateUASignature(appId, signatureNonce, serverSecret, timeStamp));
在使用服务端 API 接口发送请求时,存在以下与签名相关的返回码,请开发者根据实际情况处理。
返回码 | 说明 | 处理建议 |
---|---|---|
0 | 请求成功。 | - |
100000004 | 签名过期。 | 请重新生成签名信息。 |
100000005 | 签名错误。 | 请检查生成签名信息时,参数输入是否正确。 |
联系我们
文档反馈