调用方式

使用说明

ZEGO 服务端 API 支持 HTTPS 网络请求协议，允许 GET 或 POST 方法。您可以通过以下方式调用服务端 API：

根据 API 文档编写代码，访问相应 API。
参考如何在线调试服务端 API，可在文档页面快速调试相应接口。

请求结构

服务地址

开发者需要根据自己的服务端所在地理区域，指定相应的接入地址，向 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} 值	接入域名
即时通讯	zim	zim-api.zego.im
鉴权（用于语音组件）	auth	auth-api.zego.im

通信协议

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

请求方法

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

GET
POST

说明

所有请求参数（包括公共参数和业务参数）统⼀放在 Query，使⽤ GET 请求方法。特殊复杂的 API 参数放在 Body，使用 POST 请求方法。

公共参数

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

公共请求参数

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

参数	类型	是否必选	描述
AppId	Uint32	是	应用 Id，由 ZEGO 分配的用户唯一凭证。可从 ZEGO 控制台获取。
Signature	String	是	签名，签名的生成请参考签名机制。
SignatureNonce	String	是	16 位 16 进制随机字符串（8 字节随机数的 hex 编码）。生成算法可参考签名示例。
SignatureVersion	String	是	签名版本号，默认值为 2.0。
Timestamp	Number	是	当前 Unix 时间戳，单位为秒。生成算法可参考签名示例，最多允许 10 分钟的误差。

请求示例：

GET 请求

https://zim-api.zego.im/?Action=xxx
&AppId=1234567890
&Timestamp=1234567890
&Signature=Pc5WB8gokVn0xfeu%2FZV%2BiNM1dgI%3D
&SignatureVersion=2.0
&SignatureNonce=15215528852396
&<非公共请求参数>

https://zim-api.zego.im/?Action=xxx
&AppId=1234567890
&Timestamp=1234567890
&Signature=Pc5WB8gokVn0xfeu%2FZV%2BiNM1dgI%3D
&SignatureVersion=2.0
&SignatureNonce=15215528852396
&<非公共请求参数>

公共返回参数

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

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

参数	类型	描述
Code	Number	返回码。
Message	String	请求结果的说明信息。
RequestId	String	请求 ID。

返回示例：

{
    "Code": 0,
    "Message": "",
    "RequestId": "8411281679140263090",
    ......
}

{
    "Code": 0,
    "Message": "",
    "RequestId": "8411281679140263090",
    ......
}

签名机制

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

注意

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

密钥获取

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

开发者可到 ZEGO 控制台在 “控制台 > 项目管理” 中，查看项目的 AppId；单击项目右侧的“查看”按钮，在 项目配置 中查看 ServerSecret 等信息。

签名生成

签名参数说明

参数	含义
AppId	应用 ID。即公共参数里的 AppId，从 ZEGO 控制台获取。
SignatureNonce	16 位 16 进制随机字符串（8 字节随机数的 hex 编码）。即公共参数里的 SignatureNonce。生成算法可参考签名示例。
ServerSecret	应⽤密钥。从 ZEGO 控制台获取。
Timestamp	当前 Unix 时间戳，即公共参数里的 Timestamp，单位为秒。生成算法可参考签名示例，最多允许 10 分钟的误差。

注意

计算签名所使用的 SignatureNonce 和 Timestamp 参数取值，需要和公共参数中的 SignatureNonce 和 Timestamp 参数取值保持一致。
生成的签名在 10 分钟内有效，超过时间请重新生成。

签名生成算法

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

返回码

在使用服务端 API 接口发送请求时，存在以下与签名相关的返回码，请开发者根据实际情况处理。

返回码	说明	处理建议
0	请求成功。	-
100000004	签名过期。	请重新生成签名信息。
100000005	签名错误。	请检查生成签名信息时，参数输入是否正确。