← Cloudflare Realtime / realtime / sfu

Connection API

Cloudflare Realtime упрощает управление пиринговыми соединениями и медиатреками с помощью эндпойнтов HTTPS API. Эти эндпойнты позволяют разработчикам эффективно управлять сессиями, добавлять и удалять треки, а также получать информацию о сессии.

• Создание новой сессии: Создаёт новый Session в Cloudflare Realtime, который можно изменить с помощью других эндпойнтов ниже.
  • POST /apps/{appId}/sessions/new
• Добавьте новый трек: добавляет медиатрек (аудио или видео) в существующую сессию.
  • POST /apps/{appId}/sessions/{sessionId}/tracks/new
• Обновление треков: изменяет треки за счет повторного использования существующих объектов transceiver.
  • PUT /apps/{appId}/sessions/{sessionId}/tracks/update
• Повторное согласование Session: Обновляет состояние согласования сессии с учетом новых треков или изменений в существующих.
  • PUT /apps/{appId}/sessions/{sessionId}/renegotiate
• Закройте трек: Удаляет указанную дорожку из сессии.
  • PUT /apps/{appId}/sessions/{sessionId}/tracks/close
• Установка транспорта DataChannel: Получает server-events канал для установления транспорта DataChannel. Вызовите это перед добавлением DataChannels.
  • POST /apps/{appId}/sessions/{sessionId}/datachannels/establish
• Add DataChannels: Публикует локальный DataChannel или получает удаленный (необязательный waitForAck, canReply).
  • POST /apps/{appId}/sessions/{sessionId}/datachannels/new
• Обновление DataChannels: Устанавливает или снимает флаги для уже полученного удалённого DataChannel (например canReply).
  • PUT /apps/{appId}/sessions/{sessionId}/datachannels/update
• Закройте DataChannels: Удаляет указанный DataChannel из сессии.
  • PUT /apps/{appId}/sessions/{sessionId}/datachannels/close
• Получение информации о Session: Получает подробную информацию о конкретном Session.
  • GET /apps/{appId}/sessions/{sessionId}

Просмотр полного API и схемы (формат OpenAPI)

Крайне важно надёжно защищать App ID и его секрет. Хотя track ID и session ID могут быть публичными, их всё равно следует защищать от неправомерного использования. Если ваш бэкенд-сервер не проверяет должным образом источник запросов, злоумышленник может воспользоваться этими идентификаторами, чтобы нарушить работу сервиса, например отправляя запросы на закрытие треков в чужих сессиях. Обеспечение безопасности и подлинности запросов к вашему бэкенд-серверу критически важно для сохранения целостности вашего приложения.

Cloudflare Realtime спроектирован так, чтобы в большинстве сценариев эффективно работать без TURN-серверов, поскольку Cloudflare предоставляет для Realtime общедоступный маршрутизируемый IP-адрес. Тем не менее для обнаружения узлов и установления соединения может потребоваться STUN-сервер.

• Cloudflare STUN-сервер: stun.cloudflare.com:3478

Использование STUN-сервера Cloudflare может облегчить процесс установления соединения для приложений Realtime.

В этом разделе представлен обзор типичного жизненного цикла простой сессии на примере приложений только с аудио. Показано, как backend-сервер уведомляет клиентов о присоединении и выходе новых удалённых клиентов; добавление видео привнесло бы в сессию дополнительные треки и нюансы.

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

    Note over BS: Client Joins

    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 Connectivity Check
    Note over WA: iceconnectionstatechange (connected)
    WA-->>CA: DTLS Handshake
    Note over WA: connectionstatechange (connected)

    WA<<->>CA: *Media Flow*

    Note over BS: Remote Client Joins

    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: Remote Client Leaves

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

    Note over BS: Client Leaves

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