初めてPostmanを使ってみた記録

Postmanをインストールする

qiita.com

リクエストを整理するためのCollectionsを作成する

これからPostmanを使っていくといろんなリクエストを作ることになります。そんなたくさんのリクエストを整理するためのフォルダのようなものがCollectionです。

Postman's collection folders make it easy to keep your API requests and elements organized.

Postman Collections: Organize API Development and Testing

  1. [Cllections] > [+New Collection] > [Name]にAPIがわかるような名前を指定 > [Create]ボタンでCollectionを作成する
  2. 作成したCollectionの右にある[...] > [Add Folder] > [Name]にローカル環境がわかるような名前を指定 > [Create]ボタンでフォルダを作成する
    • f:id:ponsuke_tarou:20210119183924p:plain

f:id:ponsuke_tarou:20210124170932j:plain
栃木県下都賀郡壬生町のストロベリーガーデンロイヤルからお取り寄せ、1パック2400円なだけあって激ウマ!

Collectionsにリクエストを追加する

  • 環境
    • Windows10 Pro バージョン1909
    • Postmat v7.36.1

APIにつなぐには認証が必要です。認証に何を使うかAPIによって異なります。初めてのリクエストのサンプルとして、認証してトークンを取得します。

  1. 作成したフォルダの右にある[...] > [Add Request] > [Name]にやることがわかるような名前を指定 > [Save to {フォルダ名}]ボタンで作成する
    • f:id:ponsuke_tarou:20210119184456p:plain
  2. f:id:ponsuke_tarou:20210119185709p:plain
    HTTPメソッドで「POST」を選択 > APIトークンを取得するエンドポイントを入力する
  3. APIに合わせて[Parameters]や[Headers]を設定する
  4. [Send]ボタンでリクエストをおくると[Body]にレスポンスが表示される

環境変数を作成する

APIのURLやらユーザ名やらリクエストにはよく使うものがあります。そんなものは環境変数にして便利に使えるようにします。

  1. f:id:ponsuke_tarou:20210120132904p:plain
    画面右上のマークから環境設定ダイアログを表示する
  2. f:id:ponsuke_tarou:20210120132921p:plain
    [Add]ボタンから環境変数セットを追加できる
  3. f:id:ponsuke_tarou:20210120133303p:plain
    環境変数セットの名前と変数名と値を設定して[Add]ボタンで追加
  4. f:id:ponsuke_tarou:20210120133450p:plain
    環境変数セットの一覧が表示される
  5. f:id:ponsuke_tarou:20210120133902p:plain
    画面右上のプルダウンから作成した環境変数セットの名前を選択する
  6. URLやパラメータの値などで{{変数名}}の形式で記載すると設定した値が利用される
    • f:id:ponsuke_tarou:20210120134246p:plain
      変数名を途中まで入力すると候補が表示されるので便利

なお、INITIAL VALUE と CURRENT VALUE の違いですが、Postman のサーバに情報が送られるか否かになります。

チームでテストしていたり、複数台の PC でテストするときは INITIAL VALUE を使うと便利なのかもしれません。 ですが、検証用 PC は 1台しかないですし、私はボッチですしおすし。(・ω・) セキュリティを高めるためにもっ!CURRENT VALUE を使っています!!! セキュリティを高めるためだからねっ!(大事なことは二度言うスタイル)

Postman の環境変数を設定する - Qiita

任意のCllection専用に環境変数を設定できます。

Postman は変数を使うことができます。変数には Global/Collection/Environment 変数があり、Global は Postman 全体で利用できる変数。Collection は Collection レベルで参照できる変数。Environment は各 Environment(タブ)で利用できる変数です。

RESTサービスを触る際の必須ツールPostmanを使ってみました | エクセルソフト ブログ

  1. 作成したCollectionの右にある[...] > [Edit]でCollectionの設定ダイアログを開く
  2. [Variables]タブでCollection専用の環境変数を設定する
    • f:id:ponsuke_tarou:20210124153213p:plain
      接続する環境(サーバとかローカルとか)やAPI毎にCollectionを作っておくと接続先のURLを環境変数に入れて使えて便利です。

認証情報をリクエストにくっつける

APIにつなぐときに毎回認証情報が必要となることはよくあります。その認証情報をリクエストに自動でくっつけられるようにします。

リクエスト単位で認証を設定することもできますが、API単位でCollectionを作って、API単位で設定することもできます。どちらも[Authorization]タブで設定します。

