Photo on Business Wire

在文章還沒開始之前，小弟先附上 Postman 官方網站的傳送門。
有興趣或是覺得小弟寫得不清楚的，都可以再到官方網站來看看～
( ～'ω')～ <<< Postman 官方網站 >>> ～('ω'～ )

前言

在上週的 "鼠年全馬鐵人挑戰 WEEK 11：API 測試工具 - Insomnia" 文章中已經介紹過 Insomnia API 的測試工具了，而在這禮拜要介紹的是另一個 API 測試工具 "Postman"。

小弟以前都是用 Insomnia 來做 API 的測試，但是近期的某些需求在 Insomnia 無法達成，因此在同事的推薦下，我決定來了解一下 Postman 順便寫成筆記文章。所以如果內容有錯誤或不清楚的，也歡迎各位大哥大姐們提點。

介紹 Postman

Postman 在官方網站上就可以進行操作了，前提是要為登入的狀態。
如果想要直接在網頁上使用，可以參考連結：Postman Dashboard。
如果覺得在網頁操作太麻煩的話，安裝應用程式就可以在本機端直接操作了。
小弟在這篇的文章會以 Postman 的應用程式操作來做說明。

在免費使用的情況下 Postman 所提供的功能就很多了，多到我都覺得有點亂了。
但是最基本的功能一樣還是那些

• 清楚劃分的工作區。
• 快速的匯入與匯出。
• 便捷環境變數切換。
• 多型別的 http request。

上述的內容，在這週的文章小弟將一一寫成筆記，為大哥大姐們做介紹。

安裝 Postman

一開始當然是要先把 Postman 安裝下來啦～
Postman 適用於 Mac, Windows 和 Linux 作業系統。
那就廢話不多說，趕快到官方網站的下載處下載吧！
官方網站下載處: Download Postman

使用 Postman

• 開啟 Postman

  確認 Postamn 安裝成功後，就可以開啟 Postman。
  剛開啟 Postman 的時後樣子會長下面這張圖的樣子。
  那就讓我們一起開始進行接下來的奇幻旅程吧～
  

• 創建一個 HTTP Request

  1. 點擊左上角的 + New 按鈕，或是直接點擊 + 的頁籤。

     選擇 Create New 中，左上角的 Request。
     

  2. 填寫 Request 輸入框內容。

     

     1. 在 Request name 的欄位中填寫 request 的名字。 (必填)
     2. 在 Request description 的欄位中可以做一些詳細描述。 (選填)
     3. Search for a collection or folder 可以搜尋現有的資料夾。
     4. Create Folder 可以新增資料夾並把該 request 歸納於此。
     5. 當一切資料填妥後就可以按下 Save 的按鈕儲存了。

  3. 設置 http request 的 URL 並且送出執行。

     完成新增 http request 後，就可以在請求方式的旁邊填寫 URL。
     小弟這邊的範例將使用，六角學院大大釋出的馬拉松 API 資料。
     https://raw.githubusercontent.com/hexschool/w3hexschool-API/master/data.json
     

  4. 送出 request 並查看 request 的回傳訊息。

     點擊 URL 旁邊的 Send 按鈕，執行 request 請求。
     詳細的訊息會在下方的視窗中顯示。
     在這個區塊中可以得到的資訊有：

     狀態代碼 (200 OK)
     執行時間 (569 ms)
     內容大小 (47.05 KB)
     回傳內容 (Body, Cookies, Headers, Test Results)

     

  5. 篩選回傳回來的訊息。

     在 Postman 這點就沒有 Insomnia 快速且方便。
     首先，先點擊 request 工具列中的 Tests 頁籤。
     然後貼上下方連結中附上的程式碼。 (為了讓 filter 功能在 postman 可用)
     因為內容有點多所以我就寫到 Gist Github 了。 點我 "Code Link"
     

     接著就可以執行 request，然後等待回傳。
     資料回傳後點選最下面 Body 中的 Visualize 選項。
     最後就是輸入上次說過的篩選指令。
     小弟這邊的範例將使用，自己的名字來篩選出文章名稱。
     (因為小弟上週名字有更新過，所以篩選的名字跟上週不太一樣)
     $..[?(@.name=="謝昌諺 (Ron Hsieh)")].blogList[*].title
     

  看完以上內容的大哥大姐們。
  恭喜你，跟我一樣已經會使用 Postman 的基本功能了～
  接下來的內容將會進一步的介紹其他功能。

靈活運用 Postman

