Oracle Database Cloud Serviceでは、RESTを使って、起動停止・パッチ適用・バックアップなどのインスタンス管理操作ができます。マニュアルや他のサイトではcURLを使った方法しか紹介されていないので、Postmanを使った方法を紹介します。
Postmanを使うと良いこと
- GUI派にとっては見やすく、とっつきやすい
- (Windowsの場合)cURLのインストール作業で消耗しない
- REST発行履歴から、簡単に再実行できる
- よく使うRESTクエリを保存できる
- コマンドラインに生でパスワード類を打ち込まなくて良い
Postmanのインストール
公式サイトからダウンロードします。Chromeの場合、Chrome拡張機能として提供されています。
以降の記事では、Chrome拡張機能としてインストールしたPostmanの画面を前提に説明します。
認証プロキシを使ってOracle Cloudにアクセスしなければならない環境では、プロキシを通すための準備も必要です。
Chrome拡張機能では未対応のため、Postman Interceptorという拡張機能も導入します。導入方法は、こちらのQiita記事で紹介されています。
アプリケーションのPostmanの場合は、画面右上のアイコンからプロキシのURLとポートを設定します。プロキシのユーザ名とパスワードが入った認証情報を、後述の
Authorizationを作る要領で作成し、HeaderタブでAuthorizationの前にProxy-を付け、Proxy-Authorizationヘッダとします。
GETの場合（インスタンス情報表示の例）
URLと認証情報の設定
Authorizationタブが選択されていなければ選択し、TypeプルダウンリストからBasic Authを選択します。
以下、埋めるところを順番に見ていきます。
(A) エンドポイントURL
エンドポイントURLは、「RESTサーバー」と「相対パス」を繋げたものです。
RESTサーバー: たいていの場合はhttps://dbaas.oraclecloud.com/ですが、Oracle Database Cloud Serviceの詳細表示画面で確認できます。
相対パス: マニュアルの各RESTクエリの説明画面で確認できます。例えば、DBaaSのサービス・インスタンスの表示の場合、画面はこのようになっています。
これによると、相対パスは/paas/service/dbcs/api/v1.1/instances/{identityDomainId}/{serviceId}のようです。さらに、パス・パラメータを見てパスの一部を書き換えます。この場合は、{identityDomainId}をアイデンティティ・ドメイン名、{serviceId}をDBCSのインスタンス名に書き換えます。
(B) メソッド
先ほどのマニュアルに示されていますので、それと同じものをプルダウンから選択します。Oracle CloudではGET・PUT・POST・DELETEを選択します。
Database Cloud Serviceでは少ないですが、RESTの常軌を逸するメソッドの使い方をするエンドポイントがOracle Cloudに少なからず存在しますので、初めて使うエンドポイントでは、必ずマニュアルでメソッドの種類を確認するようにしましょう。
(C) ユーザ名とパスワード
Oracle Cloudのユーザ名とパスワードを設定します。
(D) ヘッダに反映
オレンジ色のUpdate Requestボタンをクリックします。
リクエストヘッダの設定
Headersタブを選択します。
再びマニュアルを参照します。ヘッダ・パラメータを見ます。
これによると、AuthorizationとX-ID-TENANT-NAMEをヘッダに設定する必要があることが分かります。Authoriztationは既に追加されているので、X-ID-TENANT-NAMEだけ追加し、アイデンティティ・ドメイン名を指定します。
結果の表示
青のSendボタンをクリックします。
DBaaSのサービス・インスタンスの表示など、GET系のリクエストの場合は、このようにJSONで結果が返ります。レスポンスコードは、レスポンス本文の欄の右上に小さく表示されます。Headersをクリックすると、レスポンスヘッダを見ることもできます。
マニュアルのレスポンスタブの中に、レスポンス本文の仕様が書いてあります。
GET以外の場合（インスタンス起動の例）
これまで説明してきた手順とほぼ同じです。差分は、次の３点です。
- メソッドを適切なものに変更
- リクエスト本文と、その種類を定義するためのヘッダを追加
- レスポンス本文は空で、レスポンスコードやレスポンスヘッダで情報を見る
サービス・インスタンスまたは計算ノードの停止、起動または再起動を例にやってみます。
エンドポイントURLは先ほどと全く同じですので、そのままにします。
メソッドを、マニュアルに記載のあるPOSTに変更します。
Bodyタブに行きます。
ラジオボタンでrawを選択し、JSON(application/json)を選択します。この時点で、自動的にヘッダにContent-Typeが追加され、値にapplication/jsonが設定されます。
さて、本文に何を書けば良いかですが、マニュアルを見ると、以下のようになっています。
ルート・スキーマという項目の中のものが、ルートレベルになります。つまり、普通にインスタンスを起動したい場合は、以下のように書けば良いことが分かります。
{"lifecycleState":"start"}
青のSendボタンをクリックすると、比較的すぐに202 Acceptedが返ってきます。実際のインスタンス起動の完了までには少しかかるため、起動要求を受け付けたらすぐに返答を送るようにしているためです。なお、操作系のRESTでは、レスポンス本文は基本的に空です。
進捗状態の表示
ここで、マニュアルのレスポンスタブを見てみましょう。
ヘッダーのLocationに、進捗を表示できるREST URIが書かれているとのことなので、PostmanのHeadersタブをクリックして、レスポンスヘッダを見てみます。
Locationには、以下のようなURLが書かれています。
https://dbaas.oraclecloud.com:443/paas/service/dbcs/api/v1.1/instances/アイデンティティ・ドメイン名/status/control/job/数字
このエンドポイントは、マニュアルでは操作のジョブ・ステータスの表示に該当します。
Postmanで新しいタブを開き、そのURLを入力して、ヘッダにAuthorizationとX-ID-TENANT-NAMEを追加してSendボタンをクリックすると、進捗情報が返ってきます。以下の例では、ジョブの実行が正常に終了しています。
