文档中心
声网平台
Console 官网 社区 技术支持
简体中文
search-icon

控制台 RESTful API

更新时间 2024/07/24 08:00:31

当需要创建和管理项目或查看项目用量，除使用声网控制台的图形用户界面，还可以使用声网提供的控制台 RESTful API。

本页面介绍声网控制台 RESTful API 的详细信息，并提供保障 REST 服务高可用的方案。

基本信息

本节介绍所有声网控制台 RESTful API 的基本信息。

域名

所有请求都发送给域名：api.sd-rtn.com。

数据格式

所有 HTTP 请求头部的 Content-Type 类型为 application/json。所有请求和响应内容的格式均为 JSON。所有的请求 URL 和请求包体内容都区分大小写。

认证方式

声网控制台 RESTful API 仅支持 HTTPS 协议。发送请求时，你需要使用声网提供的客户 ID 和客户密钥生成一个 Base64 算法编码的凭证，并填入 HTTP 请求头部的 Authorization 字段中。详见 HTTP 基本认证。

调用频率限制

对于每个声网账号（非每个 App ID），本页每个 API 的调用频率上限为每秒 10 次。如果调用频率超出限制，请参考如何处理服务端 RESTful API 调用超出频率限制优化调用频率。

创建项目

创建一个新的声网项目。

  • 一个账户最多可创建 20 个项目，包括已删除的项目。如果需要创建更多项目，请通过工单系统申请。
    在 2021 年 10 月 1 日前注册的账户最多可创建 10 个项目，包括已删除的项目。如果需要创建更多项目，请通过工单系统申请。

接口原型

  • 方法：POST
  • 接入点：https://api.sd-rtn.com/dev/v1/project

请求参数

请求包体参数

在请求包体中传入以下参数：

