Safie API v2(正式版)の始め方とトライアル方法の紹介

企画本部 AIソリューション部今野です。Safie DevelopersのPdMを担当しています。

過去に「Safie APIの始め方と動作方法の紹介」にて、Safie API β版の使い方を紹介させて頂きました。投稿から一年半以上経過する訳ですが、Safie APIはSafie Developersと同時にバージョンアップされ、現在はSafie API v2(正式版)として無事に公開することができています。過去の投稿の中ではβ版を正式版とすることが業務目標とお伝えしており、それを達成してこうしてまたBlogを投稿することができて嬉しい限りです。

本投稿では、Safie API v2(正式版)より提供を開始した無料トライアルを実際に使用してみた手順について紹介します。よろしくお願いいたします。

Safie Developers, Safie APIとは？
トライアルに必要なものを揃える
Safie APIをトライアルで動かしてみる
最後に

Safie Developers, Safie APIとは？

Safie Developersは、以前はSafie APIの紹介と問い合わせを受けるのみのサイトでした。現在は、ログイン機能が用意され、Safie APIの利用に必要な情報取得や各種設定ができるポータルサイトとなっています。

developers.safie.link

Safie APIは変わらず、セーフィーが提供するクラウド録画サービスのデータを、外部のサーバーから取得したり、情報を書き足したりする機能を提供するものとなります。サーバーからの呼び出しを原則としているため、ブラウザから呼び出したい場合はSafie SDK(JavaScript)をご利用頂くこととなります。Safie SDK(JavaScript)については、改めて別の投稿で紹介したいと思っています。

Safie APIのv2(正式版)は、β版の認証情報は使用できない、メソッドが変更されている、等、様々な違いがあり、互換性は維持されていません。β版との互換性を維持しないことによる利用者のデメリットは理解していましたが、β版運用時に明らかとなっていた技術負債は軽視できるものではなく、正式版リリースを機に負債を解消して運用の安定化を行う決断をしました。正式版と銘打ってリリースした以上、今後は可能な限り仕様を公開し、後方互換を保って運用していく計画です。ご理解頂ければと思います。

互換性がなくなった分、β版ではできなかったことを大幅に盛り込みました。盛り込んだ推しの要素は以下となります。

クラウド録画サービスを契約しているだけでSafie APIのトライアルができる
認証に必要な情報がSafie Developersから待ち時間なしで取得できる
Safie APIに関する各種設定がSafie Developersから行うことができる
認証方式を「OAuth2.0認証」に加え「APIキー」方式を利用できる
β版では非公開だったRatelimitやエラー情報、など、機能制限の情報を確認できる
β版では法人向けのみ公開だが、法人・個人の両方が利用できる

他にも様々な便利になった点があります。詳細はSafie Developersのサイトにてご確認ください。

トライアルに必要なものを揃える

早速ですが、トライアルに必要な環境を揃えていきます。

クラウド録画サービスを契約をしたカメラ（自分がオーナーのもの）
Safie Developersへの登録

クラウド録画サービスを契約したカメラは、シェアされたものではなく、自分がオーナーとして契約したカメラであることが条件となっています。また、Safie Developersへの登録は以下の手順にて行います。

Safie Developersの右上の「ログイン」ボタンよりログインする ※アカウントはSafie Viewerと同じもの
ディベロッパーとしての情報を入力し、利用規約を確認の上、登録する

これにて準備は完了です。

Safie APIをトライアルで動かしてみる

私が具体的に動かした手順を紹介していきます。Safie APIはREST APIであり、多種多様な環境での呼び出しが可能なものです。今回の動作手順はあくまで一例にすぎませんが、動作理解の参考にして頂けると幸いです。環境の影響はほぼないかとは思いますが、動作環境を以下に記載しておきます。

MacBook Pro (13-inch, M1, 2020)
macOS Ventura Version 13.4.1 (c)
Google Chrome Version 116.0.5845.187 (Official Build) (arm64)
Postman Version 10.17.3
https://www.postman.com/

①Safie Developersでアプリケーションを作る

まずはアプリケーションを作成しました。アプリケーションは自分が作成するサービスを表すものになります。アプリケーションを作成する際には、認証方式を選択することが必要となります。認証方式はOAuth2.0認証とAPIキー認証の2方式を提供しており、トライアルが実行できるのはAPIキー認証方式のみとなります。認証方式の違いに詳しく知りたい方は、Safie Developersのチュートリアルの「OAuth2.0認証」「APIキー認証」をご確認ください。

Safie Developersにログインした後、「①-a 管理ツール」「①-b APIキー認証」「①-c アプリケーション新規作成」の順に選択しました(図1)。

図1. Safie Developers APIキー認証アプリケーション一覧(アプリケーション作成前)

