调用方式

使用说明

ZEGO 服务端 API 支持 HTTPS 网络请求协议，允许 GET 或 POST 方法。您可以根据 API 文档编写代码，访问相应 API。

请求方式概述

服务端 API 请求由不同内容构成，有固定的请求结构：

接入地址：ZEGO 服务端的接入地址，根据不同的产品和地域会有所不同。
公共参数：每个请求都须有一系列公共参数。
签名：签名也属于公共参数，需要根据相应的签名算法生成。
请求参数：您需要通过 Action 参数指定目标操作，例如 Action = GetBizUsage；还需要指定接口的其他参数。

我们根据您的签名验证了请求后，会返回结果给您。接口调用成功会显示返回参数，调用失败则显示相应报错，您可以根据全局返回码分析排查。

展开查看服务端 API 请求示例

以下为 GetBizUsage（查询业务规模）接口的请求结构为例：

https://analytics-api.zego.im/?Action=GetBizUsage
&AppId=1234567890
&SignatureNonce=15215528852396
&Timestamp=1234567890
&Signature=7a2c0f11145fb760d607a07b54825013
&SignatureVersion=2.0
&IsTest=false
&StartDate=20230912
&EndDate=20231012
&Metrics[]=publish_count
&Metrics[]=play_count

https://analytics-api.zego.im/?Action=GetBizUsage
&AppId=1234567890
&SignatureNonce=15215528852396
&Timestamp=1234567890
&Signature=7a2c0f11145fb760d607a07b54825013
&SignatureVersion=2.0
&IsTest=false
&StartDate=20230912
&EndDate=20231012
&Metrics[]=publish_count
&Metrics[]=play_count

其中：

https：指定了请求通信协议。
analytics-api.zego.im：指定了 ZEGO 服务端的接入地址。
Action=GetBizUsage：指定了要调用的 API。
公共请求参数：是每个接口都需要使用到的请求参数，包含 AppId、SignatureNonce、Timestamp、Signature、SignatureVersion 和 IsTest，具体说明请参考公共请求参数。
业务参数：不同 Action 要求开发者传入不同的业务参数，上述例子中的 StartDate、EndDate 和 Metrics 为业务参数，具体说明请参考各接口文档。

此外，ZEGO 提供多种编程语言的示例代码，开发者可根据实际情况进行参考。以下是 GetBizUsage 接口的 Node.js 代码：

const crypto = require('crypto');
const request = require('request');

//请将 appId 修改为你的 AppId，AppId 为 number
var appId = 1234567890;
//请将 serverSecret 修改为你的 serverSecret，serverSecret 为 string
//举例："1234567890bbc111111da999ef05f0ee"
var serverSecret = ;

//生成签名
//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');
var timeStamp = Math.round(Date.now()/1000);
// 生成签名
// 生成签名时用到的 Timestamp 要和url参数中的 Timestamp一致，生成签名时用到的 SignatureNonce 也要和url参数中的 SignatureNonce 一致
var sig = GenerateUASignature(appId, signatureNonce, serverSecret, timeStamp)
// analytics-api.zego.im 表示使用的产品是星图
//以下示例可获取 RoomID 为 room1 的房间用户数
var url = `https://analytics-api.zego.im/?Action=GetBizUsage&StartDate=20250110&EndDate=20250112&Metrics[]=publish_count&Metrics[]=play_count&AppId=${appId}&SignatureNonce=${signatureNonce}&Timestamp=${timeStamp}&Signature=${sig}&SignatureVersion=2.0&IsTest=false`;

request(url, function(error, response, body){
    console.log('Url: ',url)
    console.log('StatusCode: ',response.statusCode)
    console.log('Error: ', error)
    if(!error && response.statusCode){
        console.log(body)
    }
})

const crypto = require('crypto');
const request = require('request');

//请将 appId 修改为你的 AppId，AppId 为 number
var appId = 1234567890;
//请将 serverSecret 修改为你的 serverSecret，serverSecret 为 string
//举例："1234567890bbc111111da999ef05f0ee"
var serverSecret = ;

