本記事はソラコムが提供する「SORACOM公式ブログ」に掲載された「自動化に役立つソラカメ API を CLI から呼ぶ方法 – 7 つの API を完全網羅」を再編集したものです。
目次
事前確認クラウド常時録画ライセンスの割り当て
権限管理
SORACOM CLI
カメラ情報取得
ソラカメ対応カメラの一覧を取得する
ソラカメ対応カメラの情報を取得する
エクスポート使用状況
ソラカメ対応カメラの静止画のエクスポート可能枚数や録画映像のエクスポート可能時間を取得する
ストリーミング再生
ストリーミング映像 (リアルタイム映像 / 録画映像) をダウンロードするための情報を取得する
録画映像ダウンロード
クラウド常時録画で保存された録画映像をエクスポートする処理を開始する
ソラカメ対応カメラで撮影した録画映像をエクスポートする処理の現在の状況をリストで取得する（複数台を対象）
ソラカメ対応カメラで撮影した録画映像をエクスポートする処理の現在の状況をリストで取得する（1 台を対象）
クラウド常時録画で保存された録画映像をエクスポートする処理の現在の状況を取得する
静止画ダウンロード
クラウド常時録画で保存された録画映像から静止画をエクスポートする処理を開始する
ソラカメ対応カメラで撮影した録画映像から静止画をエクスポートする処理の現在の状況をリストで取得する（複数台を対象）
ソラカメ対応カメラで撮影した録画映像から静止画をエクスポートする処理の現在の状況をリストで取得する（1 台を対象）
クラウド常時録画で保存された録画映像から静止画をエクスポートする処理の現在の状況を取得する
イベント一覧
ソラカメ対応カメラで検出されたイベントの一覧を取得する
ソラカメ対応カメラのイベント一覧を取得する
ライセンス 操作
Soracom Cloud Camera Services のライセンスパックの一覧を取得する
Soracom Cloud Camera Services のライセンス数を更新する
まとめ
参考
こんにちは、ソリューションアーキテクトの内田（ニックネーム: jet）です。
カメラ映像をクラウドに常時録画できるクラウドカメラサービス「Soracom Cloud Camera Services」（以下、ソラカメ）は 2022年5月のリリース 以降、多くのお客様のフィードバックを基にアップデートを重ねてきました。
中でも、2022年10月から一般利用が可能となったソラカメ API は、クラウド上に保存された録画データの動画や静止画の切り出しが行えたり、カメラ側で検出したイベントの取得ができたり と、映像を活用した IoT システム作りにおいて、繰り返し行う操作の自動化に役立つとご評価をいただいています。
今回は 2023年01月時点 までにリリースされた 7 つの ソラカメ API（以下、API）を SORACOM CLI（以下、CLI）で実際に使ってみようと思います。
API 種別ごとに CLI コマンドのサンプルと実行結果のサンプルを記載してありますので、ご自身の環境で実際に試していただく際の参考にしていただければと思います。
事前確認
CLI でコマンドを実行するために事前に必要な設定や準備を確認していきます。すでに設定済みの場合は読み飛ばしてください。
クラウド常時録画ライセンスの割り当て
これから実行するコマンドの中には、クラウドへ常時録画したデータを操作するものがあるため、対象のカメラにクラウド常時録画ライセンスの割り当てを行い、クラウドへの常時録画をスタートさせてください。
権限管理
以下のソラカメの Getting Started に沿って準備を行ってください。
Getting Started の設定では CLI コマンド実行には権限が不足しています。
今回はソラカメ関連の CLI コマンドをすべて実行して確認するため、以下のように SoraCam:* でソラカメ関連の操作をすべて許可します。
{ "statements": [ { "effect": "allow", "api": [ "OAuth2:authorize", "SoraCam:*" ] } ] }
今回のような SoraCam:* による許可は、今後ソラカメ関連の CLI コマンドが追加されても、そのままの権限で利用できる一方で、意図しない操作を自動的に許可してしまう状態 でもあるため、実利用の際には十分確認と検討を行なってください。
SAM ユーザーについては以下のブログも参考にしてください。
CLI コマンド実行時にエラーが表示される場合
SAM ユーザーの権限が十分かどうかの確認と、対象のカメラにクラウド常時録画ラインセスが正しく割り当てられているかどうかを確認してください。
クラウド常時録画ライセンスが正しく割り当てられていて録画が行われている必要があります。
SORACOM CLI
すべての操作を CLI で行うため、CLI の設定が完了している必要があります。
設定の方法や詳細はユーザードキュメントを参照してください。
CLI コマンドのサンプルを記載していますが、動作確認は以下の環境で行なっています。
また、実行しているコマンドは 2023年01月時点のものとなり、実行制限や実行結果は実行時点のものとなるため、利用する場合には実際に動作させて内容を確認してください。
| 名称 | バージョン | 備考 |
|---|---|---|
| SORACOM CLI | SORACOM API client v0.14.0 | https://github.com/soracom/soracom-cli |
| jq | jq-1.6 | https://stedolan.github.io/jq/ |
| FFmpeg | ffmpeg version 5.1.2 Copyright (c) 2000-2022 the FFmpeg developers built with Apple clang version 14.0.0 (clang-1400.0.29.202) |
https://ffmpeg.org/ |
カメラ情報取得
ここからは実際に CLI のコマンドを実行していきたいと思います。
まずはカメラの一覧を取得したり、カメラの情報を取得する CLI コマンドを実行してみます。
これらのコマンドを使うことで、カメラの一覧画面やカメラごとの詳細画面に情報が表示できます。
ソラカメ対応カメラの一覧を取得する
ソラカメ対応カメラの一覧を取得します。（SoraCam:listSoraCamDevices）
CLI コマンド サンプル
soracom sora-cam devices list
CLI コマンド 実行結果 サンプル（一部抜粋 / 編集済み）
[ { "configuration": { "audioAlarmEnabled": false, "motionDetectionEnabled": true, "smokeAlarmEnabled": false }, "connected": false, "deviceCategory": "Camera", "deviceId": "7CXXXXXXXX38", "firmwareVersion": "4.58.0.100", "lastConnectedTime": 1668752411404, "name": "ATOM Cam 2", "productDisplayName": "ATOM Cam 2" }, { "configuration": { "audioAlarmEnabled": false, "motionDetectionEnabled": false, "smokeAlarmEnabled": false }, "connected": false, "deviceCategory": "Camera", "deviceId": "7CXXXXXXXX2B", "firmwareVersion": "4.37.1.106", "lastConnectedTime": 1668751137629, "name": "ATOM Cam Swing", "productDisplayName": "ATOM Cam Swing" }, { "configuration": { "audioAlarmEnabled": false, "motionDetectionEnabled": false, "smokeAlarmEnabled": false }, "connected": true, "deviceCategory": "Camera", "deviceId": "7CXXXXXXXX8E", "firmwareVersion": "4.58.0.100", "lastConnectedTime": 1668751384918, "name": "ATOM Cam 2 office", "productDisplayName": "ATOM Cam 2" } # ... The following output was omitted because there were so many. ]
ソラカメ対応カメラの情報を取得する
デバイス ID で指定したソラカメ対応カメラの情報を取得します。（SoraCam:getSoraCamDevice）
CLI コマンド サンプル
カメラを識別するのはデバイス ID になるので、カメラ一覧の中から1つ選択した deviceId の値を利用してカメラの情報を表示する例。選択しているカメラの名称はご自身の環境に合わせて読み替えをお願いします。
DEVICE_ID=$(soracom sora-cam devices list | jq -r '.[] | select(.name == "ATOM Cam 2") | .deviceId') # echo "${DEVICE_ID}" soracom sora-cam devices get --device-id "${DEVICE_ID}"
CLI コマンド 実行結果 サンプル（編集済み）
{ "configuration": { "audioAlarmEnabled": false, "motionDetectionEnabled": true, "smokeAlarmEnabled": false }, "connected": true, "deviceCategory": "Camera", "deviceId": "7CXXXXXXXX38", "firmwareVersion": "4.58.0.100", "lastConnectedTime": 1673596942916, "name": "ATOM Cam 2", "productDisplayName": "ATOM Cam 2" }
これらの CLI コマンドで、カメラの一覧と個別のカメラ情報を取得でき、SORACOM ユーザーコンソール
と同じ値が取れていることが確認できているかと思います。
エクスポート使用状況
静止画の残りエクスポート可能枚数や、録画映像の残りエクスポート可能時間を取得する CLI コマンドを実行してみます。
このコマンドを使うことでカメラのエクスポート状態が確認できます。エクスポート可能な時間は固定値ではなくこのコマンドの戻り値を基準とすることで、基準が変更になった場合でも修正の必要がなくなります。
静止画/ 録画映像のどちらをエクスポートしても、動画の視聴可能時間は消費されます。静止画の場合には 1 秒、録画映像の場合には指定したエクスポート時間分が消費されます。
ソラカメ対応カメラの静止画のエクスポート可能枚数や録画映像のエクスポート可能時間を取得する
静止画の残りのエクスポート可能枚数や、録画映像の残りのエクスポート可能時間などを取得します。（SoraCam:getSoraCamDeviceExportUsage）
CLI コマンド サンプル
DEVICE_ID はカメラ一覧から取得済みのものを継続して利用します。
soracom sora-cam devices get-export-usage --device-id "${DEVICE_ID}"
CLI コマンド 実行結果 サンプル（編集済み）
{ "deviceId": "7CXXXXXXXX51", "image": { "remainingFrames": 256954, "usedFrames": 2246 }, "meteredYearMonth": "202301", "video": { "remainingSeconds": 256954, "usedSeconds": 2246 } }
CLI コマンド サンプル
SORACOM ユーザーコンソールの表示と同じような 時 / 分 / 秒 の形式にフォーマットして表示する例。DEVICE_ID はカメラ一覧から取得済みのものを継続して利用します。
VIDEO_SEC=$(soracom sora-cam devices get-export-usage --device-id "${DEVICE_ID}" | jq -r '.video | .remainingSeconds') # echo "${VIDEO_SEC}" ((_REMAIN_H=VIDEO_SEC/3600, _REMAIN_M=(VIDEO_SEC%3600)/60, _REMAIN_S=VIDEO_SEC%60)) _REMAIN=$(printf "%dh %02dm %02ds" "$_REMAIN_H" "$_REMAIN_M" "$_REMAIN_S") echo "$_REMAIN"
この CLI コマンドで、エクスポート可能時間を取得でき、SORACOM ユーザーコンソール と同じ値が取れていることが確認できているかと思います。
ストリーミング再生
ストリーミング映像 (リアルタイム映像 / 録画映像) をダウンロードするための情報を取得する CLI コマンドを実行してみます。MPEG-DASH (Dynamic Adaptive Streaming over HTTP) と呼ばれるストリーミング方式に対応した URL の配列を取得できます。
このコマンドを使うことで、取得した URL を用いて Web ブラウザでのストリーミング映像の再生が行えるため、遠隔地の状況確認や、いわゆるお天気カメラのような仕組みを構築できます。
取得した URL には有効期限が設定されています。有効期限はコマンドの戻り値を利用することで、期限が変更になった場合でも修正の必要がなくなります。
- リアルタイム映像をストリーミング再生する場合は、以下の点に注意してください。
- コマンドを実行した時刻を基準に、リアルタイム映像をストリーミング再生できる有効期限付きの URL を取得できます。継続してストリーミング再生を行う場合は、繰り返しコマンドを実行して、新しい有効期限付き URL を取得してください。
- URL の取得リクエストが成功した時点で、視聴状況にかかわらず動画の視聴可能時間 が 300 秒 (5 分) 消費されます。
- リクエストは毎回処理されます。同じパラメーターのリクエストもその都度 1 回として処理されます。
- 録画映像をストリーミング再生する場合は、以下の点に注意してください。
- 最大 300 秒 (5 分) の録画映像をストリーミング再生できる 有効期限付きの URL を取得できます。
- URL の取得リクエストが成功した時点で、視聴状況にかかわらず動画の視聴可能時間 が録画映像を出力した分消費されます。
- リクエストは毎回処理されます。同じパラメーターのリクエストもその都度 1 回として処理されます。
リアルタイム映像は、クラウドへ常時録画で保存された録画映像から最新の映像を取得する機能です。リアルタイム映像を取得するには、クラウド常時録画ライセンスが必要となります。ATOM アプリで再生できる「ライブ映像 (P2P)」は、リアルタイム映像とは異なる機能です。リアルタイム映像は、録画映像を再生しているためネットワーク状況に依存して、タイムラグが出る場合があります。
ストリーミング映像 (リアルタイム映像 / 録画映像) をダウンロードするための情報を取得する
ストリーミング映像 (リアルタイム映像 / 録画映像) をダウンロードするための情報を取得します。具体的には、MPEG-DASH (Dynamic Adaptive Streaming over HTTP) と呼ばれるストリーミング方式に対応した URL の配列を取得できます。URL には有効期限が設定されています。（SoraCam:getSoraCamDeviceStreamingVideo）
CLI コマンド サンプル
DEVICE_ID はカメラ一覧から取得済みのものを継続して利用します。
soracom sora-cam devices get-streaming-video --device-id "${DEVICE_ID}"
CLI コマンド 実行結果 サンプル（編集済み）
{ "expiryTime": 1674715566105, "playList": [ { "url": "https://XXXXX.amazonaws.com/dash/v1/getDASHManifest.mpd?XXXXXXXXX" } ] }
CLI コマンド サンプル
コマンド実行日時を基準に 1 分前の録画映像を取得する例。録画映像を取得する場合は期間の指定が必須となります。DEVICE_ID はカメラ一覧から取得済みのものを継続して利用します。
VIDEO_TO=$(date +%s000) ((VIDEO_FROM=VIDEO_TO - 60000)) # echo "${VIDEO_TO}" # echo "${VIDEO_FROM}" soracom sora-cam devices get-streaming-video --device-id "${DEVICE_ID}" --from "${VIDEO_FROM}" --to "${VIDEO_TO}"
CLI コマンド 実行結果 サンプル（編集済み）
{ "expiryTime": 1668923808865, "playList": [ { "from": 1668846773000, "to": 1668846953000, "url": "https://XXXXX.amazonaws.com/dash/v1/getDASHManifest.mpd?XXXXXXXXX" } ] }
CLI コマンド サンプル
実行結果から取得した URL を、そのままコマンドラインの FFmpeg ツールで再生する例。DEVICE_ID はカメラ一覧から取得済みのものを継続して利用します。
VIDEO_TO=$(date +%s000) ((VIDEO_FROM=VIDEO_TO - 60000)) # echo "${VIDEO_TO}" # echo "${VIDEO_FROM}" VIDEO_URL=$(soracom sora-cam devices get-streaming-video --device-id "${DEVICE_ID}" --from "${VIDEO_FROM}" --to "${VIDEO_TO}" | jq -r '.playList | .[].url') ffplay -i "${VIDEO_URL}"
この CLI コマンドで、ストリーミング映像を取得でき、SORACOM ユーザーコンソール と同じように再生ができていると思います。
CLI で再生するために FFmpeg を利用していますが、例えば以下のような MPEG-DASH に対応したプレーヤーであれば URL を貼り付けるだけで再生できますので、動作を試したい場合は手軽に確認できる方法を試していただければと思います。
録画映像ダウンロード
クラウドへ常時録画で保存された録画映像を、ダウンロードできる方式でエクスポートする処理を開始する CLI コマンドを実行してみます。エクスポート処理は非同期で処理されます。
このコマンドを使うことで、エクスポート処理の状況や、エクスポートしたファイルをダウンロードできる URL を取得できます。取得した URL には有効期限が設定されています。有効期限はコマンドからの戻り値を利用することで、期限が変更になった場合でも修正の必要がなくなります。
取得した URL から録画した映像をファイルとして保存できます。保存したファイルを使って他のシステムや仕組みで利用できます。例えば、映像を AI / ML サービスのインプットとして利用できます。
- 1 度のリクエストで指定できるエクスポート期間は最大 300 秒 (5 分) 間です。
- ダウンロードでされるのは、mp4 ファイルを zip 形式で圧縮したファイルです。
- zip ファイル内の mp4 ファイルは複数になる場合があります。
- URL の取得リクエストが成功した時点でダウンロード状況にかかわらず動画の視聴可能時間 が消費されます。
- リクエストは毎回処理されます。同じパラメーターのリクエストもその都度 1 回として処理されます。
クラウド常時録画で保存された録画映像をエクスポートする処理を開始する
クラウド常時録画で保存された録画映像を、ダウンロードできる方式 (mp4 ファイルを zip 形式で圧縮したファイル) でエクスポートする処理を開始します。エクスポート処理は非同期で処理されます。エクスポート処理の進捗や、エクスポートしたファイルの URL は、状況をリスト表示で確認するコマンド で取得できます。URL には有効期限が設定されています。（SoraCam:exportSoraCamDeviceRecordedVideo）
CLI コマンド サンプル
コマンド実行日時を基準に 1 分前の録画映像をダウンロードする例。DEVICE_ID はカメラ一覧から取得済みのものを継続して利用します。
VIDEO_TO=$(date +%s000) ((VIDEO_FROM=VIDEO_TO - 60000)) # echo "${VIDEO_TO}" # echo "${VIDEO_FROM}" soracom sora-cam devices videos export --device-id "${DEVICE_ID}" --from "${VIDEO_FROM}" --to "${VIDEO_TO}"
CLI コマンド 実行結果 サンプル（編集済み）
{ "deviceId": "7CXXXXXXXX51", "exportId": "3abb2ee0-9dd0-4253-96ae-1632cd541aa6", "operatorId": "OPXXXXXXXX96", "requestedTime": 1669028718371, "status": "initializing" }
ソラカメ対応カメラで撮影した録画映像をエクスポートする処理の現在の状況をリストで取得する（複数台を対象）
開始した「録画映像をエクスポートする処理」の現在の状況をリストで取得します。このコマンドでは、対象をオペレーターが所有するすべてのデバイスにしたり、1 台のソラカメ対応カメラに限定したりできます。（SoraCam:listSoraCamDeviceVideoExports）
CLI コマンド サンプル
soracom sora-cam devices videos list-exports
CLI コマンド 実行結果 サンプル（編集済み）
[ { "deviceId": "7CXXXXXXXX51", "expiryTime": 1669109577000, "exportId": "4bbe30c8-89a1-4d5e-acb4-3f9edf5d48d3", "operatorId": "OPXXXXXXXX96", "requestedTime": 1669108947470, "status": "completed", "url": "https://XXX.XXX.amazonaws.com/2022-11-24-10-37-22_XXXX.zip?XXXXX=aaabcdef&Expires=1669286843" }, { "deviceId": "7CXXXXXXXX0E", "expiryTime": 1669029448000, "exportId": "34884e78-5c4f-4b85-9e3e-64a349d91248", "operatorId": "OPXXXXXXXX96", "requestedTime": 1669028814611, "status": "expired", "url": "https://XXX.XXX.amazonaws.com/2022-11-24-10-37-22_XXXX.zip?XXXXX=aaabcdef&Expires=1669286843" }, { "deviceId": "7CXXXXXXXX51", "expiryTime": 1669029352000, "exportId": "3abb2ee0-9dd0-4253-96ae-1632cd541aa6", "operatorId": "OPXXXXXXXX96", "requestedTime": 1669028718371, "status": "expired", "url": "https://XXX.XXX.amazonaws.com/2022-11-24-10-37-22_XXXX.zip?XXXXX=aaabcdef&Expires=1669286843" } ]
ソラカメ対応カメラで撮影した録画映像をエクスポートする処理の現在の状況をリストで取得する（1 台を対象）
開始した「録画映像をエクスポートする処理」の現在の状況をリストで取得します。このコマンドでは、対象を 1 台のソラカメ対応カメラに限定します。
なお、対象を 1 台のソラカメ対応カメラに限定しないで、オペレーターが所有するすべてのソラカメ対応カメラにする場合は、状況をリスト表示で確認するコマンド を使用してください。（SoraCam:listSoraCamDeviceVideoExportsForDevice）
CLI コマンド サンプル
DEVICE_ID はカメラ一覧から取得済みのものを継続して利用します。
soracom sora-cam devices videos list-exports-for-device --device-id "${DEVICE_ID}"
CLI コマンド 実行結果 サンプル（編集済み）
[ { "deviceId": "7CXXXXXXXX51", "expiryTime": 1669109577000, "exportId": "4bbe30c8-89a1-4d5e-acb4-3f9edf5d48d3", "operatorId": "OPXXXXXXXX96", "requestedTime": 1669108947470, "status": "completed", "url": "https://XXX.XXX.amazonaws.com/2022-11-24-10-37-22_XXXX.zip?XXXXX=aaabcdef&Expires=1669286843" }, { "deviceId": "7CXXXXXXXX51", "expiryTime": 1669029448000, "exportId": "34884e78-5c4f-4b85-9e3e-64a349d91248", "operatorId": "OPXXXXXXXX96", "requestedTime": 1669028814611, "status": "expired", "url": "https://XXX.XXX.amazonaws.com/2022-11-24-10-37-22_XXXX.zip?XXXXX=aaabcdef&Expires=1669286843" }, { "deviceId": "7CXXXXXXXX51", "expiryTime": 1669029352000, "exportId": "9ee31354-f480-4347-843a-1b968f5b8950", "operatorId": "OPXXXXXXXX96", "requestedTime": 1669028718371, "status": "expired", "url": "https://XXX.XXX.amazonaws.com/2022-11-24-10-37-22_XXXX.zip?XXXXX=aaabcdef&Expires=1669286843" } ]
クラウド常時録画で保存された録画映像をエクスポートする処理の現在の状況を取得する
開始した「録画映像をエクスポートする処理」の現在の状況をリストで取得します。このコマンドでは、対象を 1 つのエクスポート処理に限定します。（SoraCam:getSoraCamDeviceExportedVideo）
CLI コマンド サンプル
DEVICE_ID はカメラ一覧から取得済みのものを継続して利用します。
VIDEO_EXP_ID=$(soracom sora-cam devices videos list-exports --device-id "${DEVICE_ID}" | jq -r 'sort_by(.requestedTime) | reverse | .[0].exportId') # echo "${VIDEO_EXP_ID}" soracom sora-cam devices videos get-exported --device-id "${DEVICE_ID}" --export-id "${VIDEO_EXP_ID}"
CLI コマンド 実行結果 サンプル（編集済み）
{ "deviceId": "7CXXXXXXXX51", "expiryTime": 1674641966000, "exportId": "c316f3b0-b046-43b5-892f-f2c292b5f1a3", "operatorId": "OPXXXXXXXX96", "requestedTime": 1674641326850, "status": "completed", "url": "https://XXX.XXX.amazonaws.com/2022-11-24-10-37-22_XXXX.zip?XXXXX=aaabcdef&Expires=1669286843" }
これらの CLI コマンドで、録画映像のエクスポート処理と処理状況の情報が取得でき、SORACOM ユーザーコンソール と同じようにファイルのダウンロードができていると思います。
映像を繰り返し視聴して確認する場合には、1 度ファイルとしてダウンロードを行うことで動画の視聴可能時間を気にせず確認できます。
静止画ダウンロード
クラウドへの常時録画で保存された録画映像から、静止画を切り出してエクスポートする処理を開始する CLI コマンドを実行してみます。エクスポート処理は非同期で処理されます。
このコマンドを使うことで、エクスポート処理の状況や、エクスポートしたファイルがダウンロードできる URL を取得できます。取得した URL には有効期限が設定されています。有効期限はコマンドからの戻り値を利用することで、期限が変更になった場合でも修正の必要がなくなります。
取得した URL から静止画をファイルとして保存できます。保存したファイルを使って他のシステムや仕組みで利用できます。例えば一定間隔で取得した静止画をつないで、動画に見せる「タイムラプス」写真を作れます。
- ダウンロードできるのは、JPEG ファイルです。
- 静止画のサイズは録画時の解像度に依存します。HD 画質で録画している場合には HD（1280×720ピクセル）となります。
- 録画時の広角レンズによる画像のゆがみを補正できます。ゆがみ補正を行った場合には、画像がトリミングされるため録画時と見える範囲が異なる場合があります。
- URL の取得リクエストが成功した時点でダウンロード状況にかかわらず動画の視聴可能時間 が消費されます。
- リクエストは毎回処理されます。同じパラメーターのリクエストもその都度 1 回として処理されます。
クラウド常時録画で保存された録画映像から静止画をエクスポートする処理を開始する
クラウド常時録画で保存された録画映像から静止画を切り出してエクスポートする処理を開始します。エクスポート処理は非同期で処理されます。エクスポート処理の進捗や、エクスポートしたファイルの URL は、状況をリスト表示で確認するコマンド で取得できます。URL には有効期限が設定されています。（SoraCam:exportSoraCamDeviceRecordedImage）
CLI コマンド サンプル
コマンド実行日時を基準に 1 分前の広角補正を行った静止画をダウンロードする例。 DEVICE_ID はカメラ一覧から取得済みのものを継続して利用します。
IMAGE_NOW=$(date +%s000) ((IMAGE_TIME=IMAGE_NOW - 60000)) # echo "${IMAGE_TIME}" soracom sora-cam devices images export --device-id "${DEVICE_ID}" --time "${IMAGE_TIME}" --image-filters wide_angle_correction
CLI コマンド 実行結果 サンプル（編集済み）
{ "deviceId": "7CXXXXXXXX51", "exportId": "223cd164-3bdd-4893-9792-7ecea057aef9", "operatorId": "OPXXXXXXXX96", "requestedTime": 1669283710049, "status": "initializing" }
ソラカメ対応カメラで撮影した録画映像から静止画をエクスポートする処理の現在の状況をリストで取得する（複数台を対象）
開始した「録画映像から静止画をエクスポートする処理」の現在の状況をリストで取得します。このコマンドでは、対象をオペレーターが所有するすべてのデバイスにしたり、1 台のソラカメ対応カメラに限定したりできます。（SoraCam:listSoraCamDeviceImageExports）
CLI コマンド サンプル
soracom sora-cam devices images list-exports
CLI コマンド 実行結果 サンプル（編集済み）
[ { "deviceId": "7CXXXXXXXX0E", "expiryTime": 1669286843000, "exportId": "aa07d7c7-2983-4969-ac4b-5984d5244690", "operatorId": "OPXXXXXXXX96", "requestedTime": 1669286242878, "status": "completed", "url": "https://XXX.XXX.amazonaws.com/2022-11-24-10-37-22_XXXX.jpg?XXXXX=aaabcdef&Expires=1669286843" }, { "deviceId": "7CXXXXXXXX51", "expiryTime": 1669284312000, "exportId": "223cd164-3bdd-4893-9792-7ecea057aef9", "operatorId": "OPXXXXXXXX96", "requestedTime": 1669283710049, "status": "expired", "url": "https://XXX.XXX.amazonaws.com/2022-11-24-09-55-10_XXXX.jpg?XXXXX=xcvbnsdr&Expires=1669284312" } ]
ソラカメ対応カメラで撮影した録画映像から静止画をエクスポートする処理の現在の状況をリストで取得する（1 台を対象）
開始した「録画映像から静止画をエクスポートする処理」の現在の状況をリストで取得します。このコマンドでは、対象を 1 台のソラカメ対応カメラに限定します。
なお、対象を 1 台のソラカメ対応カメラに限定しないで、オペレーターが所有するすべてのソラカメ対応カメラにする場合は、状況をリスト表示で確認するコマンド を使用してください。（SoraCam:listSoraCamDeviceImageExportsForDevice）
CLI コマンド サンプル
DEVICE_ID はカメラ一覧から取得済みのものを継続して利用します。
soracom sora-cam devices images list-exports-for-device --device-id "${DEVICE_ID}"
CLI コマンド 実行結果 サンプル（編集済み）
[ { "deviceId": "7CXXXXXXXX51", "expiryTime": 1669286843000, "exportId": "9ee31354-f480-4347-843a-1b968f5b8950", "operatorId": "OPXXXXXXXX96", "requestedTime": 1669286242878, "status": "completed", "url": "https://XXX.XXX.amazonaws.com/2022-11-24-10-37-22_XXXX.jpg?XXXXX=aaabcdef&Expires=1669286843" }, { "deviceId": "7CXXXXXXXX51", "expiryTime": 1669284312000, "exportId": "223cd164-3bdd-4893-9792-7ecea057aef9", "operatorId": "OPXXXXXXXX96", "requestedTime": 1669283710049, "status": "expired", "url": "https://XXX.XXX.amazonaws.com/2022-11-24-09-55-10_XXXX.jpg?XXXXX=xcvbnsdr&Expires=1669284312" } ]
クラウド常時録画で保存された録画映像から静止画をエクスポートする処理の現在の状況を取得する
開始した「録画映像から静止画をエクスポートする処理」の現在の状況をリストで取得します。このコマンドでは、対象を 1 つのエクスポート処理に限定します。（SoraCam:getSoraCamDeviceExportedImage）
CLI コマンド サンプル
DEVICE_ID はカメラ一覧から取得済みのものを継続して利用します。
IMAGE_EXP_ID=$(soracom sora-cam devices images list-exports --device-id "${DEVICE_ID}" | jq -r '.[-1:] | .[].exportId') # echo "${IMAGE_EXP_ID}" soracom sora-cam devices images get-exported --device-id "${DEVICE_ID}" --export-id "${IMAGE_EXP_ID}"
CLI コマンド 実行結果 サンプル（編集済み）
{ "deviceId": "7CXXXXXXXX51", "expiryTime": 1669284312000, "exportId": "223cd164-3bdd-4893-9792-7ecea057aef9", "operatorId": "OPXXXXXXXX96", "requestedTime": 1669283710049, "status": "completed", "url": "https://XXX.XXX.amazonaws.com/2022-11-24-09-55-10_XXXX.jpg?XXXXX=xcvbnsdr&Expires=1669284312" }
これらの CLI コマンドで、静止画のエクスポート処理と処理状況の情報が取得でき、SORACOM ユーザーコンソール と同じようにファイルのダウンロードができていると思います。
動画ではなく静止画をダウンロードすることで、動画の視聴可能時間を節約できます。
イベント一覧
モーション検知録画が有効化 されているソラカメ対応カメラで検出されたイベントの一覧を取得する CLI コマンドを実行してみます。
このコマンドを使うことで、音や動体検出などのイベントを検知した瞬間の静止画や、映像を指定して取得できます。動画の視聴可能時間を節約しながら、必要な部分だけを効率的に利用できるようになります。
- イベント一覧で取得できるイベント開始時の静止画の URL には有効期限があります。有効期限が切れた場合、再度 コマンドを実行してください。
- クラウド常時録画ライセンスが割り当てられてない場合や、イベントの録画状況によってはイベントの終了時刻が取得できない場合があります。
- イベントの開始時刻とイベントの終了時刻が 300 秒 (5 分) 以上になる場合があります。他の CLI コマンドの入力値として利用する場合には注意してください。
ソラカメ対応カメラで検出されたイベントの一覧を取得する
ソラカメ対応カメラで検出されたイベントの一覧を取得します。（SoraCam:listSoraCamDeviceEvents）
CLI コマンド サンプル
soracom sora-cam devices events list
CLI コマンド 実行結果 サンプル（一部抜粋 / 編集済み）
[ { "deviceId": "7CXXXXXXXX0E", "deviceType": "atomCamV2", "eventId": "ef2222395b8b40b1915da5af100b983e", "eventInfo": { "atomEventV1": { "picture": "https://XXfileXXX.amazonaws.com/7CXXXXXXXX0E/2022-12-05/7CXXXXXXXX0E131670281135_1670281135000_13_1_0/311989cf93bf4afa9c282b6a2a682525.jpg", "startTime": 1670281135000, "status": "recording", "type": "cloudStorage" }, "infoType": "atomEventV1" }, "time": 1670281135000 }, { "deviceId": "7CXXXXXXXX89", "deviceType": "atomCamV2", "eventId": "9522226d9b8b41889f1827ad26b3a028", "eventInfo": { "atomEventV1": { "endTime": 1670281129000, "picture": "https://XXfileXXX.amazonaws.com/7CXXXXXXXX89/2022-12-05/7CXXXXXXXX89131670281107_1670281107000_13_1_0/800ff8febfac4c63b86bc18b7df0f042.jpg", "startTime": 1670281107000, "status": "completed", "type": "cloudStorage" }, "infoType": "atomEventV1" }, "time": 1670281107000 }, { "deviceId": "7CXXXXXXXX0E", "deviceType": "atomCamV2", "eventId": "db22221df07f4244b53486995c655fb6", "eventInfo": { "atomEventV1": { "endTime": 1670281125000, "picture": "https://XXfileXXX.amazonaws.com/7CXXXXXXXX0E/2022-12-05/7CXXXXXXXX0E131670281090_1670281090000_13_1_0/8f399fbb27384e07b819bd4997ac0a3f.jpg", "startTime": 1670281090000, "status": "completed", "type": "cloudStorage" }, "infoType": "atomEventV1" }, "time": 1670281090000 } # ... The following output was omitted because there were so many. ]
ソラカメ対応カメラのイベント一覧を取得する
デバイス ID で指定したソラカメ対応カメラで検出されたイベントの一覧を取得します。（SoraCam:listSoraCamDeviceEventsForDevice）
CLI コマンド サンプル
DEVICE_ID はカメラ一覧から取得済みのものを継続して利用します。
soracom sora-cam devices events list-for-device --device-id "${DEVICE_ID}"
CLI コマンド 実行結果 サンプル（一部抜粋 / 編集済み）
[ { "deviceId": "7CXXXXXXXX0E", "deviceType": "atomCamV2", "eventId": "ef2222395b8b40b1915da5af100b983e", "eventInfo": { "atomEventV1": { "picture": "https://XXfileXXX.amazonaws.com/7CXXXXXXXX0E/2022-12-05/7CXXXXXXXX0E131670281135_1670281135000_13_1_0/311989cf93bf4afa9c282b6a2a682525.jpg", "startTime": 1670281135000, "status": "recording", "type": "cloudStorage" }, "infoType": "atomEventV1" }, "time": 1670281135000 }, { "deviceId": "7CXXXXXXXX0E", "deviceType": "atomCamV2", "eventId": "db22221df07f4244b53486995c655fb6", "eventInfo": { "atomEventV1": { "endTime": 1670281125000, "picture": "https://XXfileXXX.amazonaws.com/7CXXXXXXXX0E/2022-12-05/7CXXXXXXXX0E131670281090_1670281090000_13_1_0/8f399fbb27384e07b819bd4997ac0a3f.jpg", "startTime": 1670281090000, "status": "completed", "type": "cloudStorage" }, "infoType": "atomEventV1" }, "time": 1670281090000 } # ... The following output was omitted because there were so many. ]
これらの CLI コマンドで、カメラで検知されたイベントの一覧が取得でき、SORACOM ユーザーコンソール と同じ情報が取得できていると思います。
定期的にこのコマンドを実行して、イベントの一覧を取得することで、イベントを起点とした通知のシステムや仕組みを作れるかと思います。
ライセンス 操作
利用可能なライセンスパックの一覧と利用中のライセンス数を表示できます。 指定されたライセンスパックのライセンスを変更できます。ATOM Cam 2 / ATOM Cam Swing をお持ちの場合は、このコマンドでライセンスを購入して割り当てを行うことで、クラウドへの常時録画を利用できます。
このコマンドを使うことで、利用中のライセンス数の表示や、ライセンスの増減を行えます。
- ライセンス数に応じて月額費用が発生しますので、利用する場合には必ず確認してください。
- 2023年01月現在、これらの ライセンス操作コマンド は日本カバレッジでのみ利用可能です。
Soracom Cloud Camera Services のライセンスパックの一覧を取得する
利用可能なライセンスパックの一覧を取得します。 現在、このコマンドは日本カバレッジでのみ利用可能です。（SoraCam:listSoraCamLicensePacks）
CLI コマンド サンプル
soracom sora-cam license-packs list
CLI コマンド 実行結果 サンプル
[ { "id": "CR7-SC", "name": "クラウド常時録画ライセンス (7 日間)", "quantity": 12, "salesChannel": "株式会社ソラコム" }, { "id": "CR14-SC", "name": "クラウド常時録画ライセンス (14 日間)", "quantity": 5, "salesChannel": "株式会社ソラコム" }, { "id": "CR30-SC", "name": "クラウド常時録画ライセンス (30 日間)", "quantity": 0, "salesChannel": "株式会社ソラコム" } ]
Soracom Cloud Camera Services のライセンス数を更新する
license_pack_id で指定されたライセンスパックのライセンス数を更新します。 ライセンス数に応じて月額費用が発生します。 現在、このコマンドは日本カバレッジでのみ利用可能です。（SoraCam:updateSoraCamLicensePackQuantity）
CLI コマンド サンプル
ライセンス数に応じて月額費用が発生します。実行する際には必ず確認してから実行してください。
CURRENT=0 / DESIRED=1 の部分は、実行環境と必要なラインセス数に合わせて適宜変更してください。
LICENSE_ID=$(soracom sora-cam license-packs list | jq -r '.[-1:] | .[].id') # echo "${LICENSE_ID}" CURRENT=0 DESIRED=1 soracom sora-cam license-packs update-quantity --license-pack-id "${LICENSE_ID}" --current-quantity ${CURRENT} --desired-quantity ${DESIRED}
CLI コマンド 実行結果 サンプル
{ "id": "CR30-SC", "name": "クラウド常時録画ライセンス (30 日間)", "quantity": 1, "salesChannel": "株式会社ソラコム" }
これらの CLI コマンドで、ライセンスの種類や現在利用しているライセンス数が取得でき、SORACOM ユーザーコンソール と同じ情報が取得できていると思います。
ライセンスの追加や削除といった操作もコマンドで行えるので、定期的なライセンスの棚卸し作業や一時的なライセンスの追加作業なども自動化できます。
まとめ
2023年01月現在 までにリリースされた 7 つのソラカメ APIを、CLI を使って実際にすべて実行してみました。記事の量が多く長くなってしまいましたが、実際に使う際に少しでも参考になれば嬉しいです。
API / CLI はまだまだ機能追加が行われていく予定となりますので、実際に使ってみて必要な機能があればぜひ フィードバック をよろしくお願いします。
参考
最後に、単純にCLIコマンドを使ってみるだけでなく、もう少し実務に沿った内容を紹介します。
SORACOM User Group のイベントで実施されたソラカメのワークショップです。API / CLI を利用してタイムラプス動画を作成できます。以下のドキュメントを読み進めながら試せますのでぜひチャレンジしてみてください。
もうひとつ、イベント一覧 APIをリリースした際のブログに、実際にイベント一覧の CLI コマンドと、録画動画ダウンロート / 静止画ダウンロード の CLI コマンドを組み合わせたサンプルがありますので、そちらも参考にしてみてください。
― ソラコム内田（jet）@uchimanajet7
投稿 自動化に役立つソラカメ API を CLI から呼ぶ方法 – 7 つの API を完全網羅 は SORACOM公式ブログ に最初に表示されました。
この連載の記事
-
第489回
デジタル
業界別に学べる、IoT・デジタル化の課題と解決策の動画を公開 -
第488回
デジタル
M5StackからSORACOM、そしてAWSを体験！北陸のIoTイベント ― IoT Get Started Day レポート -
第487回
デジタル
ソラコムサンタより愛をこめて 2024 -
第486回
デジタル
SORACOMをもっと便利に！無料機能フル活用＆SIMの選び方 -
第485回
デジタル
省電力通信LTE-M対応の小型マイコンボードをSORACOM IoTストアで提供開始、ローコードIoTアプリケーションビルダー「SORACOM Flux」の料金プランを発表 takuyaのほぼ週刊ソラコム 11/30-12/13 -
第484回
デジタル
AWS re:Invent 2024に見る、IoTの成熟と生成AIとの融合 -
第483回
デジタル
二歳半の子供を持つエンジニアの一日の働き方 -
第482回
デジタル
VPN 対応の産業用 LTE ルーターの価格改定【30%オフ】 -
第481回
デジタル
時間帯に応じたメール通知の構築方法 : SORACOM LTE-M Button と SORACOM Flux の活用 -
第480回
デジタル
SORACOM Flux 料金プランを発表しました