RICOH Live Streaming REST API: アクティビティ API (v1)
Download OpenAPI specification:Download
RICOH Live Streaming REST API は Live Streaming サービスの公開 REST API です。
本ページはアクティビティ API の仕様について記載します。
アクティビティとは、RICOH Live Streaming で発生したイベントのクライアントアプリに対する表現形式であり、本 API を利用することでクライアントアプリは Webhook によるアクティビティの通知を受けることができます。
共通仕様
- REST API の認証/認可に失敗した場合、ステータスコード 401 のレスポンスが返却されます
Webhook 設定登録時にクライアントアプリにより設定された Webhook URL の検証
Webhook 設定の登録時には指定された Webhook の URL が正当なクライアントアプリのものであることを検証するため以下のようなフローを実行します。
RICOH Live Streaming は Webhook 登録リクエストを受け取ると webhook_url の URL に対して Webhook URL の検証リクエストを送信します。
- クライアントアプリはこれに対して所定のレスポンスを返却することで、
webhook_urlが正当なクライアントアプリの Webhook URL だと証明する必要があります - アクティビティ Webhook 設定登録 > Callbacks > Webhook URL の検証 に記載された仕様に従ってこの処理の実装が必要です
Webhook 通知時に RICOH Live Streaming から送られた Webhook メッセージの検証
Webhook の URL に対して通知されたメッセージが RICOH Live Streaming からのものであることをクライアントアプリが検証することが可能です。
- RICOH Live Streaming Webhook 通知時に所定の方法で作成された署名を
X-RICOH-LS-Signatureヘッダに付与して送信します - クライアントアプリはこの署名を検証し、RICOH Live Streaming から送られた通知であることを検証できます
- アクティビティ Webhook 設定登録 > Callbacks > Activity Webhook の通知 に記載された仕様にしたがってこの処理を実装する事が可能です
Webhook 通知のリトライ
Live Streaming からクライアントアプリへの Webhook リクエストで ネットワークエラー、リクエストタイムアウト (30 秒)、または 500 系のエラーが発生した場合、以下の戦略に基づいてリトライを行います。
- 前回のエラーからそれぞれ、5 秒後, 10 秒後, 20 秒後, 40 秒後にリトライし、成功した時点で終了します
- 上記の 4 回リトライしても成功しない場合はその Webhook 通知を諦めます
アクティビティ Webhook 設定登録
- アクティビティ発生時にクライアントアプリ通知される Webhook の URL を設定します
- RICOH Live Streaming はこのリクエストを受け付けると、
webhook_urlの URL に対して、[Callbacks] の [Webhook URL の検証] に記載する POST リクエストを送出します- クライアントアプリケーションはこのリクエストを受けたら [Webhook URL の検証] に記載された所定のレスポンスを返す必要があります
- RICOH Live Streaming はこのレスポンスを受けて検証に成功すれば Webhook 設定の登録を受け付けます
- すでに Webhook 設定が登録済みだった場合、既存の設定は上書きされます
Authorizations:
path Parameters
| client_id required | string
|
Request Body schema: application/json
アクティビティ Webhook 設定を更新するための WebhookConfig オブジェクト
| webhook_url required | string <= 255 characters
|
Responses
Callbacks
Request samples
- Payload
{- "webhook_url": "string"
}Response samples
- 200
- 400
{- "webhook_url": "string"
}Callback payload samples
{- "type": "webhook.verification",
- "challenge": "string"
}| activity_id required | string アクティビティを一意に識別する ID |
| env required | string Enum: "prod" "dev" アクティビティの発生した環境 |
| created_at required | string <date-time> アクティビティが生成された時刻
|
| type required | string Value: "room.started" RoomInstance の生成を示すアクティビティ種別 |
required | object (ActivityRoom) ある Room の生成時の情報をまとめた構造体。
|
{- "activity_id": "string",
- "env": "prod",
- "created_at": "2019-08-24T14:15:22Z",
- "type": "room.started",
- "data": {
- "room_id": "string",
- "room_instance_id": "string",
- "room_spec": {
- "type": "sfu",
- "max_connections": 1,
- "media_control": {
- "bitrate_reservation_mbps": 10
}, - "recording": {
- "recording_on_start": false,
- "composition_recording": {
- "enabled": false,
- "format": "mp4",
- "video": {
- "resolution": "auto",
- "max_bitrate_kbps": "auto"
}, - "audio": {
- "codec": "aac"
}
}
}, - "classification_label": "default"
}, - "recording_status": {
- "in_recording": true
}, - "started_at": "2019-08-24T14:15:22Z",
- "ended_at": "2019-08-24T14:15:22Z"
}
}| type required | string Value: "webhook.verification"
|
| challenge required | string RICOH Live Streaming がランダムに生成した文字列 |
{- "type": "webhook.verification",
- "challenge": "string"
}| challenge_signature required | string Webhook URL の検証リクエストで受け取った |
{- "challenge_signature": "string"
}