//生成签名
//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');
var timeStamp = Math.round(Date.now()/1000);
// 生成签名
// 生成签名时用到的 Timestamp 要和url参数中的 Timestamp一致，生成签名时用到的 SignatureNonce 也要和url参数中的 SignatureNonce 一致
var sig = GenerateUASignature(appId, signatureNonce, serverSecret, timeStamp)
// analytics-api.zego.im 表示使用的产品是星图
//以下示例可获取 RoomID 为 room1 的房间用户数
var url = `https://analytics-api.zego.im/?Action=GetBizUsage&StartDate=20250110&EndDate=20250112&Metrics[]=publish_count&Metrics[]=play_count&AppId=${appId}&SignatureNonce=${signatureNonce}&Timestamp=${timeStamp}&Signature=${sig}&SignatureVersion=2.0&IsTest=false`;

request(url, function(error, response, body){
    console.log('Url: ',url)
    console.log('StatusCode: ',response.statusCode)
    console.log('Error: ', error)
    if(!error && response.statusCode){
        console.log(body)
    }
})

请求结构

接入地址

开发者需要根据自己的服务端所在地理区域，指定相应的接入地址，向 ZEGO 服务端发送请求。

注意

为保障您的业务服务接入质量，请优先使用您的服务端所在地理区域的域名，作为接入地址，向 ZEGO 服务端发送请求。

ZEGO 支持如下地理区域的请求接入：

地理区域	接⼊地址
中国⼤陆（上海）	analytics-api-sha.zego.im
港澳台（⾹港）	analytics-api-hkg.zego.im
欧洲（法兰克福）	analytics-api-fra.zego.im
美⻄（加州）	analytics-api-lax.zego.im
亚太（孟买）	analytics-api-bom.zego.im
东南亚（新加坡）	analytics-api-sgp.zego.im
统一接入地址（不区分区域）	analytics-api.zego.im

通信协议

ZEGO 服务端 API 的所有接口均通过 HTTPS 进行通信，提供安全的通信服务。

请求方法

ZEGO 服务端 API 支持以下 HTTP 请求方法：

GET
- 所有请求参数（包括公共参数和业务参数）统⼀放在 Query 中。
POST
- 特殊复杂 API 的业务参数放在 Body，公共参数放在 Query 中。
- Body 中的参数直接传 JsonObject 格式即可，无需序列化为 String 格式。
- Headers 中，设置 “Content-type” 为 “application/json”。

公共参数

本节介绍了开发者调用 ZEGO 服务端 API 时使用的公共参数，包含了公共请求参数和公共返回参数。

公共请求参数

公共请求参数是每个接口都需要使用到的请求参数。

参数	类型	是否必填	描述
AppId	Uint32	是	AppId，ZEGO 分配的用户唯一凭证。
Signature	String	是	签名，签名的生成请参考签名机制。
SignatureNonce	String	是	随机字符串。
SignatureVersion	String	是	签名版本号，必须填写为 2.0。
Timestamp	Int64	是	Unix 时间戳，单位为秒。最多允许 10 分钟的误差。
IsTest	String	是（2021-11-16 及之前创建的项目）	是否为测试环境。取值如下： true（忽略大小写）：测试环境 false（忽略大小写）：正式环境（默认值）注意针对 2021-11-16 及之前在 ZEGO 控制台创建的项目：从控制台申请的 AppId 和 AppSign 等信息默认是测试环境。可根据 AppId 环境类型及业务需求设置本参数。
IsTest	String	否（2021-11-16 之后创建的项目）	是否为测试环境。默认为正式环境，可忽略不填写。注意针对 2021-11-16 之后在 ZEGO 控制台创建的项目：从控制台申请的 AppId 和 AppSign 等信息都为正式环境。

请求示例：

注意

请勿直接拷贝下面的示例用于请求。
https://analytics-api.zego.im/?Action=GetBizUsage 需要替换为各接口文档“接口原型”章节中的请求地址。
各公共参数的取值请根据实际情况修改。

GET 请求

