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

「Postmanを使ってWeb APIにアクセスする」後編の今回は、少し応用的な以下の内容についてご紹介します。基本的な使い方は前編をご覧ください。

• Postmanの環境変数を利用する
• SendGridのAPI設計ドキュメントをPostmanで読み込む
• APIのレスポンスを次のAPIリクエストで利用する
• Runner機能を利用して一連のAPI呼び出しを自動的に行う

Postmanの環境変数を利用する

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

環境変数を設定するには、画面左のEnvironmentsタブでCreate Environmentを選択します。

環境名を入力し、環境変数名とその値を入力します。以下の例では、Test Environmentという環境の配下に「apiKey」という環境変数を作成し、その値（Value）にSendGridのAPIキーの値を入力しています。また、APIキーは機密情報であるため、鍵アイコンをクリックし「Mark as sensitive」を有効にしています（入力値がマスク表示されます）。なお、環境変数の変更内容は自動的に保存されます。

それでは作成した環境変数を使用してみましょう。環境変数は「{{ }}」で囲って使用します。
＋ボタンを選択してリクエスト生成画面を開きます。画面右上で、使用する環境名（今回はTest Environment）を選択し、Authorizationタブで以下のように設定します。

• Auth Type：Bearer Tokenを選択
• Token：「{{apiKey}}」を入力

これで、リクエスト発行時に環境変数が実際の値に置換されるようになります。本番用、テスト用、デモ用など環境を切り替えて同じリクエストを呼び出すのに便利です。

SendGridのAPI定義ファイルをPostmanで取り込む

SendGridのAPIは、Open API 3.1形式のAPI定義ファイル（JSON / YAML）がGitHub上で公開されています。このファイルをPostmanにインポートすることで、APIリクエスト設定を作成する手間を大幅に削減できます。

Postmanでは、API定義ファイルのURLを指定して直接インポートすることができます。
まず、GitHubのリポジトリから目的のAPI定義ファイルのURLを取得します。SendGridではAPIの種類ごとに定義ファイルが分かれているため、今回はMail Send APIが含まれている以下のtsg_mail_v3.jsonを取り込みます。
https://github.com/twilio/sendgrid-oai/blob/main/spec/json/tsg_mail_v3.json

上記URLにアクセス後、画面右上の「Raw」ボタンをクリックし、アドレスバーに表示されているRaw形式のURL「https://raw.githubusercontent.com/…」を取得します。

次にPostmanのImport画面を開きます。
画面左のCollectionsタブを選択し、画面左上のImportボタンを選択します。

URL入力欄に、先ほど取得したtsg_mail_v3.jsonのRaw形式のURLを入力します。

URLを入力すると自動的に遷移するChoose how to import your Specification画面で、まずはインポートの設定を行います。View Import Settingsを選択し、設定項目Folder organizationに「Tag」を設定します。これにより、今後複数のAPI定義をインポートする際、フォルダ構成が分かりやすくなります。

Choose How to import your Specification画面に戻った後、Postman Collectionを選択し、Importボタンを選択します。

Import completeと表示されたら取り込み成功です。
これだけでAPIの定義をインポートでき、画面左のCollectionsから一覧を確認できます。認証情報とAPIのリクエストパラメータの調整を行えばすぐに利用可能です。

インポートされたAPIの中には弊社で契約したアカウントでは使えないものも含まれています。また、上記API定義ファイルは最新ではない場合もあるため、利用可能なAPIの確認は日本版APIリファレンスを参照してください。

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

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

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

1で生成したBatch IDを2および3のリクエストパラメータとして指定する必要がありますが、Batch IDの値は毎回異なるので、2と3のリクエストパラメータを都度修正しなければなりません。Postmanでは特定のAPIリクエストの特定の値を変数として指定できるので、このような手動での編集作業をなくすことができます。

まずはAPI定義をインポートします。「SendGridのAPI定義ファイルをPostmanで取り込む」では、手順1および2で使用するAPI定義をインポートしました。ここでは手順3で使用するAPI定義をインポートします。以下URLからRaw形式のURLを取得し、インポートしてください。
https://github.com/twilio/sendgrid-oai/blob/main/spec/json/tsg_scheduled_sends_v3.json

インポートが完了すると、Collectionsに追加でインポートしたAPI定義が表示されます。

次に環境変数を作成します。今回は「batch_id」という名前にしました。この変数にはBatch ID生成エンドポイントで生成したBatch IDを格納するので、現時点ではValueは空のままにしておきます。

次に、Batch ID生成エンドポイントのAPIリクエスト設定を作成します。Authorizationタブで認証情報の設定を行うのを忘れないでください。また、今回は親アカウントのAPIキーで親アカウントを操作するため、Headersタブのon-behalf-ofはOFFにしておきます。設定が完了したらScriptsタブを選択します。ScriptsタブではAPIリクエスト後に実行するスクリプトを書くことができます。

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

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

ここまで完了したら、Sendボタンを選択してBatch ID生成のAPIリクエストを実行してみましょう。Statusが201 Ceatedとなったらリクエスト成功です。レスポンスボディでBatch IDが返ってきていることを確認します。

Scriptsタブに入力したスクリプトにより、生成されたBatch IDは環境変数batch_idに格納されています。Test Environmentタブから、取得したBatch IDがbatch_idのValueに格納されていることを確認しましょう。

あとはメール送信リクエストと配信キャンセルリクエストのbatch_idパラメータで{{batch_id}}と指定すれば、環境変数を参照したリクエストが実行できます。

これら3つのリクエストを順に実行することで、冒頭に書いた一連の流れをPostmanで楽に実現できます。それぞれの動作確認ができたら次の節で紹介するRunner機能のために、各APIリクエスト設定を一つのコレクションに保存しておきましょう。
リクエスト設定画面の右上にあるSaveボタン横のプルダウンをクリックし、「Save as」を選択すると、保存するCollectionを選択する画面が表示されます。左下のNew Collectionを選択してコレクション名を入力したら、Createを選択します。APIリクエスト設定につける名前をRequest nameに入力してSaveします。同様に残り2つのリクエストも保存しましょう。

インポートした API 定義のコレクションには baseUrl の変数が定義されています。新しく作成したコレクションにも同様の変数を定義します。

• Variable：baseUrl
• Value：https://api.sendgrid.com

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

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

Collection Runner機能を利用するには、作成したコレクションの横三点リーダからRunを選択します。Run Sequenceでリクエストをドラッグして実行順を設定したら、Run Schedule and Cancelを選択して一連の呼び出しを実行します。完了すれば実行結果が一覧表示されます。複雑なAPI呼び出しも一度設定すれば何度でも実行できるので、とても便利です。

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