Postmanとはなにか？
Web開発をする時に、「こんなリクエストをした時にどんなレスポンスが返ってくるのかな？」
ということをサクッと確認するときに、どんなことをしていますか？
macやlinuxを使ってる人ならば、curlコマンドでAPIリクエストを直接叩いてみる、ということもあるかもしれませんが、Windowsの場合は少しやりづらいです。
そんな時にとても便利なのがPostmanというツールで、GUIで直感的にさまざまなリクエストを発行することができ、再利用や他の人との共有も簡単にできます。
また、モックサーバーも手軽に作ることができるので、ちょっとした検証にも活用できるかもしれません。
インストール
上記サイトからダウンロードし、インストールしてください。
起動した後、ユーザー登録をして利用を開始します。
使い方
任意のリクエストを登録
例えばJSONPlaceholderのAPIを使って取得をしてみましょう
このようにお手軽に任意のクエリを発行することができます。
認証付きのAPIを使ってみましょう
弊社では、Microsoft GraphAPIを使ったプロダクトを開発しており、GraphAPIの認証にはOAuth2.0のクライアントクレデンシャルフローを使うことができます。
そこで、GraphAPIの認証をPostmanで行い、認証後にユーザー一覧を取得するリクエストを実行してみます。
今回の題材としては ユーザーを一覧表示する を実行してみます。
まずリクエストに使う変数をVault内に定義します
GraphAPIを使うためのトークンを取得するにあたって、Azure ADに登録したアプリケーションのclient_idとclient_secretが必要です。
client_idやclient_secretは機密データになりますので、通常の環境変数ではなく安全に保存できるVault内に保持していきましょう。
「Ctrl + Shift + V」または、Postmanの画面右下の「Vault」をクリックしてVaultを開きます。
次にログインに利用する情報を入力していきます。
値の利用を許可するドメインを制限することもできるので、セキュリティを考慮して設定していきましょう。
次にリクエストをまとめるためのコレクションを作成します
新規 → コレクションでGraphAPI用のコレクションを作成します。
コレクションはリクエストをまとめるためのもので、リクエストをグループ化して管理することができます。
BotのクレデンシャルでGraphAPIにログイン
それでは早速Botを使ってログインしていきます。
GET
https://login.microsoftonline.com/<EntraテナントID>/oauth2/v2.0/token
Body:
x-www-form-urlencoded
| Key | Value |
|---|---|
| client_id | {{vault:client_id}} |
| scope | https://graph.microsoft.com/.default |
| grant_type | client_credentials |
| client_secret | {{vault:client_secret}} |
これでレスポンスとして以下が返ります。
{
"token_type": "Bearer",
"expires_in": 3599,
"ext_expires_in": 3599,
"access_token": "eyJ0eXA...(中略)...tT1g"
}
取得したaccess_tokenを使ってユーザー取得APIを実行
GET
https://graph.microsoft.com/v1.0/users
認可
Auth Type: Bearer <先ほど取得したaccess_token>
トークン: Bearer eyJ0eXA...(中略)...tT1g
ヘッダー
| Key | Value |
|---|---|
| ConsistencyLevel | eventual |
Authorizationヘッダーには Bearer <先ほど取得したaccess_token> という感じで指定します。
ConsistencyLevelはGraphAPIの種類やクエリのパラメータによって必要だったり必要なかったりします。
今回は上記URLに以下のように書いてあるので、指定していきます。
クエリの中には、ConsistencyLevel ヘッダーの設定を
eventualおよび$countに使用した場合にのみサポートされるものもあります。 詳細については、「ディレクトリ オブジェクトの詳細クエリ機能」を参照してください。
Paramsは特に指定せずに実行してみますと、テナント内のユーザー一覧が取得できます。
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users",
"@odata.nextLink": "https://graph.microsoft.com/v1.0/users?$skiptoken=RFNw...(略)...AAA",
"value": [
{
"businessPhones": [],
"displayName": "テスト ユーザー",
"givenName": "テスト",
"jobTitle": "",
"mail": null,
"mobilePhone": null,
"officeLocation": null,
"preferredLanguage": null,
"surname": "ユーザー",
"userPrincipalName": "test@communitio.net",
"id": "e2612ff4-ccb5-4c42-adc6-f34ee90421b0"
},
//...(以下略)
]
}
開発用に複数のEntraテナントを使うことがあり、access_tokenは各テナントにログインするごとに毎回入れ替える必要があるため、都度コピー＆ペーストをしているとやや面倒です。
そこで、スクリプトを利用して変数に格納してVault経由で渡していくと便利です。
先ほど「BotのクレデンシャルでGraphAPIにログイン」で作ったリクエストの「スクリプト」の「Post-res」に以下のスクリプトを記述します。
// レスポンスボディからトークンを抽出（例：JSONのaccess_tokenプロパティ）
const jsonData = pm.response.json();
const accessToken = jsonData.access_token;
// Vaultにトークンを保存
pm.vault.set("access_token", accessToken)
これで、ログインした時のレスポンスに含まれる access_token がVault内の access_token に格納されます。
では次に利用側として、「取得したaccess_tokenを使ってユーザー取得APIを実行」のリクエストの認可タブから「 {{vault:access_token}} 」を指定してリクエストを実行してみます。
結果は変わらず、正しく実行できました。
このような流れで、Postmanを使って認証付きのAPIを簡単に実行することができます。
是非みなさんもPostmanで普段の開発をすこし便利にしてみてください！
Discussion