「アプリケーションの新規作成」の画面にてアプリケーションの情報（表1）を入力し、「この内容で新規作成」を選択しました。

表1. アプリケーション新規作成アプリケーション情報参考

項目名	パラメータ
アプリケーション名称	テスト
プラン	トライアル
公開状況	非公開
利用サービス> 利用API	画像取得にチェック

「この内容で新規作成」を選択した後、「新規作成完了」のモーダルが出力されました(図2)。次にAPIキー作成の画面に進むため、「①-d APIキー管理に遷移する」を選択しました。

図2. Safie Developers アプリケーション新規作成完了モーダル

②APIキーとアプリケーションコードを取得する

前述手順を行うと、「APIキー認証アプリケーション>APIキー管理」の画面が表示された状態になります。ここからAPIキーとアプリケーションコードを取得し、記録しました。APIキーは、Safie APIを使うために必要な認証キーです。アプリケーションコードは、カメラにアプリケーションを認識させて、連携させるために使うコードとなります。

「APIキー認証アプリケーション>APIキー管理」の画面にて「②-1 APIキー新規発行」「②-2 発行」を選択し、APIキーを発行しました(図3, 図4)。「②-3 APIキーコピーアイコン」を選択し、APIキーを手元に記録しました(図5)。

図3. Safie Developers APIキー認証アプリケーション設定>APIキー管理画面(APIキー発行前)

図4. Safie Developers APIキー認証アプリケーション設定>APIキー管理画面 APIキー新規発行モーダル

図5. Safie Developers APIキー認証アプリケーション設定>APIキー管理画面(APIキー発行後)

「②-4 APIキー認証」を選択して「APIキー認証アプリケーション一覧」の画面に戻りました。「②-5 アプリケーションコードコピーアイコン」を選択して、アプリケーションコードを手元に記録しました(図6)。

図6. Safie Developers APIキー認証アプリケーション一覧(アプリケーション作成後) - 1

③デバイス連携をする

カメラの所有者側の立場で、②で記録したアプリケーションコードを使って、カメラにアプリケーションを認識させました。その後、サービスを作る側の立場でアプリケーションの利用を承認しました。

本来は、自分以外のカメラの所有者にアプリケーションコードを渡して、アプリケーションを認識してもらい、作成したサービスと連携してもらうのが正規の使い方です。今回は簡易なトライアルなので、アプリケーションを使うカメラの所有者側とサービスを作る側の両方を自分が兼ねています。

Safie Viewerを開き、「③-1 ユーザ設定」「③-2 Developers連携」の順に選択し、Developers連携の画面を開きました。「③-3 アプリケーションの追加」を選択し、「アプリケーションの追加申請」のモーダルを開きました(図7)。「③-4 アプリケーションコード」の入力枠に、記録していたアプリケーションコードを入力し、「③-5 次へ」を選択しました(図8)。「③-6 デバイス選択」にてアプリケーションを認識させたいカメラを選択しました(図9)。その後、申請内容確認画面が表示され、内容確認の上、「申請」を選択しました。

図7.Safie Viewer Developers連携

図8.Safie Viewer Developers連携アプリケーションの追加申請モーダル

図9. Safie Viewer Developers連携アプリケーションの追加申請モーダル

カメラがアプリケーションを認識した上で、最後にサービスを作る側が承認を行わなければ、Safie APIは使用できない仕組みになっています。

Safie Developersを再度開き、「③-8 APIキー認証」を選択し、「APIキー認証アプリケーション一覧」の画面を開きました。「③-9 連携デバイス管理」を選択し、「APIキー認証アプリケーション>連携デバイス管理」の画面を開きました(図10)。

図10. Safie Developers APIキー認証アプリケーション一覧(アプリケーション作成後) - 2

「APIキー認証アプリケーション>連携デバイス管理」の画面では、アプリケーションコードを入力したデバイスの情報が表示されました。「③-10 設定」より「認証状況」を「承認済み」に変更しました（図11）。

図10. Safie Developers APIキー認証アプリケーション一覧(アプリケーション作成後) - 2

これにてSafie APIを使うための準備が全て整いました。

④Safie APIでデバイス一覧を取得する

アクセス可能なデバイス一覧を取得します。1台のみの登録なので、1台の情報のみ取得されます。デバイス一覧取得は特にパラメータ指定はないので、以下URLとAPIキーの設定のみを行います。

https://openapi.safie.link/v2/devices

APIキーはAuthorizationのタブを選択し、Typeは「API Key」を選択しました。「Key」は「Safie-API-Key」の文字列を記入しました。「Value」は工程②で記録したAPIキーの文字列を記入しました。「Add to」は「Header」を選択しました。実行するとデバイス一覧がResponseに表示されました。表示された一覧からdevice_idの文字列を記録しました。

図11. Postman デバイス一覧取得実行