SPP のすべての機能は API を通して利用することができます。今回は、SPP に組み込まれている Swagger UI の使用方法を紹介します。
※参照：OneIdentity/safeguard-api-tutorial（https://github.com/OneIdentity/safeguard-api-tutorial）
SPP API について
SPP は RESTベースの API（RESTful API）を提供します。SPP API のエンドポイントは、HTTP オペレーターや JSON（または XML）のリクエストとレスポンスを使って呼び出されます。
SPP API は、Swagger でドキュメント化されています。ユーザーは、Swagger UI から API を直接呼び出したり、URL やパラメーター、ペイロードに関するドキュメントを確認したりすることができます。
SPP API は、One Identity のオープンソースプロジェクトでサポートされます。SPP API を学習するために役立つ API チュートリアルやハンズオンラボ、PowerShell や bash で使用できるスクリプトリソースも用意されています。
SPP API を構成するサービス
SPP API は、core、appliance、notification、event、a2a サービスから構成されています。
| サービス | 説明 |
|---|---|
| core | クラスタ全体の操作、アクセスリクエストワークフロー、資産管理、ポリシー管理など、ほとんどの製品機能 |
| appliance | IP アドレスの設定、メンテナンス、バックアップ、サポートバンドル、アプライアンス管理など、アプライアンス固有の操作 |
| notification | 匿名、未認証の操作 |
| event | リアルタイムイベントのために SignalR に接続するための専用エンドポイント |
| a2a | アプリケーション統合に特化した操作。パスワードの取得、ユーザーに代わってのアクセスリクエストなど |
これら SPP API サービスごとに OpenAPI ファイルがあります。
Swagger OpenAPI ファイルへのアクセス
Swagger OpenAPI ファイルへアクセスするには、ブラウザで以下にアクセスします。
https://<SPPのネットワークアドレス>/service/<サービス名>/swagger/v4/swagger.json
ここでは、Firefoxを使用しています。SPP OpenAPI ファイルへは、Firefox またはその他 JSON パーサーでアクセスすることをお勧めします。
paths ノードを展開すると、SPP API でこのサービスに対して公開されているすべてのエンドポイントが表示されます。
展開すると、利用可能な HTTP メソッドが表示されます（例：get、post、put、delete）。
これらの HTTP メソッドは、標準的なデータ操作の動詞 (CRUD) に対応しています。
- post = create
- get = read
- put = update
- delete = delete
components/schemas ノードを展開すると、SPP API で、このサービスに対して公開されているすべてのデータ転送オブジェクト(data transfer objects = DTOs) が表示されます。DTOは、REST API から渡されるデータ表現です。
SPP Swagger UI へのアクセス
Swagger UI にアクセスするには、ブラウザで以下にアクセスします。
https://<SPPネットワークアドレス>/service/<使用するSPPサービス>/swagger
notification サービスの呼び出し
最初に、notification サービスを見てみます。 ブラウザを起動し、以下にアクセスします。
https://<SPPのネットワークアドレス>/service/notification/swagger
自動的に以下のアドレスにリダイレクトされます。
https://<SPPのネットワークアドレス>/service/notification/swagger/index.html
ページがロードされると、サービスによってホストされているトップレベルのエンドポイントリストが表示されます。
Status をクリックすると、利用可能なエンドポイントが表示されます。
例として、GET /v4/Status/Availability をクリックしてみます。
エンドポイントと対話できる HTML フォームが表示されます。
出力形式を選択することができます。
Schema リンクをクリックすると、オブジェクトプロパティの詳細情報が表示されます。
Try it out ボタンをクリックします。
Execute ボタンをクリックします。
GET /v4/Status/Availability エンドポイントが呼び出されます。
Swagger UI がサーバーに HTTP GETリクエストを発行し、HTTP レスポンスの結果が表示されます。
Code には、呼び出しが成功したかどうかが示されます。200番台は成功で、400番台や500番台は失敗です。
Response body フィールドには、結果が表示されます。失敗した場合は Response body フィールドに情報が表示されます。
Response body の情報を見ると、SPPアプライアンスが ”Online”（オンライン）状態であることがわかります。
この notification エンドポイントは SPP がメンテナンス中であっても利用可能で、認証も必要ありません。
cURL コマンドをロードバランサーから使用して、SPP アプライアンスが ”Online”であるかどうかをチェックすることができます。また、このアプライアンスが ”IsPrimary”（プライマリかどうか）を判断することもできます。
core サービスの呼び出し
次に、実際に SPP の設定変更を行う core サービスを見てみます。
ブラウザの URL を次のように変更します。
https://<SPPのネットワークアドレス>/service/core/swagger/index.html
今回は、OpenAPI ファイルが大きいため、ページの読み込みに時間がかかります。
ページがロードされたら、例として AssetPartitions のエンドポイントをクリックし、
GET /v4/AssetPartitions をクリックします。
先ほどと同じように Try it out をクリックした後、Execute をクリックします。
今回の HTTP レスポンスコードは、401（エラー）でした。これは、ユーザーが認証されていないためです。
前の notification サービスの呼び出しは認証なしで実行できましたが、今回は、ユーザーの認証が必要です。
認証のため、Swagger UI ページの上部にある Authorize ボタンをクリックします。
Authorize をクリックします。
SPP のログイン画面が表示されます。
ここでは、「資産」アクセス許可権限を持つユーザーでログインしてください。
Close ボタンをクリックして、画面を閉じます。
もう一度、GET /v4/AssetPartitions で Execute をクリックしてみてください。
Codeが 200番ですので、今回は成功です。
レスポンスコードが 403 の場合、ユーザーは認証されたが、エンドポイントを使用するためのアクセス許可権限を持っていないことを意味します。適切なアクセス許可権限を持つユーザーで認証をやり直してください。
appliance サービスの呼び出し
最後に、appliance サービスも見てみましょう。
ブラウザの URL を次のように変更します。
https://<SPPのネットワークアドレス>/service/appliance/swagger/index.html
例として、ApplianceStatus をクリックし、POST /v4/ApplianceStatus/Reboot エンドポイントをクリックします。
Try it out ボタンをクリックします。
［Reason for performing operation］フィールドに test と入力して、Execute ボタンをクリックします。
401 エラーが戻ります（認証されていないため、実行に失敗しました）。
これは、Swagger UI ページを切り替えるたびに再認証が必要であるためです。前と同じ手順で認証（今回は、「アプライアンス」または「操作」アクセス許可権限を持つユーザーで認証）すれば、この API を実行することができます。
Swagger UI を頻繁に使用する予定がある場合は、ブラウザを複数のタブで開いたままにしておくことをお勧めします。
このセクションには、アプライアンスの状態を変更するのに便利なエンドポイントがあります。
IPアドレスの変更、再起動、シャットダウン、バックアップの取得、その他多くの操作をこのインターフェイスから行うことができますが、たいていの場合、認証された「アプライアンス」アクセス許可権限を必要とします。
さいごに
SPP は、他のアプリケーションやシステムとの連携を可能にする RESTful API を提供します。SPP API を学習するために役立つ API チュートリアルやハンズオンラボ、Powershell や bash で使用できるスクリプトリソースも用意されています。評価版でお試しください。
SPP 製品紹介ページ
SPPには、この記事で紹介した以外にも機能があります。
その他の特長や機能については、それぞれの製品紹介ページをご参照ください。
SPP 評価版
SPP の評価版は、仮想アプライアンス（OVAまたはVHDXファイル）で提供いたします。
SPPの評価版では、すべての機能を 90日間無料でご利用いただけます。
評価版の利用をご希望いただく場合は、下記お問い合わせフォームから評価ライセンスをお申し込みください。
お問い合わせ
購入前の SPP に関するお問い合わせは、下記お問い合わせフォームからお問い合わせください。
