本記事はソラコムが提供する「SORACOM公式ブログ」に掲載された「カメラで検出した音や動体の記録を確認できるソラカメ API」を再編集したものです。
目次
イベント一覧 APIソラカメ対応カメラで検出されたイベントの一覧を取得する
指定されたソラカメ対応カメラで検出されたイベントの一覧を取得する
イベントが検出された瞬間を確認する
イベント情報から静止画を取得する
イベント情報から動画を取得する
まとめ
こんにちは、ソリューションアーキテクトの内田（ニックネーム: jet）です。
以下のブログで Soracom Cloud Camera Services（以下、ソラカメ）のAPIとWebコンソールのアップデートを紹介しました。
今回はこの ソラカメ API（以下、API）に「カメラで検出されたイベント（音や動体検出など）」を取得できるイベント一覧APIが追加されましたので紹介します。
今回追加されたAPIのAPIリファレンスはこちらです。
- ソラカメ対応カメラのイベント一覧を取得する / listSoraCamDeviceEventsForDevice
- ソラカメ対応カメラで検出されたイベントの一覧を取得する / listSoraCamDeviceEvents
このAPIを利用すると例えば、音や動体検出などのイベントを検知した瞬間の静止画や、映像だけを取得できるようになります。
イベントが発生した期間の動画をダウンロードして手元に保存したり、イベント検出時の静止画を時系列で並べることで、変化の様子を記録するなど新しいソリューションのきっかけとして利用できます。
弊社の社員が花壇によく動物の足跡が付いているのを見つけて、ソラカメを設置して監視をしたところ、ある朝に新しい足跡を発見し、通常であれば昨夜の動画を全部見て確認するところを、最初にイベント一覧を確認して猫が写っているところがあったので、その周辺の動画を確認したところ、直ぐに猫を特定することができました。
この様に、このAPIを利用することによって、目的の動画に効率的にアクセスできるようになるので、皆様是非ご活用ください。
イベント一覧 API
ソラカメのライセンスを紐づけているカメラでモーション検知設定を有効化していれば、カメラで検出されたイベントに関する情報が取得可能になります。
すでにATOM Cam 2やATOM Cam Swingをお持ちの方へ:
ソラカメのライセンスは、ライセンス単体でオンラインでお求めいただくことができます。詳しくは「ソラカメ」ライセンス単独販売開始のお知らせをご覧ください。
SORACOMユーザーコンソールで確認すると、以下が確認できます。
- 日時：イベントが検出された日時
- デバイスタイプ：イベントが検出されたデバイスの種類
- デバイス：イベントが検出されたデバイス。デバイス詳細画面へのリンクになっています
- イベントタイプ：検出されたイベントの種類
- イベント画像：イベントが検出された際の画像。有効期限があります。
- 画像をダウンロードするボタン：イベント画像に表示されている画像をダウンロードできます。有効期限があります。
- 映像を確認するボタン：イベントを検出した開始時刻から終了時刻までをストリーミング映像で確認できます。ここで映像を確認すると月72 時間分の再生時間が消費されます。
ソラカメ対応カメラで検出されたイベントの一覧を取得する
実際にSORACOM CLIを利用して、イベント一覧を取得するAPIを実行してみます。
SORACOM CLIは最新のバージョンを利用してください。
実行するAPI
ソラカメ対応カメラで検出されたイベントの一覧を取得します (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.] ]
指定されたソラカメ対応カメラで検出されたイベントの一覧を取得する
指定されたソラカメ対応カメラについて、イベントの一覧を取得します。
実行するAPI
指定されたソラカメデバイスで検出されたイベントの一覧を取得します (SoraCam:listSoraCamDeviceEventsForDevice)
CLIコマンド サンプル
※ --device-id の引数は soracom sora-cam devices events list で得たリストの中から対象の deviceId を指定します。
soracom sora-cam devices events list-for-device --device-id 7CXXXXXXXX0E
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.] ]
イベントが検出された瞬間を確認する
最後は実際にイベントAPIを利用して、イベントが検出された瞬間を確認してみます。
イベント一覧から1つイベントを選択して、そのイベントについて動画と静止画を取得していきます。
コマンドサンプルではイベント一覧の最後のイベントを対象としています。
イベントの中には動画が取得できないものがあるので、その場合は別のイベントを選択するなどしてください。
イベント情報から静止画を取得する
イベント情報の中にある time の値はイベントが開始された値となるため、この値を使って静止画を取得するAPIを呼び出します。
CLIコマンド サンプル
※最後の open コマンドは macOS 特有のものであり、Windows(PowerShellやWSL)や、Linuxの場合は画像を開くアプリケーションにて開くようにしてください。
SORA_CAM_EVENT=$(soracom sora-cam devices events list | jq -r '.[-1:]') echo ${SORA_CAM_EVENT} IMAGE_TIME=$(echo ${SORA_CAM_EVENT} | jq -r '.[].time' ) echo ${IMAGE_TIME} soracom sora-cam devices images export --device-id ${DEVICE_ID} --time ${IMAGE_TIME} EXP_ID=$(soracom sora-cam devices images list-exports --device-id ${DEVICE_ID} | jq -r '.[0].exportId') echo ${EXP_ID} soracom sora-cam devices images get-exported --device-id ${DEVICE_ID} --export-id ${EXP_ID} IMAGE_URL=$(soracom sora-cam devices images get-exported --device-id ${DEVICE_ID} --export-id ${EXP_ID} | jq -r .url) echo ${IMAGE_URL} IMAGE_FILE=~/_test/img-test.jpeg curl -v -L ${IMAGE_URL} -o ${IMAGE_FILE} open ${IMAGE_FILE}
イベント情報の中にも picture として画像のURLが付与されているので、このURLからイベント開始時の静止画は確認できます。どちらも同じ画像となるため、72時間の出力制限を消費しないイベント情報の画像を利用するのも良い方法かと思います。
picture のURLには有効期限が存在します。有効期限が過ぎて画像が取得できない場合には再度イベント情報を取得しなおしてください。
イベント情報から動画を取得する
イベント情報の中にある startTime / endTime の値はイベントが開始 / 終了の値となるため、この値を使って録画映像をダウンロードするAPIを呼び出します。
2022年12月現時点 でのAPIの制限として1回のダウンロードで指定できる時間の長さは5分以内となっています。コマンドサンプルでは戻り値の startTime / endTime をそのまま from / to に利用していますが、5分を超えている場合はダウンロードAPIでエラーになるので注意してください。
CLIコマンド サンプル
VIDEO_FROM=$(echo ${SORA_CAM_EVENT} | jq -r '.[].eventInfo.atomEventV1.startTime') VIDEO_TO=$(echo ${SORA_CAM_EVENT} | jq -r '.[].eventInfo.atomEventV1.endTime' ) echo ${VIDEO_FROM} echo ${VIDEO_TO} soracom sora-cam devices videos export --device-id ${DEVICE_ID} --from ${VIDEO_FROM} --to ${VIDEO_TO} EXP_ID=$(soracom sora-cam devices videos list-exports --device-id ${DEVICE_ID} | jq -r 'sort_by(.requestedTime) | reverse | .[0].exportId') echo ${EXP_ID} soracom sora-cam devices videos get-exported --device-id ${DEVICE_ID} --export-id ${EXP_ID} VIDEO_URL=$(soracom sora-cam devices videos get-exported --device-id ${DEVICE_ID} --export-id ${EXP_ID} | jq -r .url) echo ${VIDEO_URL} VIDEO_ZIP_FILE=~/_test/video-test.zip VIDEO_FILE=~/_test/video-test.mp4 curl -v -L ${VIDEO_URL} -o ${VIDEO_ZIP_FILE} unzip -p ${VIDEO_ZIP_FILE} > ${VIDEO_FILE} open ${VIDEO_FILE} ffmpeg -i ${VIDEO_FILE} -ss 0 -t 1 -r 1 ~/_test/%06d.jpg open ~/_test
まとめ
今回は「検出されたイベント」を取得できるAPIが追加されたので、APIの紹介と簡単な利用方法を書いてみました。定期的にこのイベントAPIを呼び出して、イベントの一覧を取得することで、イベントを起点としたシステムや仕組みを作れるかと思います。
例えば、部屋の出入り口に設置されているカメラで定期的にイベントを取得し、イベントから静止画を取得しておけば、部屋の入退出リストを画像付きで作ることができます。イベントAPIがPull型となるのでイベントを検知したタイミングで、リアルタイム通知とならない部分はご注意ください。
新しく追加されたAPIを紹介しました。実務に利用する際に少しでも参考になれば嬉しいです。
APIはこれからも引き続き機能追加が行われていく予定となりますので、ぜひ実際に試していただき必要な機能があれば フィードバック をよろしくお願いします。
― ソラコム内田（jet）@uchimanajet7
投稿 カメラで検出した音や動体の記録を確認できるソラカメ API は SORACOM公式ブログ に最初に表示されました。
この連載の記事
-
第402回
デジタル
技術評論社の書籍「IoTの知識地図」が発売、Soracom Onyx用防水・防塵アンテナセットの販売を開始 takuyaのほぼ週刊ソラコム 04/15-05/03 -
第401回
デジタル
IoTの基礎知識から実務を網羅した一冊「IoTの知識地図」 ― 見どころ解説 -
第400回
デジタル
USB型LTEデバイス「Soracom Onyx」向け、防水・防塵アンテナセットの販売開始 -
第399回
デジタル
クラウド型カメラの新たな使い方を提案！ソラカメの新機能「ライブ視聴見放題」ご紹介 -
第398回
デジタル
見える化、監視の次は？ ソラコムが考える製造業IoTのメリットと課題 -
第397回
デジタル
Make a Global Impact as a Technical Writer at Soracom -
第396回
デジタル
SORACOM LTE-M Button powered by AWSの移行受付を開始、SPSアワード 2023の表彰を発表 takuyaのほぼ週刊ソラコム 04/01-04/14 -
第395回
デジタル
SORACOMの新機能開発の舞台裏 ― お客様の声からリリースまでの道のり -
第394回
デジタル
動画で分かる！SORACOM Lagoon 3への移行の手順 -
第393回
デジタル
ソラカメ運用管理をより簡単に！アクセス権限設定テンプレートのご紹介