https://analytics-api.zego.im/?Action=xxxx
&AppId=1234567890
&SignatureNonce=15215528852396
&Timestamp=1234567890
&Signature=xxxx
&SignatureVersion=2.0
&IsTest=false
&<非公共请求参数>

https://analytics-api.zego.im/?Action=xxxx
&AppId=1234567890
&SignatureNonce=15215528852396
&Timestamp=1234567890
&Signature=xxxx
&SignatureVersion=2.0
&IsTest=false
&<非公共请求参数>

开发者可以在服务端 API 校验页面中，输入 URL 地址，验证签名信息、公共参数、以及 URL 格式是否合法。

公共返回参数

API 返回结果采用统一格式，返回的数据格式为 JSON。

每次调用接口，无论成功与否，都会返回公共参数。

参数	类型	描述
Code	Number	返回码。
Message	String	操作结果描述。
RequestId	String	请求 ID。
Data	-	响应数据。

返回示例：

{
    "Code": 0,
    "Data": {
        "Metrics": [
            {
                "Metric": "publish_count",
                "Values": [
                    {
                        "Date": "20250110",
                        "Value": 100
                    },
                    {
                        "Date": "20250111",
                        "Value": 30
                    },
                    {
                        "Date": "20250112",
                        "Value": 40
                    }
                ]
            },
            {
                "Metric": "play_count",
                "Values": [
                    {
                        "Date": "20250110",
                        "Value": 60
                    },
                    {
                        "Date": "20250111",
                        "Value": 20
                    },
                    {
                        "Date": "20250112",
                        "Value": 10
                    }
                ]
            }
        ]
    },
    "Message": "success",
    "RequestId": 1659512998878671000
}

{
    "Code": 0,
    "Data": {
        "Metrics": [
            {
                "Metric": "publish_count",
                "Values": [
                    {
                        "Date": "20250110",
                        "Value": 100
                    },
                    {
                        "Date": "20250111",
                        "Value": 30
                    },
                    {
                        "Date": "20250112",
                        "Value": 40
                    }
                ]
            },
            {
                "Metric": "play_count",
                "Values": [
                    {
                        "Date": "20250110",
                        "Value": 60
                    },
                    {
                        "Date": "20250111",
                        "Value": 20
                    },
                    {
                        "Date": "20250112",
                        "Value": 10
                    }
                ]
            }
        ]
    },
    "Message": "success",
    "RequestId": 1659512998878671000
}

签名机制

为保证 API 的安全调用，ZEGO 服务端会对每个 API 的访问请求进行身份验证。开发者在调用 API 时，都需要在请求中包含签名 Signature 信息。

注意

每次调用接口都需要生成新的签名。

密钥获取

Signature 通过使用 AppID 和 ServerSecret 进行对称加密的方法来验证请求的发送者身份。AppID 用于标识访问者的身份，ServerSecret 用于加密签名字符串和服务器验证签名字符串的密钥，必须严格保密，防止泄漏。

AppID 和 ServerSecret 从 ZEGO 控制台获取，详情请参考控制台文档项目信息。

签名生成

签名参数说明

参数	含义
AppId	应用 ID。
SignatureNonce	随机字符串。公共参数里的 SignatureNonce，生成算法可参考下方签名示例。
ServerSecret	应⽤密钥。
Timestamp	当前 Unix 时间戳，单位为秒。生成算法可参考下方签名示例，最多允许 10 分钟的误差。

说明

计算签名所使用的 SignatureNonce 和 Timestamp 参数取值，需要和公共参数中的 SignatureNonce 和 Timestamp 参数取值保持一致。

签名生成算法

Signature = md5(AppId + SignatureNonce + ServerSecret + Timestamp)

签名字符串格式

签名采⽤ hex 编码（⼩写），⻓度为 32 个字符。

签名示例

ZEGO 提供多种编程语言的签名示例代码，开发者可根据实际情况进行参考。

Go

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

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

签名失败

存在以下签名失败的返回码，请开发者根据实际情况处理。

返回码	说明
100000004	签名过期。
100000005	签名错误。