企画部 商品企画 今野です。Safie APIのプロジェクトの企画を担当しています。
Safie APIは現在β版として公開していますが、それを正式版にすることが近々の私の業務目標となっています。私の業務区分は、企画立案・プロジェクトマネージメントですので、バリバリの技術屋の方々に比べるとテックブログを書くには力不足感が正直否めませんが、今回、Safie APIの紹介の場を頂けるとのことで、こうして筆を取らせて頂くことになりました。
本投稿では、Safie APIの概要と簡単な動作お試し方法をご紹介します。よろしくお願いいたします。
2023.11.6 追記: 最新のSafie APIの紹介として「Safie API v2(正式版)の始め方とトライアル方法の紹介」を投稿しています。この記事の内容は古いものになっていますので、最新の情報は上記記事を確認ください。
Safie APIとは？
Safie APIは、セーフィーが提供するクラウド録画サービスのデータを、外部のサーバから取得したり、情報を書き足したりする機能を提供するものです。詳細な情報を知りたい方は、Safie DevelpersサイトにあるAPIドキュメントを参照ください。大まかには、以下の２つのことができるものと理解して頂ければ、概ね誤りはないかと思います。
- カメラから動画や静止画、検知したイベント（音や動体検知、など）を取得する
- 動画にイベント（何かが起こった時間を記録するもの）を登録する
注意頂きたいこととして、Safie APIは外部サーバからの呼び出しを原則としているため、ブラウザから呼び出すことはできないことがあります。ブラウザから呼び出したい場合は、Safie APIの利用プランに含まれているSafie web componentsをご利用ください。
Safie APIを利用するには？
Safie APIの新規利用をご希望の際は、Developerサイトの「お問い合わせ>API導入前のお問い合せ」の項目よりフォームを開いて頂き、項目「API新規利用」を「希望する」にし、他、必要情報を入力の上、送信ください。情報を受けて弊社より案内を差し上げ、手続きが進みます。Safie APIの利用には以下の2つの前提条件がありますので、お問い合わせの際にはご注意ください。
クラウド録画プランを契約すること、既に契約していること
Safie APIを利用するシステムがWebのページを持っていること
1は、Safie APIがカメラ毎に利用許可を管理しているために付いている条件です。利用者の方にカメラのシリアルナンバーを提供頂き、弊社側の管理システムにてそのカメラに権限付与を行います。
2は、認証に必要な情報をAPI利用者側のWebページに向けて送信しなくてはいけない手続きが、認証プロセス中にあるために付いている条件です。利用者の方より用意されたWebページのURIを提供頂き、弊社側の管理システムに事前に登録をします。
それぞれ事前に準備されていると手続きがスムーズに進みます。
手続きが完了すると、認証用のClient IDとClient Secretが記載された通知書が手元に届き、APIが使用できるようになります。
図１：Developerサイト お問い合わせ
ここで大変申し訳ないお話をしなければなりません。現在、Safie APIは運用キャパシティの関係で、問い合わせを頂いた全ての方々に提供することができていません。また、法人向け公開に限定しており、個人のお問い合わせはお断りしております。β版が正式版となった際にはより多くの方々にご利用頂けるよう、現在プロジェクトを推進しております。現状はご了承頂ければと思います。
Safie APIを動かしてみる
具体的にどのように動作するのか、私の方で実際に動かしてみた手順を紹介させて頂きます。REST APIですので、呼び出し方は多種多様に可能な訳ですが、あまりこの分野に明るくない方もいらっしゃるかと思います。そのような方にとって、どのようなものなのかの感触を掴む一助になれれば幸いです。動作環境の影響はほぼないかとは思いますが、参考に実際に動作させた環境を以下に記載しておきます。
MacBook Pro (13-inch, M1, 2020)
macOS Monterey version 12.0.1
Google Chrome version 95.0.4638.69 (Official Build) (arm64)
Postman Version 9.0.3 (9.0.3)
https://www.postman.com/
カメラにはトライアル用のSafie APIプランを付与
①カメラ所有者に接続許可をもらう
※今回は許可を出すのは自分自身
最初にカメラ所有者から接続許可をもらう必要があります。以下のURLに指定のQuery Paramsを付与し、カメラ所有者よりカメラ所有者のSafie Viewerのメールアドレス, パスワードを入力してもらいます。 https://openapi.safie.link/v1/auth/authorize
私はPostmanを使用してQuery Paramsを設定することで、Query Paramsを含んだURLを作成しました（図2）。
図2：接続許可をもらうURLを生成（Postman）
※client_idとredirect_uriは利用者のものを使用すること
そのURLをコピー＆ペーストでGoogle ChromeのURL欄に貼り付けることで、接続許可の画面が表示されます（図3）。
図3：接続許可をするための認証画面（Google Chrome）
今回はカメラ所有者が自分なので、自分のSafie Viewerのメールアドレス, パスワードを打ち込みました。カメラ所有者が別の人の場合は、URLを送付し、メールアドレス, パスワードを打ち込んで許可をもらう必要があります。図3の画面にて許可を行うと、redirect_uriで指定した画面に遷移します。遷移した先では、Query ParamsのKey: Codeの文字列が付与されます。以下のように「?code=」の後に16進数の羅列が付与されますので、「?code=」の後から「&status=」の前までの文字列を記録しました。
~~~?code=XXXXXXXXXXXX（16進数の羅列）&status=
②Code情報を使ってTokenを取得する
Postmanに下記URLを入力し、マニュアルに記載された指定の各パラメータを設定します。codeは記録したものを使用しました。 https://openapi.safie.link/v1/auth/token
POSTメソッド、かつ、パラメータもBodyに設定することなど指定が多いので単純にブラウザでは実行できないため、Postman上から実行しています。私はBodyのデータ形式設定を誤り一度詰まりました。正確に「x-www-form-urlencoded」を指定します。
図4：Tokenを取得（Postman）
※各パラメータは利用者のものを使用すること
成功するとPostmanのResponseにaccess_tokenが表示されます。ここで、access_tokenの文字列を記録しました。
図5: Access token 正常系Response （Postman）
③アクセスできるデバイス一覧を取得する
Tokenを無事に取得できたので、アクセス可能なデバイス一覧を取得します。デバイス一覧取得は特にパラメータ指定はないため、以下URLとToken設定のみを行います。
https://openapi.safie.link/v1/devices
TokenはAuthorizationのタブを選択し、Access Tokenの枠に②で記録した文字列を記入しました。Header Prefixは②のResponseに従いBearerに設定しました。実行するとデバイス一覧がResponseに表示されます。表示された一覧から操作したいデバイスを探し、そのdevice_idの文字列を記録しました。
図6：Authorizationの設定（Postman）
④静止画像を撮影してみる
デバイスを操作してみます。今回は静止画撮影を行っています。以下のURLの[device_id]の部分に先ほど記録したdevice_idの文字列を設定しました。
https://openapi.safie.link/v1/devices/[device_id]/image
③の操作同様、Authorizationのタブ下にTokenを設定しました（図7）。実行すると、Responseに撮影した画像が表示されます。実際に、図7のResponseで静止画像が表示されたことを確認できました。
図7：静止画の取得（Postman）
最後に
いかがでしたでしょうか。β版では運用キャパシティに限界があり、あまり大々的な広報ができない状況ですが、今回、テックブログということで簡単に紹介をさせて頂きました。紹介が主な内容だったということで、技術者の方にとっては若干物足りなかったかもしれません。今後、弊社技術者より「Safie API使ってXXXしてみた」といったような内容の記事が投稿される予定となっていますので、より技術的な内容を知りたい方は、そちらの記事も是非閲覧頂ければと思います。β版が正式版になった際は、多くの人が利用できる環境を提供でき、情報展開も大きくしていける予定です。どうぞご期待ください。
