Postman APIを活用したPostmanデータCRUD処理の自動化

これはPostman Advent Calendar 2024の7日目の記事。本記事では、Postman APIの概要と、Postman APIを活用したPostmanデータのCRUD処理の自動化のサンプルを紹介します。

Postman APIとは？

Postmanアカウントで設定するPostmanのデータはPostmanクラウドに保存されます。

Postman APIとは、この自分のPostmanアカウントで設定するPostmanデータを管理・操作するためのAPIです。Postman APIを使用することで、このPostmanデータをプログラムで操作し、簡単に外部の開発ツールや自動化の処理に組み込むことができます。

Postman APIで管理可能なデータの種類や、データの種類ごとに実現可能な操作内容など詳細についてはPostman APIリファレンスを参照ください。

また、実際にPostman APIを試してみる際は、パブリックに公開されているPostman API用コレクションがあるので、それをフォークしてご自身のワークスペースでお試しいただくのが良いでしょう。

Postman API公式コレクション

クイックスタート

クイックスタートとしてPostman APIコレクションを自身のワークスペースにフォークしてPostman APIを試す方法を紹介します。ここではあるワークスペースにあるコレクション一覧を取得するAPIを題材に解説します。

1. Postman APIコレクションをフォーク

まずは、パブリックに公開されているPostman API用コレクションを、自分の作業用ワークスペースにフォークします。コレクションのフォークの仕方について詳しくは下記ページが参考になります。

2.Postman APIキーの取得

Postman API利用のためにはPostman API キーが必要です。次の流れでPostman APIキーの管理ページに遷移します。もしくは go.postman.co/settings/me/api-keys に直接アクセスしてもAPIキー管理ページに遷移できます。

「個人のアイコン (画面右上)」＞ 「設定 (Settings)」 ＞ 「API Keys」

Postmanキー管理ページで「Generate API Key」ボタンをクリックすることでAPIキーが生成されます。なお、APIキーの文字列は生成時にしか表示されないので、そのタイミングで必ずクリップボードなどにコピーしておいてください。

3. APIリクエストの設定・送信

上述のとおり、ここではワークスペースのコレクション一覧を取得するAPIを利用します。1でフォークしたコレクションのWorkspacesフォルダ配下の「Get a workspace」リクエストを選択します。

3-1. APIリクエストのAPIキー認可設定

選択したAPIリクエストにAPIキー認可設定をします。Postman APIのエンドポイントにリクエスト送信する際に、リクエストヘッダーにx-api-keyキーの値としてAPIキーをセットします。Postman アプリのUIでは、APIリクエスト設定の認可タブをクリックし、認可タイプにAPIキーを選択して下記項目を入力します。

• キー: x-api-key (全角半角関係なし)
• 値: 2️で取得したAPIキー文字列を入力
• 追加先: 「ヘッダー」を選択

なお、APIキーの文字列は秘匿情報に当たるので、直接上記の値入力エリアに記入するのではなく、環境変数もしくはPostman Vaultを活用するとよいでしょう。Postmanにおける秘匿情報の扱いについて、詳しくは下記ページにまとめてあります。

3-2. ワークスペースIDを取得

コレクション一覧取得対象のワークスペースを開き、「⋯」メニューをクリックして、「Workspace info」をクリックしてください。UUID形式のワークスペースIDが表示されます。例）7a652b7f-8a07-4078-a135-3d693361b27x

3-3. APIリクエスト送信

Postman APIコレクションのWorkspacesフォルダ配下の「Get a workspace」リクエストの{{workspaceId}} に3-2で取得したワークスペースIDをセットして次のようにリクエスト送信します。無事コレクション一覧が取得されることを確認してください。

[参考] curlで送信例

参考までに、curlコマンドでの送信方法を紹介します。次のようにワークスペースIDをパスパラメータにセットし、リクエストヘッダーにx-api-keyキーの値としてAPIキーをセットして送信します。

curl --location 'https://api.getpostman.com/workspaces/<workspaceId>' \
--header 'X-API-Key: <Postman-API-Key>'

Postman APIを活用したPostmanデータのCRUD処理例

ここでは、Postman APIを活用したPostmanデータのCRUD処理例を紹介します。

例1: Postman CLI経由で全てのコレクションのテストを実行

あるワークスペースにあるすべてのコレクションをPostman CLIで実行するサンプルです。

あるワークスペースにあるすべてのコレクションをPostman CLIで実行する方法

コレクション一覧取得にクイックスタートでも紹介した下記APIを利用しています。

• ワークスペース中の全てのコレクションを取得するAPI: GET - Get a workspace

例2: OpenAPIを元にしたコレクション作成・更新の自動化

OpenAPI Specファイルを元にPostmanのコレクションの作成・更新を自動化するサンプルです。

ここではコレクションの作成・更新にそれぞれ次のAPIを利用しています。

• コレクションの作成: Post - Create a collection
• コレクションの更新: PUT - Replace a collection's data

例3: モックサーバー作成

Postman API を使用してコレクションをモックする方法の実践的なデモンストレーションです。

ここではそれぞれ次のAPIを利用しています。

• コレクションIDの取得: GET - Get all collections
• 環境IDの取得: GEt - Get all environments
• モックサーバーの作成: POST - Create a mock server
• モックサーバーの取得: GET - Get all mock servers

コレクションIDと環境IDをPostman APIを活用して取得していますが、これらIDはモックサーバー作成時に利用します。

{
  "mock": {
    "name": "testAPImock",
    "collection": "<your-collection-id>",
    "environment": "<your-environment-id>"
  }
}

例4: モニター実行の自動化

Postman API を使用してモニターを実行する方法を解説してます。CI/CD、監視ダッシュボード、その他の使用するアプリなどのワークフローにモニターの実行を統合できるようになります。/monitorsエンドポイントを使用する方法と /webhooks エンドポイントを使用する２つの方法を紹介しています。

ここではmonitors、webhooksでそれぞれ次のAPIを利用しています。

• /monitorsエンドポイント
  • モニターの作成: POST - Create a monitor
  • モニターの実行: POST - Run a monitor
• /webhooks エンドポイント
  • Webhookを使用してコレクションの実行をトリガーの作成 (モニターが作成される): POST - Create a webhook

例5: 環境変数の初期値の更新

環境変数の初期値の更新方法を紹介する記事です。

Postman CLIやNewman経由のテスト実行においてテスト実行中に更新される変数の値は現在値(Current Value)です。現在値はローカルにしか保持されず、クラウドに保存されません。一方、Postman CLIやNewmanはテスト実行開始時に初期値(Initial Value)を参照します。したがって、その更新された変数値を次のPostman CLIやNewmanでのテスト実行時に参照するには初期値を更新する必要があります。そして、変数の初期値を変更するにはPostman APIの活用が必要となります。環境変数の初期値更新には次のenvironments APIを利用します。

• 環境変数の更新: PUT Update an environment

さいごに

今後良いサンプルを見つけ次第こちらに追加していきます。Stay tuned!