イベントウェブフック

概要

Sora は、予め設定しておいた URL に、シグナリングの接続や切断、録画の終了といった様々なイベントを通知するウェブフックの機能を持っています。

この機能を使うことで、Sora のイベントをアプリケーション側と簡単に連携することが可能です。

注意

event_webhook_url を有効にしない場合でも log/event_webhook.log は生成されます。

解説

event_webhook_url

デフォルト

未設定

イベント通知の送り先の URL です。イベントウェブフック機能を使用する場合は指定してください。

この URL には HTTPS の URL を指定することも可能です。

HTTPS の URL を指定する場合は、通知先のアプリケーションには正規の認証局から発行された証明書を使用してください。

自己署名証明書等の正規の認証局から発行されていない証明書を使用した場合には、信頼できないと判断しエラーになります。

接続イベント

  • connection.createdconnection.destroyed はセットです。

  • connection.created が通知されずに connection.destroyed が通知されることはありません。

  • connection.created が通知された場合、 connection.destroyed必ず 通知されます。

  • conneciton.created の後に connection.destroyed が通知されます。順番は保証されます。

共通項目

  • id

    • イベント毎の ID です

  • version

    • Sora のバージョンが 文字列 で入ってきます

  • label

    • sora.conf の label で指定した値が入ってきます

  • minutes

    • 接続経過時間 (分) が入ってきます

  • total_received_bytes

    • Sora がクライアントから受信したパケットの合計数です

  • total_sent_bytes

    • Sora がクライアントへ送信したパケットの合計数です

  • turn_transport_type

    • udp か tcp が入ってきます

    • TURN-UDP または TURN-TCP (TURN-TLS 含む) のどちらを利用したかがわかります

  • audio

    • false の場合は audio を使用しません

    • コーデックやビットレートが入ってくる場合は {"codec_type": "OPUS", "bit_rate": 32} が入ってきます

    • コーデックの種類は OPUS です

    • ビットレートはクライアントが送ってこない場合は含まれません

      • もし default_audio_bit_rate に値を指定していた場合はその値が利用されます

      • 最小が 6 で、最大が 510 です

  • video

    • false の場合は video を使用しません

    • コーデックやビットレートが入ってくる場合は {"codec_type": "VP9", "bit_rate": 100} が入ってきます - コーデックの種類は VP8、VP9、H264 の 3 種類です - ビットレートはクライアントが送ってこない場合は sora.confdefault_video_bit_rate が使用されます

      • デフォルトは 500 です

      • 最小が 1 で、最大が 30000 です

      • 5000 より大きい値は現時点でサポート外です

  • multistream

    • マルチストリームでの接続要求を出しているかどうかの値が入ってきます

    • true の場合はマルチストリームを希望している接続です

  • role

    • sendrecv (送受信) / sendonly (送信のみ) / recvonly (受信のみ)

    • upstream (配信) / downstream (視聴) は今後廃止されます

  • event_metadata

    • この項目はオプションです

    • サーバが定義を自由にできる値です

    • 認証サーバから event_metadata を返した値が含まれます

    • 詳細は event_metadata の払い出し をご確認ください

  • channel_id

    • 認証対象のクライアントが接続要求を出しているチャネル ID です

  • client_id

    • 認証対象のクライアントが提案してきたクライアント ID です

    • sora.confallow_client_id_assignmenttrue にした場合で、 クライアントが client_id を含めてこない場合は null が入ってきます

  • connection_id

    • 認証対象のクライアントに割り当てられたユニークな ID です

  • reason

    • DisconnectChannel API または Disconnect API を利用して切断した際、オプションの reason に指定した JSON がこの reson に含まれます

    • 指定しなかった、またはそれ以外の場合は null が入ります

connection.created

接続通知

シグナリングの接続が成功して、WebRTC としての通信が開始可能になった状態を通知します。

  • channel_connections

    • 現在そのチャネルに接続しているクライアントの接続数です

    • 自分が含まれません

  • channel_upstream_connections

    • 現在そのチャネルで配信をしている配信者の接続数です

    • 自分が含まれません

  • channel_downstream_connections

    • 現在そのチャネルを視聴している視聴者の接続数です

    • 自分が含まれません