ヘッダーにBearerトークンをくっつける

先ほどのように取得したトークンをリクエストに設定して認証できるようにします。

Postman を複数環境で使う場合にアクセストークン取得方法を簡略化する | Developers.IOを参考に設定していきます。

  1. トークンを取得した時と同じようにリクエストを追加する
  2. [Authorization]タブで設定する
  3. f:id:ponsuke_tarou:20210120135855p:plain
    [Type]ではトークンを取得する認証方法を選択する
  4. f:id:ponsuke_tarou:20210120142349p:plain
    トークンを取得するのに必要な情報やトークンを設定するヘッダ情報などを入力する
  5. f:id:ponsuke_tarou:20210120142534p:plain
    [Get New Access Token]ボタンでトークンを取得して[Proceed]ボタンで進む
  6. f:id:ponsuke_tarou:20210120142635p:plain
    [Use Token]ボタンでリクエストの設定に反映する
  7. f:id:ponsuke_tarou:20210120142712p:plain
    取得したトークンが[Access Token]に反映される

Bearerトークンを直接設定することもできるようですが、トークンの期限切れとなった時に手動で再設定するのは面倒くさいのでOAuth2.0で設定しました。

f:id:ponsuke_tarou:20210219120207p:plain
[Type]で「Bearer Token」を選択すれば直接トークンを設定できるようです

リクエスト単位ではなくCollection単位で認証を設定した場合は、各リクエストの[Authorization]タブの[Type]には「Inherit auth from parent」を設定します。

パラメータにAPIキーをくっつける

  • 環境
    • macOS BigSurバージョン11.1
    • Postman for Mac Version 8.0.5

認証情報によってはパラメータにくっつけることもあります。

例えば政府統計の総合窓口(e-Stat)APIではアプリケーションIDをappIdリクエストパラメータに毎回指定する必要があります。

APIを利用するには、アプリケーションIDを必ず指定する必要があります。利用登録を行い、アプリケーションIDを取得して下さい。

政府統計の総合窓口(e-Stat)のAPI 仕様 3.0版 | 政府統計の総合窓口(e-Stat)−API機能

Collection共通の認証設定としてe-StatのAPIへのリクエストにアプリケーションIDをくっつけます。

  1. f:id:ponsuke_tarou:20210212063720p:plain
    Collectionを選択して設定を開く
  2. f:id:ponsuke_tarou:20210212064124p:plain
    [Variables]で環境変数にアプリケーションIDを設定する
  3. f:id:ponsuke_tarou:20210212065832p:plain
    [Authorization]で[Type]に「API Key」を選択する
  4. 以下を設定して保存する
    • Key : appId(アプリケーションID用のパラメータ名)
    • Value : {{appId}}(設定した環境変数名)
    • Add to : Query Params
  5. f:id:ponsuke_tarou:20210212071023p:plain
    このCollectionのリクエストには自動でアプリケーションIDが設定されるようになった

f:id:ponsuke_tarou:20210124170009j:plain
板橋区の竹の湯

リクエストをAPIにおくる

ここまでで覚えたことを使っていろんなAPIを使ってみます。

パスパラメータを指定する

  • 環境 : macOS BigSurバージョン11.1 / Postman for Mac Version 8.0.5

ここではBacklogAPIのプロジェクトの状態一覧の取得 | Backlog Developer API | Nulabをやってみます。

パスパラメータはAPIのエンドポイントのパスに設定されるパラメータです。

URL /api/v2/projects/:projectIdOrKey/statuses

プロジェクトの状態一覧の取得 | Backlog Developer API | Nulab

「プロジェクトの状態一覧の取得」の場合はprojectIdOrKeyがパスパラメータになります。

Parameter Name Type Description
projectIdOrKey String Project ID or Project Key
  1. (事前準備)使っているBacklogでAPIキーを発行する
  2. Postmanを起動する
  3. Backlog用にCollectionsを作成する
    1. 環境変数を設定する
    2. API Key方式の認証を設定する(Backlogには他にも認証方法はあります。参考 : 認証と認可 | Backlog Developer API | Nulab)
      • TYPE : API Key
      • Key : apiKey
      • Value : {{API_KEY}}
      • Add to : Query Params
  4. URLとして{{URL}}/projects/:projectIdOrKey/statusesを入力するとパスパラメータの入力欄が表示される
    • f:id:ponsuke_tarou:20210219092258p:plain
  5. パスパラメータに取得したいプロジェクトIDを指定する
  6. [Send]ボタンでプロジェクトの状態一覧の取得 | Backlog Developer API | Nulabの「レスポンスボディ」みたいなのが取れるか確認する