参数 类型 描述
name String （必填）项目名称，长度为 1 ~ 255 个字符。
enable_sign_key Boolean （必填）是否启用主要 App 证书：
  • true：启用
  • false：（默认）不启用
    • 注意事项：创建项目后，你可以调用 https://api.sd-rtn.com/dev/v1/signkey 启用或禁用主要 App 证书，或调用 https://api.sd-rtn.com/dev/v1/reset_signkey 重置主要 App 证书。

    请求示例

    请求包体

    {
  "name": "project1",
  "enable_sign_key": true
}

    响应参数

    可能的响应状态码详见状态码汇总表。

    如果状态码不为 201，则请求失败。响应包体中包含 message 字段，描述失败的具体原因。

    如果状态码为 201，则请求成功，响应包体包含如下参数：

    参数 类型 描述
    project Object 项目的信息，包含以下字段：
    • id：String。项目 ID。
    • name：String。项目名称。
    • vendor_key：String。项目的 App ID。
    • sign_key：String。项目的主要 App 证书。
    • recording_server：String。录制项目服务器 IP 地址：
      • 如果你使用的是本地服务端录制 SDK v1.9.0 及之前版本，请关注此字段。
      • 如果你使用的是本地服务端录制 SDK v1.11.0 及之后版本，请忽略此字段。
    • status：Number。项目状态：
      • 1：启用
      • 0：禁用
    • created：Number。项目的创建时间，Unix 时间戳，单位为秒。

    响应示例

    请求成功的响应示例：

    {
    "project": {
      "id": "xxxx",
      "name": "project1",
      "vendor_key": "4855xxxxxxxxxxxxxxxxxxxxxxxxeae2",
      "sign_key": "4855xxxxxxxxxxxxxxxxxxxxxxxxeae2",
      "recording_server": null,
      "status": 1,
      "created": 1464165672
    }
}

    获取指定项目

    获取指定声网项目的信息。

    接口原型

    • 方法：GET
    • 接入点：https://api.sd-rtn.com/dev/v1/project

    请求参数

    查询参数

    在请求路径中传入以下查询参数：

    参数 类型 描述
    id String （必填）项目 ID，可以通过调用获取所有项目信息 API 获取。
    name String （必填）项目名称。

    请求示例

    请求路径

    https://api.sd-rtn.com/dev/v1/project?id=7sdnf3xRH&name=project1

    响应参数

    可能的响应状态码详见状态码汇总表。

    如果状态码不为 201，则请求失败。响应包体中包含 message 字段，描述失败的具体原因。

    如果状态码为 201，则请求成功，响应包体包含如下参数：

    参数 类型 描述
    projects Array 项目的信息。由多个 Object 组成的数组，一个 Object 表示一个项目的信息。每个 Object 包含以下字段：
    • id：String。项目 ID。
    • name：String。项目名称。
    • vendor_key：String。项目的 App ID。
    • sign_key：String。项目的主要 App 证书。
    • recording_server：String。录制项目服务器 IP 地址：
      • 如果你使用的是本地服务端录制 SDK v1.9.0 及之前版本，请关注此字段。
      • 如果你使用的是本地服务端录制 SDK v1.11.0 及之后版本，请忽略此字段。
    • status：Number。项目状态：
      • 1：启用
      • 0：禁用
    • created：Number。项目的创建时间，Unix 时间戳，单位为秒。

    响应示例

    请求成功的响应示例：

    {
    "projects": [
        {
            "id": "xxxx",
            "name": "project1",
            "sign_key": "4855xxxxxxxxxxxxxxxxxxxxxxxxeae2",
            "vendor_key": "4855xxxxxxxxxxxxxxxxxxxxxxxxeae2",
            "recording_server": null,
            "status": 1,
            "created": 1464165672
        }
    ]
}

    获取所有项目

    获取所有声网项目的信息。

    接口原型

    • 方法：GET
    • 接入点：https://api.sd-rtn.com/dev/v1/projects

    请求示例

    请求路径

    https://api.sd-rtn.com/dev/v1/projects

    响应参数

    可能的响应状态码详见状态码汇总表。

    如果状态码不为 201，则请求失败。响应包体中包含 message 字段，描述失败的具体原因。

    如果状态码为 201，则请求成功，响应包体包含如下参数：

    参数 类型 描述
    projects Array 项目的信息。由多个 Object 组成的数组，一个 Object 表示一个项目的信息。每个 Object 包含以下字段：
    • id：String。项目 ID。
    • name：String。项目名称。
    • vendor_key：String。项目的 App ID。
    • sign_key：String。项目的主要 App 证书。
    • recording_server：String。录制项目服务器 IP 地址：
      • 如果你使用的是本地服务端录制 SDK v1.9.0 及之前版本，请关注此字段。
      • 如果你使用的是本地服务端录制 SDK v1.11.0 及之后版本，请忽略此字段。
    • status：Number。项目状态：
      • 1：启用
      • 0：禁用
    • created：Number。项目的创建时间，Unix 时间戳，单位为秒。

    响应示例

    请求成功的响应示例：

    {
    "projects": [
        {
            "id": "xxxx",
            "name": "project1",
            "sign_key": "4855xxxxxxxxxxxxxxxxxxxxxxxxeae2",
            "vendor_key": "4855xxxxxxxxxxxxxxxxxxxxxxxxeae2",
            "recording_server": null,
            "status": 1,
            "created": 1464165672
        },
        {
            "id": "xxxx",
            "name": "project1",
            "sign_key": "2c01da6d6f6741df88ec47005f08572b",
            "vendor_key": "eb00cd2b222a4eeaa24fc6046d90b227",
            "recording_server": null,
            "status": 1,
            "created": 1637153755
        }
    ]
}

    禁用或启用项目

    禁用或启用指定的项目。

    接口原型

    • 方法：POST
    • 接入点：https://api.sd-rtn.com/dev/v1/project_status

    请求参数

    请求包体参数

    在请求包体中传入以下参数：

    参数 类型 描述
    id String （必填）项目 ID，可以通过调用获取所有项目信息 API 获取。
    status Number （必填）想要设置的项目状态：
  • 0：禁用
  • 1：启用
    		•

    请求示例

    请求包体

    {
  "id": "xxxx",
  "status": 0
}

    响应参数

    可能的响应状态码详见状态码汇总表。

    如果状态码不为 201，则请求失败。响应包体中包含 message 字段，描述失败的具体原因。

    如果状态码为 201，则请求成功，响应包体包含如下参数：

    参数 类型 描述
    project Object 项目的信息，包含以下字段：
    • id：String。项目 ID。
    • name：String。项目名称。
    • vendor_key：String。项目的 App ID。
    • sign_key：String。项目的主要 App 证书。
    • recording_server：String。录制项目服务器 IP 地址：
      • 如果你使用的是本地服务端录制 SDK v1.9.0 及之前版本，请关注此字段。
      • 如果你使用的是本地服务端录制 SDK v1.11.0 及之后版本，请忽略此字段。
    • status：Number。项目状态：
      • 1：启用
      • 0：禁用
    • created：Number。项目的创建时间，Unix 时间戳，单位为秒。

    响应示例

    请求成功的响应示例：

    {
    "project": {
      "id": "xxxx",
      "name": "project1",
      "vendor_key": "4855xxxxxxxxxxxxxxxxxxxxxxxxeae2",
      "sign_key": "4855xxxxxxxxxxxxxxxxxxxxxxxxeae2",
      "recording_server": null,
      "status": 1,
      "created": 1464165672
    }
}

    设置录制服务器 IP

    设置指定项目的录制服务器的 IP 地址。

    该方法仅适用于 v1.9.0 及之前版本的本地服务端录制 SDK。

    接口原型

    • 方法：POST
    • 接入点：https://api.sd-rtn.com/dev/v1/recording_config

    请求参数

    请求包体参数

    在请求包体中传入以下参数：

    参数 类型 描述
    id String （必填）项目 ID，可以通过调用获取所有项目信息 API 获取。
    recording_server String （必填）项目的录制服务器 IP 地址。该字段仅当你使用 v1.9.0 或之前版本的本地服务端录制 SDK 时生效。

    请求示例

    请求包体

    {
  "id": "xxxx",
  "recording_server": "10.12.1.5:8080"
}

    响应参数

    可能的响应状态码详见状态码汇总表。

    如果状态码不为 201，则请求失败。响应包体中包含 message 字段，描述失败的具体原因。

    如果状态码为 201，则请求成功，响应包体包含如下参数：

    参数 类型 描述
    project Object 项目的信息，包含以下字段：
    • id：String。项目 ID。
    • name：String。项目名称。
    • vendor_key：String。项目的 App ID。
    • sign_key：String。项目的主要 App 证书。
    • recording_server：String。录制项目服务器 IP 地址：
      • 如果你使用的是本地服务端录制 SDK v1.9.0 及之前版本，请关注此字段。
      • 如果你使用的是本地服务端录制 SDK v1.11.0 及之后版本，请忽略此字段。
    • status：Number。项目状态：
      • 1：启用
      • 0：禁用
    • created：Number。项目的创建时间，Unix 时间戳，单位为秒。

    响应示例

    请求成功的响应示例：

    {
    "project": {
      "id": "xxxx",
      "name": "project1",
      "vendor_key": "4855xxxxxxxxxxxxxxxxxxxxxxxxeae2",
      "sign_key": "4855xxxxxxxxxxxxxxxxxxxxxxxxeae2",
      "recording_server": null,
      "status": 1,
      "created": 1464165672
    }
}

    启用或禁用主要 App 证书

    启用或禁用指定项目的主要 App 证书。

    接口原型

    • 方法：POST
    • 接入点：https://api.sd-rtn.com/dev/v1/signkey

    请求参数

    请求包体参数

    该 API 需要在请求包体中传入以下参数：

    参数 类型 描述
    id String （必填）项目 ID，可以通过调用获取所有项目信息 API 获取。
    enable Boolean （必填）是否启用项目的主要 App 证书：
  • true：（默认）启用
  • false：不启用
    		•

    请求示例

    请求包体

    {
  "id": "xxxx",
  "enable": true
}

    响应参数

    可能的响应状态码详见状态码汇总表。

    如果状态码不为 201，则请求失败。响应包体中包含 message 字段，描述失败的具体原因。

    如果状态码为 201，则请求成功，响应包体包含如下参数：

    参数 类型 描述
    project Object 项目的信息，包含以下字段：
    • id：String。项目 ID。
    • name：String。项目名称。
    • vendor_key：String。项目的 App ID。
    • sign_key：String。项目的主要 App 证书。
    • recording_server：String。录制项目服务器 IP 地址：
      • 如果你使用的是本地服务端录制 SDK v1.9.0 及之前版本，请关注此字段。
      • 如果你使用的是本地服务端录制 SDK v1.11.0 及之后版本，请忽略此字段。
    • status：Number。项目状态：
      • 1：启用
      • 0：禁用
    • created：Number。项目的创建时间，Unix 时间戳，单位为秒。

    响应示例

    请求成功的响应示例：

    {
    "project": {
      "id": "xxxx",
      "name": "project1",
      "vendor_key": "4855xxxxxxxxxxxxxxxxxxxxxxxxeae2",
      "sign_key": "4855xxxxxxxxxxxxxxxxxxxxxxxxeae2",
      "recording_server": null,
      "status": 1,
      "created": 1464165672
    }
}

    重置主要 App 证书

    重置指定项目的主要 App 证书。

  • 如果原来的主要 App 证书泄漏了，你可以使用该方法对主要 App 证书进行重置。
  • 如果该项目的主要 App 证书尚未启用，调用该方法会启用主要 App 证书。

    • 接口原型

    • 方法：POST
    • 接入点：https://api.sd-rtn.com/dev/v1/reset_signkey

    请求参数

    请求包体参数

    在请求包体中传入以下参数：

    参数 类型 描述
    id String （必填）项目 ID，可以通过调用获取所有项目信息 API 获取。

    请求示例

    请求包体

    {
  "id": "xxxx"
}

    响应参数

    可能的响应状态码详见状态码汇总表。

    如果状态码不为 201，则请求失败。响应包体中包含 message 字段，描述失败的具体原因。

    如果状态码为 201，则请求成功，响应包体包含如下参数：

    参数 类型 描述
    project Object 项目的信息，包含以下字段：
    • id：String。项目 ID。
    • name：String。项目名称。
    • vendor_key：String。项目的 App ID。
    • sign_key：String。项目的主要 App 证书。
    • recording_server：String。录制项目服务器 IP 地址：
      • 如果你使用的是本地服务端录制 SDK v1.9.0 及之前版本，请关注此字段。
      • 如果你使用的是本地服务端录制 SDK v1.11.0 及之后版本，请忽略此字段。
    • status：Number。项目状态：
      • 1：启用
      • 0：禁用
    • created：Number。项目的创建时间，Unix 时间戳，单位为秒。

    响应示例

    请求成功的响应示例：

    {
    "project": {
      "id": "xxxx",
      "name": "project1",
      "vendor_key": "4855xxxxxxxxxxxxxxxxxxxxxxxxeae2",
      "sign_key": "4855xxxxxxxxxxxxxxxxxxxxxxxxeae2",
      "recording_server": null,
      "status": 1,
      "created": 1464165672
    }
}

    获取指定项目的用量

    获取指定项目的用量数据。

  • 请确保填写有效的项目 ID，否则无法获取用量数据。
  • 该方法支持最多查询过去 12 月内的用量。
  • 建议查询时段不要包含当天，因为当天数据会持续变化。

    • 接口原型

    • 方法：GET
    • 接入点：https://api.sd-rtn.com/dev/v3/usage

    请求参数

    查询参数

    在请求路径中传入以下查询参数：

    参数 类型 描述
    project_id String （必填）项目 ID，可以通过调用获取所有项目信息 API 获取。
    from_date String （必填）查询开始日期，格式为 YYYY-MM-DD。
    to_date String （必填）查询结束日期，格式为 YYYY-MM-DD。
    business String （必填）指定业务类型。可设为以下值：
  • default: 音视频。不包括小程序的用量。
  • transcodeDuration: 转码。
  • recording: 本地服务端录制。
  • cloudRecording: 云端录制。
  • miniapp: 小程序。
    		•

    请求示例

    请求路径

    https://api.sd-rtn.com/dev/v3/usage?project_id=rxxxxxxj5u&from_date=2021-10-12&to_date=2021-12-14&business=default

    响应参数

    可能的响应状态码详见状态码汇总表。

    如果状态码不为 200，则请求失败。响应包体中包含 message 字段，描述失败的具体原因。

    如果状态码为 200，则请求成功，响应包体包含如下参数：

    参数 类型 描述
    meta Object 元数据，解释 usage 参数中 durationAudioAll, durationVideo1080P, durationVideo2K, durationVideo4K， durationVideoHd 和 durationVideoHdp 的含义。
    • durationAudioAll：Object 类型。总音频时长。
      • cn：String 类型。durationAudioAll 的中文含义，即“总音频时长”。
      • en：String 类型。durationAudioAll 的英文含义，即 “Total Audio Duration”。
      • unit：String 类型。时长单位，秒。
    • durationVideo1080P：Object 类型。全高清（Full HD）视频的时长。
      • cn：String 类型。durationVideo1080P 的中文含义，即 “1080P视频时长（含录制）”。
      • en：String 类型。durationVideo1080P 的英文含义，即 “Full HD Video Duration（including Recording)”。
      • unit：String 类型。时长单位，秒。
    • durationVideo2K：Object 类型。2K 视频的时长。
      • cn：String 类型。durationVideo2K 的中文含义，即 “2K视频时长（含录制）”。
      • en：String类型。durationVideo2K 的英文含义，即 “2K Video Duration（including Recording)”。
      • unit：String 类型。时长单位，秒。
    • durationVideo4K：Object 类型。2K+ 视频的时长。
      • cn：String 类型。durationVideo4K 的中文含义，即 “2K+视频时长（含录制）”。
      • en：String 类型。 durationVideo4K 的英文含义，即 “2K+ Video Duration（including Recording)”。
      • unit：String 类型。时长单位，秒。
    • durationVideoHd：高清视频的时长。
      • cn：String 类型。durationVideoHd 的中文含义，即 “HD视频时长（含录制）”。
      • en：String 类型。 durationVideoHd 的英文含义，即 “HD Video Duration (including On-premise Recording)”。
      • unit：String 类型。时长单位，秒。
    • durationVideoHdp：超高清视频的时长。
      • cn：String 类型。durationVideoHdp 的中文含义，即 “HDP视频时长（含录制）”。
      • en：String 类型。durationVideoHdp 的英文含义，即 “HDP Video Duration（including Recording)”。
      • unit：String 类型。时长单位，秒。
    usages Array 指定项目在查询时间段内的用量。由多个 Object 组成，一个 Object 表示一天的用量。每个 Object 包含以下字段：
    • date：Number 类型，日期，使用 UTC 时间和 Unix 时间戳。
    • usage：Object 类型，日用量。
      • durationAudioAll：Number 类型。音频总时长，单位为秒。
      • durationVideo1080P：Number 类型。全高清（Full HD）视频的时长，单位为秒。
      • durationVideo2K：Number 类型。2K 视频的时长，单位为秒。
      • durationVideo4K：Number 类型。2K+ 视频的时长，单位为秒。
      • durationVideoHd：Number 类型。高清视频的时长，单位为秒。
      • durationVideoHdp：Number 类型。超高清视频的时长，单位为秒。

    响应示例

    请求成功的响应示例：

    {
    "meta": {
        "durationAudioAll": {
            "cn": "总音频时长",
            "en": "Total Audio Duration",
            "unit": "second"
        },
        "durationVideo1080P": {
            "cn": "1080P视频时长（含录制）",
            "en": "Full HD Video Duration（including Recording)",
            "unit": "second"
        },
        "durationVideo2K": {
            "cn": "2K视频时长（含录制）",
            "en": "2K Video Duration（including Recording)",
            "unit": "second"
        },
        "durationVideo4K": {
            "cn": "4K视频时长（含录制）",
            "en": "4K Video Duration（including Recording)",
            "unit": "second"
        },
        "durationVideoHd": {
            "cn": "HD视频时长（含录制）",
            "en": "HD Video Duration（including Recording）",
            "unit": "second"
        },
        "durationVideoHdp": {
            "cn": "HDP视频时长（含录制）",
            "en": "HDP Video Duration（including Recording)",
            "unit": "second"
        }
    },
    "usages": [
        {
            "date": "2021-10-12T00:00:00.000Z",
            "usage": {
                "durationAudioAll": 0,
                "durationVideo1080P": 0,
                "durationVideo2K": 0,
                "durationVideo4K": 0,
                "durationVideoHd": 0,
                "durationVideoHdp": 0
            }
        },
        {
            "date": "2021-10-13T00:00:00.000Z",
            "usage": {
                "durationAudioAll": 779,
                "durationVideo1080P": 0,
                "durationVideo2K": 0,
                "durationVideo4K": 0,
                "durationVideoHd": 60,
                "durationVideoHdp": 0
            }
        },
        {
            "date": "2021-10-14T00:00:00.000Z",
            "usage": {
                "durationAudioAll": 0,
                "durationVideo1080P": 0,
                "durationVideo2K": 0,
                "durationVideo4K": 0,
                "durationVideoHd": 0,
                "durationVideoHdp": 0
            }
        }
    ]
}

    响应状态码

    下表列出了可能出现的响应状态码。

    • 如果状态码为 200 或 201，表示请求成功。

    • 如果状态码不为 200 或 201，则请求失败。响应包体中包含 message 字段，描述失败的具体原因。

    响应状态码 描述
    200 操作成功。
    201 请求成功并创建了新的资源。
    400 请求无效。可能的原因包括：
  • 项目名称不能重复。
  • 公司已被禁用
  • 项目数量超出最大限制。
    		•
    401 未经授权的（App ID/Customer Certificate 匹配错误）。
    403 禁止访问。
    404 请求的资源未找到。
    415 不支持的媒体类型。请确保 Headers 中的 Content-Type 设置为 application/json。
    429 请求过于频繁。
    500 服务器内部错误。

    保障 REST 服务高可用

    为保障 REST 服务的高可用，避免因区域网络故障造成的服务不可用，声网提供切换域名的方案。

    切换域名操作

    1. 根据你的业务服务器所在地设置主域名：
      • 业务服务器 DNS 地址位于中国大陆时，设置主域名为 api.sd-rtn.com。
      • 业务服务器 DNS 地址位于中国大陆以外的国家或地区时，设置主域名为 api.agora.io。
    2. 当使用主域名发起 RESTful API 请求失败时，使用该域名重试一次。
    3. 如果步骤 2 的重试依然失败，使用备用的主域名重试：
      • 如果当前设置的主域名为 api.sd-rtn.com，备用的主域名指 api.agora.io。
      • 如果当前设置的主域名为 api.agora.io，备用的主域名指 api.sd-rtn.com。
    4. 如果步骤 3 的重试依然失败，使用与当前解析区域相邻的区域域名重试。
      举例说明：假设你的业务服务器位于欧洲，你设置主域名为 api.agora.io，而且业务服务器解析主域名解析到德国。德国位于欧洲中部 api-eu-central-1.agora.io，查域名信息表可知，相邻区域为欧洲西部 api-eu-west-1.agora.io 或 api-eu-west-1.sd-rtn.com。因此，出现网络故障且步骤 2、3 的重试失败时，请使用 api-eu-west-1.agora.io 或 api-eu-west-1.sd-rtn.com 域名重试。

    注意事项

    • 为避免重试请求过于频繁，超过声网服务所规定的 QPS（每秒请求数），声网建议你使用退避策略。例如，第一次等待 1 秒后重试、第二次等待 3 秒后重试、第三次等待 6 秒后重试。
    • 如果是网络问题而非 DNS 解析域名问题导致的请求失败，声网建议你跳过步骤 3，直接进行步骤 4。
    • 切换至区域域名前，请确保你使用的业务（例如，云端录制、云信令、频道管理等 REST 服务）在该区域有部署服务。

    域名信息

    主域名 区域域名 地理区域
    api.sd-rtn.com api-us-west-1.sd-rtn.com 美国西部
    api-us-east-1.sd-rtn.com 美国东部
    api-ap-southeast-1.sd-rtn.com 亚太东南
    api-ap-northeast-1.sd-rtn.com 亚太东北
    api-eu-west-1.sd-rtn.com 欧洲西部
    api-eu-central-1.sd-rtn.com 欧洲中部
    api-cn-east-1.sd-rtn.com 中国华东
    api-cn-north-1.sd-rtn.com 中国华北
    api.agora.io api-us-west-1.agora.io 美国西部
    api-us-east-1.agora.io 美国东部
    api-ap-southeast-1.agora.io 亚太东南
    api-ap-northeast-1.agora.io 亚太东北
    api-eu-west-1.agora.io 欧洲西部
    api-eu-central-1.agora.io 欧洲中部
    api-cn-east-1.agora.io 中国华东
    api-cn-north-1.agora.io 中国华北