{
   "channel_id":"sora",
   "client_id": null,
   "connection_id":"4D40YWH56N5S99QHJV6GAPNHB0",
   "data":{
      "audio":{
         "codec_type":"OPUS"
      },
      "reason": null,
      "channel_connections":1,
      "channel_downstream_connections":0,
      "channel_upstream_connections":1,
      "minutes":0,
      "total_received_bytes":0,
      "total_sent_bytes":0,
      "turn_transport_type": "udp",
      "video":{
         "bit_rate":500,
         "codec_type":"VP9"
      }
   },
   "id":"KD9N57E2RN5T1BDEA7S7SH038M",
   "label":"WebRTC SFU Sora",
   "multistream":false,
   "role":"sendonly",
   "timestamp":"2017-08-13T07:08:14.346280Z",
   "type":"connection.created",
   "version":"2020.1"
}

connection.destroyed

切断通知

シグナリングの接続が切断したことを通知します。

  • channel_connections

    • 現在そのチャネルに接続しているクライアントの接続数です

    • 自分が含まれません

  • channel_upstream_connections

    • 現在そのチャネルで配信をしている配信者の接続数です

    • 自分が含まれません

  • channel_downstream_connections

    • 現在そのチャネルを視聴している視聴者の接続数です

    • 自分が含まれません

{
   "channel_id":"sora",
   "client_id": null,
   "connection_id":"3E5C6307AH3FK1EG3PXC97JGYG",
   "data":{
      "audio":{
         "codec_type":"OPUS"
      },
      "reason":{
         "code": 200,
         "message": "BAN"
      }
      "channel_connections":0,
      "channel_downstream_connections":0,
      "channel_upstream_connections":0,
      "minutes":1,
      "total_received_bytes":6962457,
      "total_sent_bytes":13168,
      "turn_transport_type": "udp",
      "video":{
         "bit_rate":500,
         "codec_type":"VP9"
      }
   },
   "id":"28PWPHTRHD31X2GZZ2HWSQ12KC",
   "label":"WebRTC SFU Sora",
   "multistream":false,
   "role":"sendonly",
   "timestamp":"2017-08-13T07:09:49.364445Z",
   "type":"connection.destroyed",
   "version":"2020.1"
}

connection.updated

接続状態更新通知

接続したタイミングから、クライアント毎の接続状態が、それぞれ 1 分間に 1 回送られてきます。

  • channel_connections

    • 現在そのチャネルに接続しているクライアントの接続数です

    • 自分が含まれます

  • channel_upstream_connections

    • 現在そのチャネルで配信をしている配信者の接続数です

    • 自分が含まれます

  • channel_downstream_connections

    • 現在そのチャネルを視聴している視聴者の接続数です

    • 自分が含まれます

{
   "channel_id":"sora",
   "client_id": null,
   "connection_id":"EYV7Y80AJ576F8VNZBS8ZA3EFG",
   "data":{
      "audio":{
         "codec_type":"OPUS"
      },
      "reason": null,
      "channel_connections":1,
      "channel_downstream_connections":0,
      "channel_upstream_connections":1,
      "minutes":1,
      "total_received_bytes":4352216,
      "total_sent_bytes":8268,
      "turn_transport_type": "udp",
      "video":{
         "bit_rate":500,
         "codec_type":"VP9"
      }
   },
   "id":"HMRVPQEXJX03D3B3WE778SJGRC",
   "label":"WebRTC SFU Sora",
   "multistream":false,
   "role":"senonly",
   "timestamp":"2017-08-13T07:09:14.282422Z",
   "type":"connection.updated",
   "version":"2020.1"
}

connection.failed

失敗通知

重要

この通知を有効にする場合は、 sora.conf にて ignore_connection_failed_webhook を無効にする必要があります。

シグナリングが失敗したり、異常が起きた場合に通知されます。

{
    "type": "connection.failed",
    "id": "<Base32-UUIDv4>",
    "role": "sendrecv | sendonly | recvonly | upstream | downstream",
    "channel_id": "<String>",
    "client_id": "<String or Base32-UUIDv4>",
    "connection_id": "<Base32-UUIDv4>",
    "timestamp": "<String>",
    "data": {
        "message": "<String>",
        "channel_connections": "<Integer>",
        "channel_upstream_connections": "<Integer>",
        "channel_downstream_connections": "<Integer>"
    }
}

録画・録音イベント

