使用方法: RTSP サーバーに接続して静止画を取得する | Remote Command

Remote Command 機能 (Sim:sendDownlinkSsh API、Sim:sendDownlinkHttp API、Sim:sendDownlinkTcp API、Sim:sendDownlinkUdp API、Sim:sendDownlinkRtsp API の利用を含む) の価格は、2025 年 8 月以降に発表予定です。それまでの間、これらの機能は無料で利用できます。

Remote Command の RTSP 機能では、IoT デバイス上で動作する RTSP (Real Time Streaming Protocol) サーバーに接続し、ビデオストリームから JPEG 形式の静止画を取得できます。取得した静止画は API レスポンスとして受信するか、SORACOM Harvest Files に保存できます。

対応プロトコル・形式

Remote Command

プロトコル: RTSP over TCP
ビデオエンコーディング: H.264
出力形式: JPEG
認証方式: 認証なし、Basic 認証

使用例

代表的な使用方法は以下のとおりです。

コマンドを受け付けた RTSP サーバーは、10 秒以内でレスポンスを返してください。

詳細な API 仕様については、Sim:sendDownlinkRtsp API を参照してください。

Basic 認証を使用する例 (パスワードを指定する例)

ユーザー名 (username) とパスワード (password) を指定します。

curl -X POST "https://api.soracom.io/v1/sims/{sim_id}/downlink/rtsp" \
  -H "X-Soracom-API-Key: $X_SORACOM_API_KEY" \
  -H "X-Soracom-Token: $X_SORACOM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "snapshot",
    "port": 554,
    "path": "/live/stream",
    "authentication": {
      "type": "basic",
      "username": "user",
      "password": "password123"
    }
  }' \
  --output snapshot.jpg

Basic 認証を使用する例 (パスワードを認証情報ストアに登録する例)

ユーザー名 (username) と認証情報ストアに登録した「事前共有鍵」種別の認証情報の ID (passwordCredentialsId) を指定します。

認証情報ストアの設定

認証情報ストアに「事前共有鍵」を指定する際、値には RTSP の Basic 認証で使用するパスワードを設定してください。

curl -X POST "https://api.soracom.io/v1/sims/{sim_id}/downlink/rtsp" \
  -H "X-Soracom-API-Key: $X_SORACOM_API_KEY" \
  -H "X-Soracom-Token: $X_SORACOM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "snapshot",
    "port": 554,
    "path": "/live/stream",
    "authentication": {
      "type": "basic",
      "username": "user",
      "passwordCredentialsId": "credential-id"
    }
  }' \
  --output snapshot.jpg

静止画を Harvest Files に保存する例

Harvest Files に保存する場合は、options.destinations.harvestFiles.filePath に Harvest Files のパスを指定します。

curl -X POST "https://api.soracom.io/v1/sims/{sim_id}/downlink/rtsp" \
  -H "X-Soracom-API-Key: $X_SORACOM_API_KEY" \
  -H "X-Soracom-Token: $X_SORACOM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "snapshot",
    "port": 554,
    "path": "/live/stream",
    "authentication": {
      "type": "basic",
      "username": "user",
      "passwordCredentialsId": "credential-id"
    },
    "options": {
      "destinations": {
        "harvestFiles": {
          "filePath": "/camera/snapshots/{sim_id}_{time}.jpg"
        }
      }
    }
  }'

ファイルパスのプレースホルダーについて

filePath では {sim_id} と {time} のプレースホルダーを使用できます。実行時に SIM ID とタイムスタンプ (UNIX 時間・ミリ秒) に置き換えられます。ファイル名の末尾は .jpg または .jpeg を推奨します。