第202回 SORACOM公式ブログ

ソラコム公式ブログ

自動化に役立つソラカメAPIをCLIから呼ぶ方法–7つのAPIを完全網羅

  • この記事をはてなブックマークに追加
  • 本文印刷

　本記事はソラコムが提供する「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）で実際に使ってみようと思います。

リファレンス: SORACOM API リファレンス | SORACOM API 利用ガイド | ソラコムユーザーサイト – SORACOM Users
ソラカメ API リファレンス

API 種別ごとに CLI コマンドのサンプルと実行結果のサンプルを記載してありますので、ご自身の環境で実際に試していただく際の参考にしていただければと思います。

事前確認

CLI でコマンドを実行するために事前に必要な設定や準備を確認していきます。すでに設定済みの場合は読み飛ばしてください。

クラウド常時録画ライセンスの割り当て

これから実行するコマンドの中には、クラウドへ常時録画したデータを操作するものがあるため、対象のカメラにクラウド常時録画ライセンスの割り当てを行い、クラウドへの常時録画をスタートさせてください。

ライセンス管理: ソラカメ対応カメラにライセンスを割り当てる | Soracom Cloud Camera Services | ソラコムユーザーサイト – SORACOM Users
ソラカメ ライセンスの割り当て

権限管理

以下のソラカメの Getting Started に沿って準備を行ってください。

Getting Started: STEP 2: ATOM アプリに SORACOM ログインする | Soracom Cloud Camera Services | ソラコムユーザーサイト – SORACOM Users
ソラカメ Getting Started

Getting Started の設定では CLI コマンド実行には権限が不足しています。
今回はソラカメ関連の CLI コマンドをすべて実行して確認するため、以下のように SoraCam:* でソラカメ関連の操作をすべて許可します。

{   "statements": [     {       "effect": "allow",       "api": [         "OAuth2:authorize",         "SoraCam:*"       ]     }   ] }

今回のような SoraCam:* による許可は、今後ソラカメ関連の CLI コマンドが追加されても、そのままの権限で利用できる一方で、意図しない操作を自動的に許可してしまう状態 でもあるため、実利用の際には十分確認と検討を行なってください。

SAM ユーザーについては以下のブログも参考にしてください。

SORACOMのアクセス管理(IAM)機能「SAMユーザー」の基本と実践例 – SORACOM公式ブログ
SAM ユーザー 参考ブログ

CLI コマンド実行時にエラーが表示される場合
SAM ユーザーの権限が十分かどうかの確認と、対象のカメラにクラウド常時録画ラインセスが正しく割り当てられているかどうかを確認してください。
クラウド常時録画ライセンスが正しく割り当てられていて録画が行われている必要があります。

SORACOM CLI

すべての操作を CLI で行うため、CLI の設定が完了している必要があります。
設定の方法や詳細はユーザードキュメントを参照してください。

SORACOM CLI 利用ガイド | 開発者向けツール | ソラコムユーザーサイト – SORACOM Users
SORACOM 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/
利用ツール一覧

カメラ情報取得

SORACOM ユーザーコンソール デバイス管理 画面

ここからは実際に 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 ユーザーコンソール
と同じ値が取れていることが確認できているかと思います。

エクスポート使用状況

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 ユーザーコンソール と同じ値が取れていることが確認できているかと思います。

ストリーミング再生

SORACOM ユーザーコンソール ストリーミング再生 画面

ストリーミング映像 (リアルタイム映像 / 録画映像) をダウンロードするための情報を取得する CLI コマンドを実行してみます。MPEG-DASH (Dynamic Adaptive Streaming over HTTP) と呼ばれるストリーミング方式に対応した URL の配列を取得できます。

このコマンドを使うことで、取得した URL を用いて Web ブラウザでのストリーミング映像の再生が行えるため、遠隔地の状況確認や、いわゆるお天気カメラのような仕組みを構築できます。

取得した URL には有効期限が設定されています。有効期限はコマンドの戻り値を利用することで、期限が変更になった場合でも修正の必要がなくなります。

  • リアルタイム映像をストリーミング再生する場合は、以下の点に注意してください。
    1. コマンドを実行した時刻を基準に、リアルタイム映像をストリーミング再生できる有効期限付きの URL を取得できます。継続してストリーミング再生を行う場合は、繰り返しコマンドを実行して、新しい有効期限付き URL を取得してください。
    2. URL の取得リクエストが成功した時点で、視聴状況にかかわらず動画の視聴可能時間 が 300 秒 (5 分) 消費されます。
    3. リクエストは毎回処理されます。同じパラメーターのリクエストもその都度 1 回として処理されます。
  • 録画映像をストリーミング再生する場合は、以下の点に注意してください。
    1. 最大 300 秒 (5 分) の録画映像をストリーミング再生できる 有効期限付きの URL を取得できます。
    2. URL の取得リクエストが成功した時点で、視聴状況にかかわらず動画の視聴可能時間 が録画映像を出力した分消費されます。
    3. リクエストは毎回処理されます。同じパラメーターのリクエストもその都度 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 を貼り付けるだけで再生できますので、動作を試したい場合は手軽に確認できる方法を試していただければと思います。

Dash JavaScript Player
MPEG-DASH JavaScript Player

録画映像ダウンロード

SORACOM ユーザーコンソール 動画のエクスポート 画面

クラウドへ常時録画で保存された録画映像を、ダウンロードできる方式でエクスポートする処理を開始する 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 度ファイルとしてダウンロードを行うことで動画の視聴可能時間を気にせず確認できます。

静止画ダウンロード

SORACOM ユーザーコンソール 静止画エクスポート 画面

クラウドへの常時録画で保存された録画映像から、静止画を切り出してエクスポートする処理を開始する 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 ユーザーコンソール と同じようにファイルのダウンロードができていると思います。
動画ではなく静止画をダウンロードすることで、動画の視聴可能時間を節約できます。

イベント一覧

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 ユーザーコンソール と同じ情報が取得できていると思います。
定期的にこのコマンドを実行して、イベントの一覧を取得することで、イベントを起点とした通知のシステムや仕組みを作れるかと思います。

ライセンス 操作

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 を利用してタイムラプス動画を作成できます。以下のドキュメントを読み進めながら試せますのでぜひチャレンジしてみてください。

【IoT ワークショップ】クラウド型カメラ「ソラカメ」のAPIでタイムラプス動画作り
タイムラプス動画を作るワークショップドキュメント

もうひとつ、イベント一覧 APIをリリースした際のブログに、実際にイベント一覧の CLI コマンドと、録画動画ダウンロート / 静止画ダウンロード の CLI コマンドを組み合わせたサンプルがありますので、そちらも参考にしてみてください。

カメラで検出した音や動体の記録を確認できるソラカメ API – SORACOM公式ブログ
イベント一覧 CLI コマンドと他の CLI コマンドの組み合わせ例

― ソラコム内田（jet）@uchimanajet7

投稿 自動化に役立つソラカメ API を CLI から呼ぶ方法 – 7 つの API を完全網羅 は SORACOM公式ブログ に最初に表示されました。

soracom トップへ

過去記事アーカイブ

2024年
01月
02月
03月
04月
05月
2023年
01月
02月
03月
04月
05月
06月
07月
08月
09月
10月
11月
12月
2022年
01月
02月
03月
04月
05月
06月
07月
08月
09月
10月
11月
12月
2021年
01月
02月
03月
04月
05月
06月
07月
08月
09月
10月
11月
12月