快速开始
简介
ZEGO 星图提供了多个服务端 API 接口,支持开发者向 ZEGO 服务端发送请求查询用户推拉流数据、地区数据和运营运营。开发者可以通过发起 HTTPS 网络请求,使用 GET 方法调用服务端 API,实现与 ZEGO 服务端的信息交互。
本文以 “如何调用一个服务端 API 接口” 为例,帮助开发者快速了解服务端 API 各类接口的使用方式。
前提条件
在开始调用服务端 API 接口之前,请确保:
- 已在 ZEGO 控制台 创建项目,并申请有效的 AppId 和 ServerSecret,详情请参考 控制台 - 项目管理 中的“项目信息”。
- 已准备好调试服务端 API 接口的开发环境。
- 已准备好自己的客户端,搭建相关的业务场景。
GET 请求示例代码
ZEGO 提供多种编程语言的示例代码,开发者可根据实际情况进行参考。以 查询业务规模 接口,向 ZEGO 服务端发送 GET 请求为例:
package main
import (
"crypto/md5"
"crypto/rand"
"encoding/hex"
"fmt"
"io/ioutil"
"net/http"
"net/url"
"time"
)
//请将 AppId 修改为你的 AppId,AppId 为 uint32
//举例:1234567890
var appId uint32 = 1234567890
//请将 serverSecret 修改为你的 serverSecret,serverSecret 为 string
//举例:"abcde1234aaaaaaaabbbbbbb"
var serverSecret =
func main() {
queryParams := url.Values{}
startDate := "20250110"
endDate := "20250112"
metrics := "publish_count"
queryParams.Add("StartDate", startDate)
queryParams.Add("EndDate", endDate)
queryParams.Add("Metrics[]", "publish_count")
queryParams.Add("Metrics[]", "view_count")
timestamp := time.Now().Unix()
// 生成16进制随机字符串(16位)
nonce := make([]byte, 8)
rand.Read(nonce)
hexNonce := hex.EncodeToString(nonce)
// 生成签名
signature := generateSignature(appId, serverSecret, hexNonce, timestamp)
authParams := url.Values{}
authParams.Set("AppId", fmt.Sprintf("%d", appId))
//公共参数中的随机数和生成签名的随机数要一致
authParams.Set("SignatureNonce", hexNonce)
authParams.Set("SignatureVersion", "2.0")
//公共参数中的时间戳和生成签名的时间戳要一致
authParams.Set("Timestamp", fmt.Sprintf("%d", timestamp))
authParams.Set("Signature", signature)
// analytics-api.zego.im 表示请求的是星图服务端 API
// 以下示例可调用 "GetBizUsage" API 查询指定时间段内每日的实时音视频数据统计
addr := fmt.Sprintf("https://analytics-api.zego.im/?Action=GetBizUsage&%s&%s", authParams.Encode(), queryParams.Encode())
rsp, err := http.Get(addr)
if err != nil {
fmt.Printf("http.Get err:%+v", err)
return
}
defer rsp.Body.Close()
body, err := ioutil.ReadAll(rsp.Body)
if err != nil {
fmt.Printf("ioutil.ReadAll err:%+v", err)
return
}
fmt.Printf("body:%+v", string(body))
}
// 生成签名
// Signature=md5(AppId + SignatureNonce + ServerSecret + Timestamp)
func generateSignature(appId uint32, serverSecret, signatureNonce string, timeStamp int64) 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))
}
使用流程
开发者可以通过以下流程,快速向 ZEGO 服务端发起请求:
- 开发者的服务端首先确认请求的 URL 地址;
- 根据签名生成规则,获取签名信息;
- 开发者的服务端配置公共请求参数;
- 配置 API 相关业务参数;
- 开发者的服务端通过 URL 地址,携带请求信息(包含业务参数、签名信息等),访问 ZEGO 服务端;
- ZEGO 服务端返回响应信息。
我们以 API 接口 查询业务规模,向 ZEGO 服务端发送 GET 请求为例,详细介绍使用流程。
1 确认 URL 地址
ZEGO 服务端根据不同的 URL 地址区分不同的请求。因此,开发者的服务端访问 ZEGO 服务端,请先到对应接口文档中获取请求 URL 地址。
以下为 查询业务规模 的 URL 地址:
https://analytics-api.zego.im/?Action=GetBizUsage
其中:
- https:指定了请求通信协议。
- analytics-api.zego.im:指定了 ZEGO 服务端的接入地址,其中
analytics
代表使用的产品是星图,详见 调用方式 - 请求结构 - 接入地址。 - Action=GetBizUsage:指定了要调用的 API 接口为
GetBizUsage
。
2 生成签名信息
为保证 API 的安全调用,ZEGO 服务端会对每个 API 的访问请求进行身份验证。开发者在调用 API 时,都需要在请求中包含签名 Signature 信息。
开发者可以参考 调用方式 - 签名机制 中的各语言示例代码,使用本文 前提条件 获取到的 AppId 和 ServerSecret,生成自己的签名信息。
3 配置公共请求参数
开发者调用每个 ZEGO 服务端 API 前,需要先配置 API 的公共请求参数。
公共请求参数,是指每个接口都需要使用到的请求参数,包含了 AppId、Signature(指 2 生成的签名信息)、SignatureNonce(随机字符串)、Timestamp(时间戳)等参数,请根据实际情况修改。公共参数的具体介绍,请参考 调用方式 - 公共参数。
https://analytics-api.zego.im/?Action=GetBizUsage&AppId=1234567890&SignatureNonce=15215528852396&Timestamp=1234567890&Signature=Pc5WB8gokVn0xfeu%2FZV%2BiNM1dgI%3D&SignatureVersion=2.0&IsTest=false
开发者可以在 服务端 API 校验 页面中,输入 URL 地址,验证签名信息、公共参数、以及 URL 格式是否合法。
4 配置 API 相关业务参数
配置完公共参数后,再去配置 API 相关的业务参数,设定所需的目标操作。
业务参数的具体介绍,请参考 请求参数。
5 开发者的服务端发起请求
以上配置完成后,开发者的服务端可以通过 URL 地址,向 ZEGO 服务端发送请求。
请求示例如下:
//该请求为获取从 20250110 至 20250112 期间的推流累计和拉流累计
https://analytics-api.zego.im/?Action=GetBizUsage
&StartDate=20250110
&EndDate=20250112
&Metrics[]=publish_count
&Metrics[]=play_count
&<公共请求参数>
6 ZEGO 服务端响应请求
ZEGO 服务端接收到开发者的请求信息后,返回响应的信息。
{
"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” 表示访问成功,即可查看到房间内的成员列表;如果不为 “0”,请参考 全局返回码 处理。
至此,开发者的服务端和 ZEGO 服务端就完成了一次信息交互。