• 工作區 (Workspaces)

  當你有許多專案都會使用到 API。
  這個時候有效的分類工作區會是一個很好的選擇。

  1. 點選上方工作區的下拉式選單。

     點擊 Create New 來新增一個新的工作區。
     其中 Type 的選項可以選擇 Team 或是 Personal。
     如果選的是 team 的話，可以邀請其他成員共同編輯。
     (記得你邀請的夥伴也必須有使用 Postman 才會邀請成功喔～)

     

• 匯入/匯出資料 (Import/Export)

  不得不說，雖然功能差不多，但是我覺得還是 Insomnia 的比較好一點。
  因為在 Ibsomnia 中，會有個視窗讓你勾選要 export 的 request。
  這樣一來就不會把 workspace 中不想公開的資訊也 export 出來。
  但是既然 Postman 也有這個功能就來筆記一下好了。

  1. 進入 Postman 的 "設定" 專區。

     也可以使用快捷鍵 command/control + ,
     

  2. 進入 Settings 後，選擇 Data 的頁籤。

     進入該頁面後就可以依照自己的需求 import/export。
     

• 環境變數 (Manage Environments)

  在測試的時候經常會遇到一種情況。
  就是同一支 API 要打到不同的環境。
  但是 API 的內容並沒有差太多，只是 host 不同而已。
  環境較常會被分成：開發環境、測試環境、正式環境。
  所以為了解決重複創建類似的 http request。
  就可以透過 環境變數 的設計方式來達成。
  小弟這邊的範例會把 base_url 變數，用來儲存 URL 部分的資訊。

  1. 點選右上角 齒輪 icon 的 Manage Environments 按鈕。

     可以點擊下方的 Add 來新增一個 Environment 來管理。
     也可以點擊預設的直接使用 "My Workspace - globals"。
     或是是點擊 Add 旁邊的旁邊的 Globals，編輯全域變數。
     

  2. 定義環境變數，與變數值。

     出現編輯欄位後，在 Variable 填上變數名 與 Initial value 填上變數值。
     確認輸入完之後，就可以點擊右下角的 Update 完成編輯。
     

  3. 使用自行設定的環境變數。

     在使用的欄位先打上 {{}} 之後，在把環境變數的名字填入。
     如果未打完的話，會跳出對應的選項可以選擇。
     自行設定的環境變數，在選擇時通常是綠色帶有 E 的符號。
     

  4. 更進一步的使用環境變數。

     在第二步的編輯中
     使用相同的 key 但是不同的 value，存在不同的 environment 中。
     這樣一來就可以達到快速切換環境來使用變數了。

• Request 前的腳本 (Pre-request Script)

  有些時候在打 API 之前必須先做好一些處理。
  這也是小弟會使用 Postman 的最大原因之一。
  因為小弟這支 API 要處理的事情太多。

  body 要帶 timestamp，整包的 body 又要轉成 base64。
  header 的密鑰要帶 十六進位 的 SHA-384 的 密鑰。

  一支 API 需要做的事情真的是太多太複雜。 (小弟只是想抱怨)
  但是使用 Pre-request Script 的功能就可以輕鬆達成了。
  想要使用的話直接點擊 Pre-request Script，就可以撰寫了～
  

• 代碼產生器 (Generate Code)

  當 API 使用 Postman 完成進行後。
  想要把該 API 的內容應用到程式設計中。
  就可以透過此功能來快速生成所需的代碼。

  1. 點擊 "Code" 按鈕。 (在 Save 按鈕下方)

     

  2. 出現編輯器後就可以選擇程式語言。

     

結尾

因為上週已經介紹過了 Insomnia 的 API 測試工具。
所以這週的 Postman 工具在使用上都會與 Insomnia 做比對。
但是小弟個人認為還是 Insomnia 較為好用。
可能是因為小弟自己不習慣 Postman 的操作。
但是不得不說 Postman 的 Pre-request-Script 真的很好用。
如果 Insomnia 也有這個功能，我可能就沒機會使用 Postman 了。 ( σ՞ਊ ՞)σ
這週的內容其實跟上週一模一樣。 (抱歉，小弟太混了 ( ˊ•̥̥̥ω•̥̥̥ˋ ))
但基本上還是在介紹一些操作方式，希望讓第一次使用的人比較好上手。
如果有疑問或是有錯誤，還請各位大哥大姐提點。
小弟將繼續往下週邁進。 ─=≡Σ((( つ•̀ω•́)つ

參考文件:

Postman | The Collaboration Platform for API Development
GitHub: hexschool/w3hexschool-API