Postmanを使ってOracle Database CloudのRESTクエリを発行する方法

[Oracle Database Cloud Service](https://cloud.oracle.com/ja_JP/database)では、RESTを使って、起動停止・パッチ適用・バックアップなどの[インスタンス管理操作](https://docs.oracle.com/cd/E60665_01/dbcs_dbaas/CSDBR/rest-endpoints.html)ができます。マニュアルや他のサイトではcURLを使った方法しか紹介されていないので、Postmanを使った方法を紹介します。

## Postmanを使うと良いこと

* GUI派にとっては見やすく、とっつきやすい
* (Windowsの場合)cURLのインストール作業で消耗しない
* REST発行履歴から、簡単に再実行できる
* よく使うRESTクエリを保存できる
* コマンドラインに生でパスワード類を打ち込まなくて良い

## Postmanのインストール

[公式サイト](https://www.getpostman.com/)からダウンロードします。Chromeの場合、Chrome拡張機能として提供されています。

以降の記事では、Chrome拡張機能としてインストールしたPostmanの画面を前提に説明します。

> 認証プロキシを使ってOracle Cloudにアクセスしなければならない環境では、プロキシを通すための準備も必要です。
>
> Chrome拡張機能では[未対応](https://github.com/postmanlabs/postman-app-support/issues/2242)のため、[Postman Interceptor](https://chrome.google.com/webstore/detail/postman-interceptor/aicmkgpgakddgnaphhhpliifpcfhicfo/)という拡張機能も導入します。導入方法は、[こちらのQiita記事](http://qiita.com/katsu_suzuki/items/fb8036776b4513366995)で紹介されています。
>
> アプリケーションのPostmanの場合は、画面右上のアイコンからプロキシのURLとポートを設定します。プロキシのユーザ名とパスワードが入った認証情報を、後述の`Authorization`を作る要領で作成し、`Header`タブで`Authorization`の前に`Proxy-`を付け、`Proxy-Authorization`ヘッダとします。

## GETの場合（インスタンス情報表示の例）

### URLと認証情報の設定

`Authorization`タブが選択されていなければ選択し、`Type`プルダウンリストから`Basic Auth`を選択します。

![Postman画面その１](https://qiita-image-store.s3.amazonaws.com/0/10290/6eb3fa5b-2e7c-5668-b2bb-4207251c3eca.png)

以下、埋めるところを順番に見ていきます。

#### (A) エンドポイントURL

エンドポイントURLは、「RESTサーバー」と「相対パス」を繋げたものです。

**RESTサーバー:** たいていの場合は`https://dbaas.oraclecloud.com/`ですが、Oracle Database Cloud Serviceの詳細表示画面で確認できます。

![詳細画面１](https://qiita-image-store.s3.amazonaws.com/0/10290/7f8fd80c-2665-4e20-ac07-35e78252d462.png)

![詳細画面２](https://qiita-image-store.s3.amazonaws.com/0/10290/c37b4ba3-0274-54d2-dae8-b84b4bdb8022.png)

**相対パス:** マニュアルの各RESTクエリの説明画面で確認できます。例えば、[DBaaSのサービス・インスタンスの表示](https://docs.oracle.com/cd/E60665_01/dbcs_dbaas/CSDBR/op-paas-service-dbcs-api-v1.1-instances-%7BidentityDomainId%7D-%7BserviceId%7D-get.html)の場合、画面はこのようになっています。

![マニュアル１](https://qiita-image-store.s3.amazonaws.com/0/10290/f117c3d4-4a0b-a6ec-b4b4-ce67994a49bc.png)

これによると、相対パスは`/paas/service/dbcs/api/v1.1/instances/{identityDomainId}/{serviceId}`のようです。さらに、`パス・パラメータ`を見てパスの一部を書き換えます。この場合は、`{identityDomainId}`をアイデンティティ・ドメイン名、`{serviceId}`をDBCSのインスタンス名に書き換えます。

#### (B) メソッド

先ほどのマニュアルに示されていますので、それと同じものをプルダウンから選択します。Oracle Cloudでは`GET`・`PUT`・`POST`・`DELETE`を選択します。

![CRUD](https://qiita-image-store.s3.amazonaws.com/0/10290/b4512bfd-bb18-81fc-038a-ab176acddccf.png)

> Database Cloud Serviceでは少ないですが、RESTの常軌を逸するメソッドの使い方をするエンドポイントがOracle Cloudに少なからず存在しますので、初めて使うエンドポイントでは、必ずマニュアルでメソッドの種類を確認するようにしましょう。

#### (C) ユーザ名とパスワード

Oracle Cloudのユーザ名とパスワードを設定します。

#### (D) ヘッダに反映

オレンジ色の`Update Request`ボタンをクリックします。

### リクエストヘッダの設定

`Headers`タブを選択します。

![ヘッダ](https://qiita-image-store.s3.amazonaws.com/0/10290/bcb52f15-c7fc-8518-e388-e3c302da4805.png)

再びマニュアルを参照します。`ヘッダ・パラメータ`を見ます。

![マニュアル２](https://qiita-image-store.s3.amazonaws.com/0/10290/bfe3b33e-f152-5e5e-e71d-eaa5e8651b97.png)

これによると、`Authorization`と`X-ID-TENANT-NAME`をヘッダに設定する必要があることが分かります。`Authoriztation`は既に追加されているので、`X-ID-TENANT-NAME`だけ追加し、アイデンティティ・ドメイン名を指定します。

### 結果の表示

青の`Send`ボタンをクリックします。

[DBaaSのサービス・インスタンスの表示](https://docs.oracle.com/cd/E60665_01/dbcs_dbaas/CSDBR/op-paas-service-dbcs-api-v1.1-instances-%7BidentityDomainId%7D-%7BserviceId%7D-get.html)など、GET系のリクエストの場合は、このようにJSONで結果が返ります。レスポンスコードは、レスポンス本文の欄の右上に小さく表示されます。`Headers`をクリックすると、レスポンスヘッダを見ることもできます。

![結果１](https://qiita-image-store.s3.amazonaws.com/0/10290/9c075650-88ce-1210-052f-26aa9fbdcc55.png)

マニュアルの`レスポンス`タブの中に、レスポンス本文の仕様が書いてあります。

![スクリーンショット 2017-03-04 14.47.41.png](https://qiita-image-store.s3.amazonaws.com/0/10290/afbefb94-d1fa-42e5-50c7-b4d6ee9115e6.png)

## GET以外の場合（インスタンス起動の例）

これまで説明してきた手順とほぼ同じです。差分は、次の３点です。

* メソッドを適切なものに変更
* リクエスト本文と、その種類を定義するためのヘッダを追加
* レスポンス本文は空で、レスポンスコードやレスポンスヘッダで情報を見る

[サービス・インスタンスまたは計算ノードの停止、起動または再起動](https://docs.oracle.com/cd/E60665_01/dbcs_dbaas/CSDBR/op-paas-service-dbcs-api-v1.1-instances-%7BidentityDomainId%7D-%7BserviceId%7D-post.html)を例にやってみます。

エンドポイントURLは先ほどと全く同じですので、そのままにします。

メソッドを、マニュアルに記載のある`POST`に変更します。

`Body`タブに行きます。

![スクリーンショット 2017-03-04 13.42.31.png](https://qiita-image-store.s3.amazonaws.com/0/10290/61832f6d-0a28-d49f-15d1-fbbddc208877.png)

ラジオボタンで`raw`を選択し、`JSON(application/json)`を選択します。この時点で、自動的にヘッダに`Content-Type`が追加され、値に`application/json`が設定されます。

さて、本文に何を書けば良いかですが、マニュアルを見ると、以下のようになっています。

![マニュアル４](https://qiita-image-store.s3.amazonaws.com/0/10290/6b8c3d80-52cd-1b1f-7976-47c5996e2447.png)

`ルート・スキーマ`という項目の中のものが、ルートレベルになります。つまり、普通にインスタンスを起動したい場合は、以下のように書けば良いことが分かります。

```json
{"lifecycleState":"start"}
```

青の`Send`ボタンをクリックすると、比較的すぐに`202 Accepted`が返ってきます。実際のインスタンス起動の完了までには少しかかるため、起動要求を受け付けたらすぐに返答を送るようにしているためです。なお、操作系のRESTでは、レスポンス本文は基本的に空です。

![結果２](https://qiita-image-store.s3.amazonaws.com/0/10290/c9a48a63-1ecf-8f28-2fa9-26aece5c1ea9.png)

## 進捗状態の表示

ここで、マニュアルの`レスポンス`タブを見てみましょう。

![マニュアル５](https://qiita-image-store.s3.amazonaws.com/0/10290/da8d6153-4202-1cbb-c35c-135ca40e134c.png)

`ヘッダー`の`Location`に、進捗を表示できるREST URIが書かれているとのことなので、Postmanの`Headers`タブをクリックして、レスポンスヘッダを見てみます。

![結果３](https://qiita-image-store.s3.amazonaws.com/0/10290/316117de-c25d-a7da-7393-7a7075b0ae06.png)

`Location`には、以下のようなURLが書かれています。

```
https://dbaas.oraclecloud.com:443/paas/service/dbcs/api/v1.1/instances/アイデンティティ・ドメイン名/status/control/job/数字
```

このエンドポイントは、マニュアルでは[操作のジョブ・ステータスの表示](https://docs.oracle.com/cd/E60665_01/dbcs_dbaas/CSDBR/op-paas-service-dbcs-api-v1.1-instances-%7BidentityDomainId%7D-status-%7BrequestName%7D-job-%7BjobId%7D-get.html)に該当します。

Postmanで新しいタブを開き、そのURLを入力して、ヘッダに`Authorization`と`X-ID-TENANT-NAME`を追加して`Send`ボタンをクリックすると、進捗情報が返ってきます。以下の例では、ジョブの実行が正常に終了しています。

![結果４](https://qiita-image-store.s3.amazonaws.com/0/10290/cdd7be70-3a6a-5e56-2307-c8042b119b38.png)