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」という環境変数を作成し、その値（CURRENT VALUE）に「Bearer SendGridのAPIキーの値」を入力しています。また、APIキーは機密情報であるため、TYPEはsecretにしています（入力値がマスク表示されます）。入力が完了したらSaveを選択して保存し、＋ボタンを選択してリクエスト生成画面を開きます。

それでは作成した環境変数を使用してみましょう。
画面右上で、使用する環境名（今回はTest Environment）を選択し、Authorizationタブで以下のように設定します。

Type：API Keyを選択
Key：「Authorization」を入力
Value：「{{apiKey}}」を入力

環境変数はこのように「{{ }}」で囲って使用します。

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

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

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

まず、GitHubのリポジトリからAPI定義ファイルをダウンロードします。今回はSwagger 2.0のJSONファイルをローカルに保存します（以下のページの内容をファイルとして保存）。
https://raw.githubusercontent.com/sendgrid/sendgrid-oai/main/oai.json

{
    "swagger": "2.0",
    "info": {
        "version": "",
        "title": "Email Activity (beta)",
        "description": "The Beta endpoints for the new Email Activity APIs - functionality is subject to change without notice. You may not have access to this Beta endpoint.\n\nEmail Activity offers filtering and search by event type for two days worth of data. There is an optional add-on to store 60 days worth of data. This add-on also gives you access to the ability to download a CSV of the 60 days worth of email event data. The Beta endpoints for the new Email Activity APIs - functionality is subject to change without notice. You may not have access to this Beta endpoint.\n\nEmail Activity offers filtering and search by event type for two days worth of data. There is an optional add-on to store 60 days worth of data. This add-on also gives you access to the ability to download a CSV of the 60 days worth of email event data."
    },
    "host": "api.sendgrid.com",
    "basePath": "/v3",
    "schemes": [
        "http"
    ], ……（略）

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

Choose Filesから、先ほどローカルに保存した定義ファイルをアップロードします。Import Elements画面でImportを選択し、その後Import completeと表示されたら取り込み成功です。
これだけで全APIの定義を一括でインポートでき、画面左のAPIsから一覧を確認できます。認証情報とAPIのリクエストパラメータの調整を行えばすぐに利用可能です。

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

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

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

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

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

次に、Batch ID生成エンドポイントのAPIリクエスト設定を作成します。Authorizationタブで認証情報の設定を行うのを忘れないでください。設定が完了したらTestsタブを選択します。TestsタブではAPIリクエスト後に実行するスクリプトを書くことができます。

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

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

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

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

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

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

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

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

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

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

検索

カテゴリ

アーカイブ

メールを成功の原動力に

開発者にもマーケターにも信頼されているメールサービスを利用して、
時間の節約、スケーラビリティ、メール配信に関する専門知識を手に入れましょう。