SRS接口文档

你知唔知我系靓仔

SRS接口文档

Orxy API 文档整理

1. HTTP API

版本：5.0 (Stable)

概述： SRS 提供 HTTP 接口，供外部程序管理服务器，并支持跨域（JavaScript 可以直接控制和获取服务器的各种信息）。通过 HTTP API，可以使用 srs-console 连接到你的服务器。

工作流：

+--------+               +-------+
| Chrome/Your Application +--HTTP-API-->--+  SRS  +
+--------+               +-------+

目标： SRS 的 HTTP 接口遵循最简单原则，主要包括：

  • 只提供 JSON 数据格式接口，要求请求和响应的数据全都是 JSON。
  • srs-console 可访问 SRS 的 API，提供管理后台。
  • 发生错误时，支持 HTTP 错误码，或者 JSON 中的 code 错误码。

构建： SRS 自动打开 HTTP API 选项，参考 configure 选项：

./configure && make

配置： 配置文件需要开启 http-api：

listen              1935;
stats {
    network         0;
    disk            sda sdb xvda xvdb;
}
http_api {
    enabled         on;
    listen          1985;
    crossdomain     on;
    raw_api {
        enabled off;
        allow_reload off;
    }
    auth {
        enabled         on;
        username        admin;
        password        admin;
    }
    https {
        enabled on;
        listen 1986;
        key ./conf/server.key;
        cert ./conf/server.crt;
    }
}
vhost __defaultVhost__ {
}

启动： 启动服务器：

./objs/srs -c http-api.conf

访问 API： 浏览器打开地址：

http://127.0.0.1:1985/api/v1
https://127.0.0.1:1986/api/v1

性能： 机器：虚拟机 CentOS6-64 位，4CPU，T430 笔记本，VirtualBox 10% CPU，10000 次请求，27 秒，平均 370 次请求/秒，30 毫秒一个请求

访问 API： 直接在浏览器中就可以访问，或者用 curl 发起 HTTP 请求。

API 导航： SRS 提供了 API 的导航，即所有支持的 API 及描述。

地址是：http://192.168.1.170:1985/api/v1，主要包含的子 API 有：

API Example Description
server 4481 服务器标识
versions /api/v1/versions 获取服务器版本信息
summaries /api/v1/summaries 获取服务器的摘要信息
rusages /api/v1/rusages 获取服务器资源使用信息
self_proc_stats /api/v1/self_proc_stats 获取服务器进程信息
system_proc_stats /api/v1/system_proc_stats 获取服务器所有进程情况
meminfos /api/v1/meminfos 获取服务器内存使用情况
authors /api/v1/authors 获取作者、版权和 License 信息
features /api/v1/features 获取系统支持的功能列表
requests /api/v1/requests 获取请求的信息，即当前发起的请求的详细信息
vhosts /api/v1/vhosts 获取服务器上的 vhosts 信息
streams /api/v1/streams 获取服务器的 streams 信息
clients /api/v1/clients 获取服务器的 clients 信息，默认获取前 10 个
configs /api/v1/configs CUID 配置，RAW API
publish /rtc/v1/publish/ WebRTC 推流的 API
play /rtc/v1/play/ WebRTC 播放流的 API

错误码： SRS 可能返回 HTTP 错误，即 Status 不等于 200；或者在 HTTP Status 为 200 时，响应的 JSON 的 code 不为 0。

跨域： SRS HTTP API 支持跨域，JavaScript 可以直接调用 SRS 的 HTTP API。

HTTPS API： SRS 内置支持 HTTPS API，只需要开启配置 https：

http_api {
    enabled         on;
    listen          1985;
    https {
        enabled on;
        listen 1990;
        key ./conf/server.key;
        cert ./conf/server.crt;
    }
}

HTTP 和 HTTPS Proxy： SRS 可以和 HTTP/HTTPS 代理一起工作得很好，比如 Nginx, HTTPX, CaddyServer 等。

Server ID： SRS 返回的 API 中都会带有 server 的信息，即 Server 的 ID，用来标识服务器。客户端在获取信息时，必须检查 ServerID 是否改变，改变时就是服务器重启，之前所有的数据都应该作废了。

WebRTC Publish： 使用 WebRTC 推流到 SRS 时，需要先调用 API 交换 SDK，SRS 支持 WHIP 协议。

WebRTC Play： 拉流或播放时，需要调用另外的 API，请求格式和 publish 一样，SRS 支持 WHEP 协议。

Summaries： SRS 提供系统的摘要信息接口，譬如当前的内存、CPU、网络、负载使用率。

Vhosts： SRS 提供获取所有 vhost 的接口。

Streams： SRS 提供获取所有 stream 的接口。

Clients： SRS 提供查询客户端信息的接口。

Kickoff Client： 可以踢掉连接的用户，SRS 提供了 HTTP RESTful 接口。

HTTP RAW API： SRS 支持 RAW API，一般的服务器只能提供读(Read)形式的 API，但是 SRS 提供写(Write)形式的 API，譬如 Reload 和修改系统配置等所有改写系统的行为。

Authentication： SRS 在 5.0.152+ 或者 6.0.40+ 版本开始支持 HTTP API 鉴权，可以通过配置 http_api.auth 开启。

2. HTTP Callback

概述： 服务器端定制的实现方式，就是 HTTP 回调。譬如当客户端连接到 SRS 时，回调指定的 HTTP 地址，这样可以实现验证功能。

