Skip to content

非公式本サイトは非公式の日本語ドキュメントであり、Cloudflare 公式サイトではありません。最新情報はdevelopers.cloudflare.comをご確認ください。

Connection API

最終更新 Markdown で表示Agent セットアップ

Cloudflare Realtime は、HTTPS API エンドポイントでピア接続とメディアトラックの管理を簡素化します。これらのエンドポイントで、セッションの管理、トラックの追加・削除、セッション情報の取得を効率よく行えます。

API エンドポイント

  • 新しいセッションを作成する: Cloudflare Realtime 上に新しいセッションを開始します。以降のエンドポイントで変更できます。
    • POST /apps/{appId}/sessions/new
  • 新しいトラックを追加する: 既存セッションにメディアトラック（音声または動画）を追加します。
    • POST /apps/{appId}/sessions/{sessionId}/tracks/new
  • トラックを更新する: 既存のトランシーバーを再利用してトラックを変更します。
    • PUT /apps/{appId}/sessions/{sessionId}/tracks/update
  • セッションを再ネゴシエーションする: 新しいトラックや既存トラックの変更に合わせ、セッションのネゴシエーション状態を更新します。
    • PUT /apps/{appId}/sessions/{sessionId}/renegotiate
  • トラックを閉じる: 指定したトラックをセッションから削除します。
    • PUT /apps/{appId}/sessions/{sessionId}/tracks/close
  • DataChannel トランスポートを確立する: server-events チャネルを引き、DataChannel トランスポートを確立します。DataChannel を追加する前に呼び出します。
    • POST /apps/{appId}/sessions/{sessionId}/datachannels/establish
  • DataChannel を追加する: ローカル DataChannel を公開するか、リモートのものを引きます（オプションの waitForAck、canReply）。
    • POST /apps/{appId}/sessions/{sessionId}/datachannels/new
  • DataChannel を更新する: すでに引いたリモート DataChannel のフラグを付与または取り消します（例: canReply）。
    • PUT /apps/{appId}/sessions/{sessionId}/datachannels/update
  • DataChannel を閉じる: 指定した DataChannel をセッションから削除します。
    • PUT /apps/{appId}/sessions/{sessionId}/datachannels/close
  • セッション情報を取得する: 特定セッションの詳細情報を取得します。
    • GET /apps/{appId}/sessions/{sessionId}

API とスキーマの全体を見る（OpenAPI 形式）

シークレットの扱い

App ID とそのシークレットは安全に管理することが重要です。トラック ID とセッション ID は公開しても構いませんが、悪用を防ぐために保護してください。バックエンドサーバーがリクエストの出所を正しく認証しないと、攻撃者がこれらの ID を悪用し、自分以外のセッションのトラックを閉じるリクエストを送るなどしてサービスを妨害できます。バックエンドサーバーへのリクエストのセキュリティと真正性を確保することが、アプリケーションの完全性を保つうえで不可欠です。

STUN サーバーと TURN サーバーの利用

Cloudflare Realtime は、ほとんどのシナリオで TURN サーバーなしで効率よく動くよう設計されています。Cloudflare は Realtime 向けにパブリックに到達可能な IP アドレスを公開しているためです。ただし、ピアの発見と接続を助けるために 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: 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

役に立ちましたか？