连接 API

Cloudflare Realtime 通过 HTTPS API 端点简化了对 peer 连接和媒体轨道的管理。这些端点允许开发人员高效地管理会话、添加或删除轨道以及收集会话信息。

• 创建新会话：在 Cloudflare Realtime 上发起一个新会话，可以使用下面列出的其他端点进行修改。
  • POST /apps/{appId}/sessions/new
• 添加新轨道：向现有会话中添加媒体轨道（音频或视频）。
  • POST /apps/{appId}/sessions/{sessionId}/tracks/new
• 重新协商会话：更新会话的协商状态，以适应新轨道或现有轨道的更改。
  • PUT /apps/{appId}/sessions/{sessionId}/renegotiate
• 关闭轨道：从会话中移除指定的轨道。
  • PUT /apps/{appId}/sessions/{sessionId}/tracks/close
• 检索会话信息：获取有关特定会话的详细信息。
  • GET /apps/{appId}/sessions/{sessionId}

查看完整 API 和 schema (OpenAPI 格式)

安全地管理 App ID 及其密钥至关重要。虽然轨道 (track) ID 和会话 (session) ID 可以是公开的，但也应妥善保护以防止滥用。如果您的后端服务器未正确验证请求来源，攻击者可能会利用这些 ID 来中断服务，例如通过发送关闭除其自身以外的会话上的轨道的请求。确保向您的后端服务器发送的请求的安全性和真实性，对于维护应用程序的完整性至关重要。

Cloudflare Realtime 旨在多数场景下无需 TURN 服务器即可高效运行，因为 Cloudflare 为 Realtime 公开了公开可路由的 IP 地址。然而，为了促进 peer 发现和连接，集成 STUN 服务器可能很有必要。

• Cloudflare STUN 服务器：stun.cloudflare.com:3478

使用 Cloudflare 的 STUN 服务器可以帮助简化 Realtime 应用程序的连接过程。

本节概述了简单会话的典型生命周期，重点介绍仅限音频的应用程序。它展示了当新的远程客户端加入或离开时，客户端如何收到后端服务器的通知，而引入视频会在会话中带来额外的轨道和考虑因素。

sequenceDiagram
    participant WA as WebRTC Agent
    participant BS as Backend Server
    participant CA as Realtime API

    Note over BS: 客户端加入

    WA->>BS: Request
    BS->>CA: POST /sessions/new
    CA->>BS: newSessionResponse
    BS->>WA: Response

    WA->>BS: Request
    BS->>CA: POST /sessions/<ID>/tracks/new (Offer)
    CA->>BS: newTracksResponse (Answer)
    BS->>WA: Response

    WA-->>CA: ICE 连接性检查
    Note over WA: iceconnectionstatechange (已连接)
    WA-->>CA: DTLS 握手
    Note over WA: connectionstatechange (已连接)

    WA<<->>CA: *媒体流*

    Note over BS: 远程客户端加入

    WA->>BS: Request
    BS->>CA: POST /sessions/<ID>/tracks/new
    CA->>BS: newTracksResponse (Offer)
    BS->>WA: Response

    WA->>BS: Request
    BS->>CA: PUT /sessions/<ID>/renegotiate (Answer)
    CA->>BS: OK
    BS->>WA: Response

    Note over BS: 远程客户端离开

    WA->>BS: Request
    BS->>CA: PUT /sessions/<ID>/tracks/close
    CA->>BS: closeTracksResponse
    BS->>WA: Response

    Note over BS: 客户端离开

    WA->>BS: Request
    BS->>CA: PUT /sessions/<ID>/tracks/close
    CA->>BS: closeTracksResponse
    BS->>WA: Response