Postmanを使ってWeb APIにアクセスする その2

先日投稿した「Postmanを使ってWeb APIにアクセスする」シリーズの第二回目です。今回は少し応用的な使い方をご紹介します。今回ご紹介する内容は以下の通りです。

複数環境からPostmanを利用する

前回はPostmanを単なるWeb APIのリクエスト発行ツールとしてのみ利用しましたが、PostmanサービスにサインインすることでAPIリクエスト設定を複数環境から利用できるようになります。

画面右上のSign Inボタンを選択してPostmanサービスへのサインアップとサインインを行います。

複数環境からPostmanを利用する

サインインすることで、他のPCでも同じ設定を確認・編集できるようになります。複数の環境で作業する場合、とても便利な機能かと思います。

Postmanのユーザ名表示

Postmanの環境変数を利用する

Postmanではキーバリュー形式の環境変数を利用できます。環境変数を利用すると、例えばあるサービス(SendGridなど)のアカウントを複数持っていて、アカウントを切り替えて同じエンドポイントにアクセスして挙動を確認する、といったことが簡単にできるようになります。

環境変数を設定するには画面右上の歯車アイコンを選択し、Manage Environmentsを選択します。

Postmanの環境変数を利用する

Addボタンを選択して環境を追加します。

Addボタンを選択

環境名を入力し、環境変数名とその値を入力してダイアログを閉じます。以下の例では、テスト環境1という環境名の配下にAuthorizationという環境変数を作成し、その値(Value)に先ほどHeadersタブで登録した「Bearer SendGridのAPIキーの値」を入力しています。

Bearer SendGridのAPIキーの値を入力

作成した環境変数は、「{{ }}」でくくってやることでAPIリクエスト内で利用できます。前回の記事ではAuthorizationヘッダに直接認証情報を埋め込みましたが、これを先ほど作成した環境変数(具体的には{{Authorization}})に変更し、画面右上で環境名を選択します。

Authorization

これで環境変数を実際の値に置換してリクエストを発行できます。私は本番環境、テスト環境、デモ環境など複数の環境を切り替えるのに利用しています。

SendGridのAPI設計ドキュメントをPostmanで読み込む

SendGridの英語版APIリファレンスでは、SwaggerまたはRAMLのようなAPI定義ファイルを出力できます。このファイルをPostmanにインポートすることで、APIリクエスト設定を作成する手間を大幅に削減できます。

まず、SendGridのAPIリファレンスページでOAS(Swagger)またはRAML定義ファイルをダウンロードしてローカルに保存します。今回はSwaggerの定義ファイルをインポートするのでOASを選択します。

SendGridのAPI設計ドキュメントをPostmanで読み込む

次にPostmanの画面左上のImportボタンを選択します。

Import

先ほどローカルに保存した定義ファイルをドラッグ&ドロップします

ドラッグ&ドロップ

これだけで全APIの定義を一括でインポートできます。認証情報とAPIのリクエストパラメータの調整を行ってすぐに利用することができます。

全APIの定義を一括でインポート

APIのレスポンスを次のAPIリクエストで利用する

いくつかのAPIでは、複数のエンドポイントを利用して、先に呼び出したAPIのレスポンスを次のAPIリクエストで使用したい場合があります。例えばSendGridでは、送信予約指定したメールをキャンセルする場合、以下の流れで各エンドポイントを呼び出します。

  1. キャンセル用Batch IDを生成する
  2. 生成したBatch IDを指定してメールの送信予約指定をする
  3. 送信予定時刻前に、Batch IDを指定して配信キャンセルを行う

手順1で生成したBatch IDは手順2および3のリクエストパラメータとして指定する必要があります。Batch IDの値は毎回異なるので各リクエストパラメータの修正には手間がかかります。Postmanを使うと、レスポンス内の特定の値を環境変数に代入できるので、こういった手動での編集作業をなくすことができます。

まず、「batch_id」という環境変数を作成します。変数名自体は何でもよいのですが、説明の都合上、今回はこの名前にしてあります。この変数にはBatch ID生成エンドポイントで生成したBatch IDを格納するので現時点ではValueは空のままにしておきます。

Batch ID

次に、Batch ID生成エンドポイントのAPIリクエスト設定を作成します。HeadersタブでAutohorizationヘッダの設定を行うのを忘れないでください。必要な設定を入力したらTestsタブを選択します。TestsタブではAPIリクエスト後に実行するスクリプトを書くことができます。

Batch ID生成用エンドポイントの設定を入力

ここでは以下の内容のスクリプトを入力します。これはレスポンスボディに含まれるbatch_idの値を取り出して、先ほど作成した環境変数のbatch_idに格納する内容となっています。

var data = JSON.parse(responseBody);
postman.setEnvironmentVariable("batch_id", data.batch_id);

ここまでできたら、試しにBatch ID生成のAPIリクエスト設定を実行するためにSendボタンを選択します。Status201 CREATEDとなったらリクエスト成功です。レスポンスボディでBatch IDが返ってきていることを確認します。

リクエストを実行

生成されたBatch IDは先ほどTestsタブに入力したスクリプトによってbatch_idという環境変数に格納されているはずです。環境変数を確認してみるとValueに取得したbatch_idの値が格納されていることがわかります。

batch_idの格納

あとはメール送信リクエストと配信キャンセルリクエスト内で{{batch_id}}と指定すると環境変数を参照できます。

batch_idを参照

batch_idを参照

これら3つのリクエストを順に実行することで、冒頭に書いた一連の流れをPostman内で実行できます。取得したレスポンスから次のAPI呼び出しに必要なパラメータをコピー&ペースト、、、みたいなことをしなくていいのでとても楽です。
それぞれの動作確認ができたら次の節で紹介するRunner機能のために各APIリクエスト設定を一つのフォルダ内に保存しておきましょう。

各APIリクエスト設定を保存

Runner機能を利用して一連のAPI呼び出しを自動的に行う

一つ前の節でご紹介した手順では、ある機能を利用するのに複数のエンドポイントを決まった順番で呼び出す必要がありました。Postmanには複数のAPIリクエスト設定を順番に呼び出してくれるRunnerという機能があります。Runner機能では呼び出し回数や間隔を指定して繰り返し呼び出す、といった使い方もできます。

Runner機能を利用するにはPostman画面左上のRunnerボタンを選択します。すると別のウィンドウが開きます。

Runner機能を利用

連続実行したい一連のAPIリクエスト設定を格納したフォルダと環境名を選択したら、画面下部の青いボタンを選択するだけで順番に実行してくれます。結果は実行後に表示されます。複雑なAPI呼び出しも一度設定すれば何度でも同じ挙動を再現できるのでとても便利です。

実行
実行

さて、ここまでPostmanの機能をいろいろとご紹介してきました。元々、PostmanはAPIの開発を支援するサービスです。今回はご紹介しませんでしたが、モックサーバ機能やAPIドキュメントの生成機能など、API自体やAPIにアクセスするライブラリを開発するための機能も充実していますので、ぜひチェックしてみてください。