recording.report

録画報告通知

{
    "type": "recording.report",
    "id": "<Base32-UUIDv4>",
    "version": "2020.1",
    "label": "sora-stand-alone",
    "channel_id": "<String>",
    "timestamp": "<String>",
    "data": {
        "id": "<Base32-UUIDv4>",
        "created_at": "<UNIX-Time>",
        "metadata_file_path": "<String>",
        "metadata_filename": "<String>",
        "files": [
            {
                "client_id": "<String or Base32-UUIDv4>",
                "connection_id": "<Base32-UUIDv4>",
                "filename": "<String>",
                "file_path": "<String>",
                "metadata_file_path": "<String>",
                "metadata_filename": "<String>",
                "start_time_offset": "<Integer>",
                "start_timestamp": "<UTC Timestamp>",
                "stop_time_offset": "<Integer>",
                "stop_timestamp": "<UTC Timestamp>",
                "size": "<Integer>",
                "video": {
                    "codec_type": "VP8",
                    "bit_rate": 3000,
                },
                "audio": {
                    "codec_type": "OPUS"
                }
            },
            {
                "client_id": "<String or Base32-UUIDv4>",
                "connection_id": "<Base32-UUIDv4>",
                "filename": "<String>",
                "file_path": "<String>",
                "metadata_file_path": "<String>",
                "metadata_filename": "<String>",
                "start_time_offset": "<Integer>",
                "start_timestamp": "<UTC Timestamp>",
                "stop_time_offset": "<Integer>",
                "stop_timestamp": "<UTC Timestamp>",
                "size": "",
                "video": {
                    "codec_type": "VP9"
                },
                "audio": {
                    "codec_type": "OPUS"
                }
            }
        ]
    }
}

録画・録音保存イベント

archive.available

録画保存したファイルが使用可能になった通知

{
    "type": "archive.available",
    "id": "<Base32-UUIDv4>",
    "version": "2020.1",
    "label": "<String>",
    "channel_id": "<String>",
    "client_id": "<String or Base32-UUIDv4>",
    "connection_id": "<Base32-UUIDv4>",
    "timestamp": "<String>",
    "data": {
        "id": "<Base32-UUIDv4>",
        "client_id": "<String or Base32-UUIDv4>",
        "connection_id": "<Base32-UUIDv4>",
        "created_at": "<Unix Time>",
        "duration": "<Integer>",
        "filename": "<String>",
        "file_path": "<String>",
        "metadata_filename": "<String>",
        "metadata_file_path": "<String>",
        "size": "<Integer>",
        "start_time": "<Unix Time>",
        "start_timestamp": "<UTC Timestamp>",
        "video": {
            "codec_type": "<String>"
            "bit_rate": "<Integer>",
            "height": "<Integer>",
            "width": "<Integer>"
        },
        "audio": {
            "codec_type": "<String>"
        },
        "stats": {},
        "stop_time": "<Unix Time>",
        "stop_timestamp": "<UTC Timestamp>",
    }
}

stats

サポート向けに録画に利用したパケット情報の統計を格納しています。 内部向け情報のため、予告なく変更されることがあります。

archive.failed

録画ファイル保存失敗通知

{
    "type": "archive.failed",
    "id": "<Base32-UUIDv4>",
    "version": "2020.1",
    "label": "sora-stand-alone",
    "timestamp": "<String>",
    "channel_id": "<String>",
    "client_id": "<String or Base32-UUIDv4>",
    "connection_id": "<Base32-UUIDv4>"
}

スポットライト機能

警告

スポットライト機能は実験的機能のため正式版では仕様が変更される可能性があります

spotlight.changed

スポットライト変更通知

スポットライトが当たるクライアントが切り替わった際にウェブフックが飛びます。

{
  "audio": true,
  "channel_id": "sora",
  "client_id": "4D40YWH56N5S99QHJV6GAPNHB0",
  "connection_id": "4D40YWH56N5S99QHJV6GAPNHB0",
  "fixed": false,
  "id": "61159781-d95b-4f70-b6a7-9e54c95512dc",
  "label": "WebRTC SFU Sora",
  "spotlight_id": "spotlight-1",
  "timestamp": "2019.04-27T02:04:41.573373Z",
  "type": "spotlight.changed",
  "version": "2020.1",
  "video": true
}