配列形式のクエリパラメータを設定する

  • 環境 : macOS BigSurバージョン11.1 / Postman for Mac Version 8.0.5

Backlog APIを使って課題一覧の取得 | Backlog Developer API | Nulabをやってみます。

パラメータで配列を指定することがあります。例えばプロジェクトIDの配列する場合にはパラメータ名がprojectIdではなくprojectId[]となり[]がくっ付きます。

今回使ってみる「課題一覧の取得」ではクエリパラメータのに配列を指定します。

以下は「課題一覧の取得」クエリパラメータの一部です(出典 : 課題一覧の取得 | Backlog Developer API | Nulab)。[]がついているのが配列で、[]がついてないのが配列でないものです。

パラメーター名 内容
projectId[] 数値 プロジェクトのID
issueTypeId[] 数値 種別のID
...省略... ...省略... ...省略...
keyword 文字列 検索キーワード
  1. 使っているBacklogでAPIキーを発行する
  2. Postmanを起動し、Backlog用にCollectionsを作成して環境変数や認証情報を設定する
  3. 「課題一覧の取得」用のGETリクエストをCollectionに作成する
    • f:id:ponsuke_tarou:20210219083548p:plain
      URLは「{{URL}}/issues」にするだけでOK
  4. Query Paramsの[KEY]にprojectId[]を、[VALUE]に1つ目のプロジェクトIDを入力する
  5. 次の行に[KEY]にprojectId[]を、[VALUE]に2つ目のプロジェクトIDを入力する
    • f:id:ponsuke_tarou:20210219223307p:plain
  6. 他のクエリパラメータを設定する
  7. [Send]ボタンで課題一覧の取得 | Backlog Developer API | Nulabの「レスポンスボディ」みたいなのが取れるか確認する

 

セッションを設定する(ここは結果としてうまくいきませんでした、またいつか挑戦したいです。)

呼び出すAPIによっては、画面でログインしてそのセッションを設定て呼び出さねばならないことがあります。そんなときのやり方をやってみました。

Postman InterceptorをChromeに追加する

4. Interceptor(https://www.getpostman.com/docs/capture

Interceptor機能はChromeを利用して、ブラウザ内で発生したリクエストを自動でPostman Historyに登録する機能です。

Postman概要/インストール/使用方法 | TOAST Meetup

  1. Postman Interceptor - Chrome ウェブストアを表示する
  2. f:id:ponsuke_tarou:20210121120415p:plain
    [Chromeに追加]ボタンを押下
  3. f:id:ponsuke_tarou:20210121120552p:plain
    [拡張機能を追加]ボタンで追加する
  4. f:id:ponsuke_tarou:20210121120759p:plain
    拡張機能として追加される
  5. ピンマークを押下するChromeツールバーにアイコンが表示される
    • f:id:ponsuke_tarou:20210121143152p:plain

PostmanでリクエストとCookieをキャプチャする

  1. 右上にある衛星アイコンでダイアログを表示 > [Cokies] > [Install Interceptor Bridge]でInterceptor Bridgeをインストールする
    • f:id:ponsuke_tarou:20210121143944p:plain
  2. [Request] > [Source] > 「Interceptor」選択 > [Capture Requests] > ON > [Save Requests to] > 設定対象にしたいCollectionなどを設定
    • f:id:ponsuke_tarou:20210121144425p:plain
  3. [Cokies] > [Capture cookies] > ON > [Domains] > 対象のドメインを入力 > [Add Domain]ボタンで追加
    • f:id:ponsuke_tarou:20210121152016p:plain
  4. f:id:ponsuke_tarou:20210121152314p:plain
    Postmanで設定したらChromeのPostman Interceptorアイコンが連動して青くなる

https://assets.postman.com/postman-docs/Interceptor-ex1.gif Using Postman Interceptor | Postman Learning Center

画面からログインしてリクエストを送る

  1. 画面からログインする
  2. Postmanでリクエストを送る > APIには到達したが、うまくセッションを取得できず・・・

f:id:ponsuke_tarou:20210124170428j:plain
板橋区仲宿にある「かさま」