工作流：

+--------+     +--------+                    +-----------------------+
| FFmpeg |-->--+  SRS   |--HTTP-Callback-->--+  Your Business Server |
+--------+     +--------+                    +-----------------------+

使用： 首先，运行 SRS，在配置中启用 HTTP 回调：

./objs/srs -c conf/http.hooks.callback.conf

启动演示 HTTP 回调服务器，这是您的业务服务器：

go run research/api-server/server.go

将流发布到 SRS，参数为：

ffmpeg -re -i doc/source.flv -c copy -f flv rtmp://localhost/live/livestream?k=v

编译： SRS 总是开启 HttpCallback。

配置 SRS： 这里有一个示例 conf/http.hooks.callback.conf 可用，演示了常见回调事件的配置，可直接使用。

协议： HTTP 回调的格式如下，以 on_publish 为例：

POST /api/v1/streams HTTP/1.1
Content-Type: application-json

Body:
{
  "server_id": "vid-0xk989d",
  "action": "on_publish",
  "client_id": "341w361a",
  "ip": "127.0.0.1",
  "vhost": "__defaultVhost__",
  "app": "live",
  "tcUrl": "rtmp://127.0.0.1:1935/live?vhost=__defaultVhost__",
  "stream": "livestream",
  "param": "",
  "stream_url": "video.test.com/live/livestream",
  "stream_id": "vid-124q9y3"
}

Heartbeat： SRS 将向 HTTP 回调服务器发送心跳信号。这允许你监控 SRS 服务器的健康状况。

HTTP callback events： SRS 的回调事件包括：

  • on_publish
  • on_unpublish
  • on_play
  • on_stop
  • on_dvr
  • on_hls

Response： 如果回调成功，必须响应正确的格式的数值，否则就会返回错误给客户端导致推流或播放失败。

3. Prometheus Exporter

概述： SRS 的可观测性是支撑业务的运营的能力，主要指监控(Prometheus Exporter)、分布式链路追踪(APM)、上下文日志(Cloud Logging)三个核心能力，以及基于这些能力的运营大盘、监控系统、问题排查、日志收集和分析等功能。

配置： Exporter 的配置如下，推荐使用环境变量方式开启配置：

exporter {
    enabled off;
    listen 9972;
    label cn-beijing;
    tag cn-edge;
}

使用： 首先，编译和启动 SRS，要求 SRS 5.0.86+：

./configure && make
env SRS_ENV_ONLY=on SRS_EXPORTER_ENABLED=on SRS_LISTEN=1935 \
  ./objs/srs -e

接着，我们启动 FFmpeg 推流：

docker run --rm -it registry.cn-hangzhou.aliyuncs.com/ossrs/srs:encoder ffmpeg -stream_loop -1 -re -i doc/source.flv \
  -c copy -f flv rtmp://host.docker.internal/live/livestream

然后，启动 node_exporter，收集节点的数据，这样和 SRS 的服务器数据可以形成完整的监控数据:

docker run --rm -p 9100:9100 prom/node-exporter

最后，编写配置文件 prometheus.yml，内容如下：

scrape_configs:
  - job_name: "node"
    metrics_path: "/metrics"
    scrape_interval: 5s
    static_configs:
      - targets: ["host.docker.internal:9100"]
  - job_name: "srs"
    metrics_path: "/metrics"
    scrape_interval: 5s
    static_configs:
      - targets: ["host.docker.internal:9972"]

启动 Prometheus：

docker run --rm -v $(pwd)/prometheus.yml:/etc/prometheus/prometheus.yml \
  -p 9090:9090 prom/prometheus

Usage for Grafana： 首先启动 Grafana：

docker run --rm -it -p 3000:3000 \
  -e GF_SECURITY_ADMIN_USER=admin \
  -e GF_SECURITY_ADMIN_PASSWORD=12345678 \
  -e GF_USERS_DEFAULT_THEME=light \
  grafana/grafana

然后打开 Grafana 页面：http://localhost:3000/

输入用户名 admin，以及密码 12345678 就可以进入 Grafana 后台了。

执行命令添加 Prometheus 的 DataSource：

curl -s -H "Content-Type: application/json" \
    -XPOST http://admin:12345678@localhost:3000/api/datasources \
    -d '{
    "name": "prometheus",
    "type": "prometheus",
    "access": "proxy", "isDefault": true,
    "url": "http://host.docker.internal:9090"
}'

执行命令导入 HelloWorld 图表：

data=$(curl https://raw.githubusercontent.com/ossrs/srs-grafana/main/dashboards/helloworld-import.json 2>/dev/null)
curl -s -H "Content-Type: application/json" \
    -XPOST http://admin:12345678@localhost:3000/api/dashboards/db \
    --data-binary "{\"dashboard\":${data},\"overwrite\":true,\"inputs\":[],\"folderId\":0}"

导入后就可以在仪表盘中看到了。

备注：

  • 请确保所有 IP 地址和端口号根据实际情况进行调整。
  • 请确保所有配置文件和命令在实际环境中正确执行。
  • 请确保所有依赖服务（如 Prometheus、Grafana 等）正确安装和配置。

希望这份文档能帮助您更好地集成和使用 Orxy 的 API。如果有任何问题或需要进一步的帮助，请随时联系我们。

渝ICP备16007848号-4