Web 技術

Postman 教學｜使用 API 測試工具開發

發佈日期: 作者:

大家都說 Postman 是測試 API 必備神器，必備到就像 ＷiFi 跟你一樣的關係，沒有他會覺得斷手斷腳，跟個廢人一樣。只是對於新手一來說，一打開好多按鈕，好多專有名詞，真的是深深體會到自己多菜，不怕！，服用本篇新手教學，幫你入門，開電扇趕走菜味．

本篇是給 Postman 新手入門使用，讓你在 10 分鐘快速上手基本 Postman 用法，從基本 GET API ，到需要驗證的 POST API，其中會一起補充一些基本觀念，包含請求四大方法(Create/Read/Update/Delete)，Header 參數簡介，最後 Bonus，使用 Postman 上傳/下載檔案．貼心讓你不用一直點分頁去 Google。

安裝 Postman

請你到 Postman 的官方網站下載應用程式：https://www.getpostman.com/downloads/

安裝好之後打開軟體，會看到以下的操作介面：

postman 操作介面

Postman 導覽：主要操作版面

一開始使用，我們只需要專注在版面右側的 Request 頁籤版面，你可以透過兩個方式看到Request 頁籤

‍

  1. 左上角的 [＋New] 跳出的選單，新增一個新的 Request 頁籤
  2. 直接在點選現有 Request 頁籤 旁的 [＋] 新增，就像平常新增 google 分頁一樣

Request 頁籤，可以大略分成三個區塊，分別是 網址區塊，參數區塊，回應區塊，每個區塊需要關注哪些部分，又各自代表什麼意義，可以參考各區塊的解說

  • 網址區塊，選擇 API 的方法、請求路徑 URL
  • 參數區塊，詳細設定 API 三大部分參數（ 網址 / Header / Body）
  • 回應區塊，檢視 API 回應的資料、回應的資訊

第一部分：網址區塊介紹

區塊簡介

為了方便理解，你可以先把接收 API 的 Server  當作是替你服務的小助理，負責代替你做各種任務，在這裡個區塊，你需要設定請求方法、請求網址，完成後，點選右側 [Send] 送出

Method 請求方法 | 小助理替你服務的類型，常見有四個

  • GET，取得 (GET) 資料
  • POST，新增 (Create) 資料
  • PUT，更新 (Update) 資料
  • DELETE，刪除 (Delete) 資料

URL 請求網址 | 小助理要到哪裡執行你交辦的任務

第二部分：參數區介紹

區塊簡介

我們會在請求三個地方，附加特定資訊，提供請求的細部設定，分別是 URL 網址、Header、Body

  • URL 網址，通常關於取得資料的篩選，都會放在這裡，可以加上兩種參數，Query Params 搜尋參數，Path Variables 路徑變數，搭配使用，做資料的篩選整理，特別注意不可以把密碼等敏感資訊放在網址
  • Header 部分，通常關於 API 請求的標示，都會存放在這裡，例如需要身份驗證的請求，會把驗證身份的token 以 Key-Value 存在 Header (ex. Authorization: token)
  • Body 部分，通常 API 需要提交給 Server 的資料，都會放在這裡（ex.註冊表單 name: 小明, password:1234）

Params 網址參數頁 ｜ (設定 Query Params 搜尋參數 Path Variables 路徑變數 )

  • 預設只有  Query Params 搜尋參數，Path Variable 路徑變數，需要自行在網址上打上冒號＋變數名 (ex.  ” : name ” )，才會出現
  • 設定方式都是採 Key – value ，可以根據情況彈性勾選

Authorization 驗證設定頁 ｜用來設定 Header 中的 Authorization 參數

常用驗證類型

  • No Auth | 不需要驗證
  • Basic Auth ｜帳號，密碼型驗證
  • token 驗證 ｜token 型驗證

Header 頁｜用來設定 Header 中的其他參數

Postman 把一些必要參數隱藏起來，如果需要特別設定，可以取消隱藏，進行修改

另外 Authorization 雖然沒有在這裡出現，不過 Authorization 驗證設定頁若有指定，還是會一起送出請求

常見參數

  • User-Agent | 告知 Server，發出 Request 的 Client 瀏覽器、作業系統等資訊 ｜doc
  • Accept ｜告知 Server，Client 可以解讀的內容類型 | doc
  • Content-type | 告知 Server，Client 提交什麼類型內容 ｜doc

Body 頁

比較常用的是 form-data 、x-www-form-urlencoded、raw，前兩者都是送出表單資料，最後一個提供較多彈性的資料格式，目前大部分都是使用 Json 只需要選擇 x-www-form-urlencoded 就可以了

  • form-data vs. x-www-form-urlencoded 有什麼不一樣呢？

‍

  • form-data 不會針對內容，進行編碼，x-www-form-urlencoded  會以 Key1 = val1 進行編碼
  • 需要上傳檔案，用 form-data，選擇 file 類型，一般的表單資料用 x-www-form-urlencoded

postman json 資料要放哪裡？

選擇 raw 選項，並且在右側下拉選單，選擇 JSON 格式

第三部分：回應區介紹

區塊簡介

  • 成功接收到回應後，下方回應區塊就會有內容提供你參考，Postman 很貼心幫忙把回應資料分門別類，大部分情況只會檢視 Body 資料，如果有特別的需求，可以檢視 Cookie 和 Header ，是否有被加東西，另外開發時會特別關注版面右上的 回應資訊，例如狀態碼、回應時間、回應大小

回應資訊欄

Status code 狀態碼 ｜表示 API 回應狀況，常見如下

  • 200 | 成功取得回應
  • 400 | 請求參數錯誤 (檢查輸入的參數，是否符合 API 規定）
  • 401 | 未認證 (未登入認證，但請求需要登入的 API）
  • 404 | 請求的資源不存在 （新手常見是，URL 打錯，再檢查看看吧）
  • 500 | 內部 Server 出錯 （不關你的事，可能是 Server 掛掉了）

Time 回應時間 ｜注重效能會特別查看這一塊，單位是 ms 微秒

架設 web API 伺服器或串接後端 API，3 分鐘小測驗取得學習建議

Q&A 問答時間

Q：Postman 可以處理需要，上傳檔案的 API 嗎？(ex.  Postman upload  image.jpg )

Ａ：可以的，設定步驟如下

  1. 確認你的提交方法為 POST
  2. 在 Body 分頁，選擇 form-data 格式，選擇 Key 類型是 file，填入 Key 名稱，點選 “Select Files” 上傳檔案
  3. 在 Header 分頁，KEY 欄位 Content-Type ，Value 欄位更改為 multipart/form-data ;（當你在成功上傳檔案，Postman 會自動幫你，完成步驟 3 ）

Q：乘上，那下載檔案的 API 呢？(ex. Postman download user.csv )

A：答｜可以的，設定步驟如下

  • 完成所有 API 設定後，提交按鈕，選擇下拉箭頭，點選“send and Download”(這個選項，如果 api 返回需要下載的檔案，會自動幫你下載儲存)

以上就是給新手的 Postman 基本操作使用介紹，如果想要有更深入的瞭解和操作，歡迎參考 ALPHA Camp 的課程 全端工程師養成：實戰學習架設 Web API 伺服器

（本文作者是 ALPHA Camp 的助教，後端工程師 Water）