Postman 如何使用 HMAC 以 TDX API 為例

前言

由於近期 The F2E 第三屆準備開跑了,那身為前端工程師最常用的 Postman 就會很常被拿來試戳 API,所以就紀錄一下如何使用 Postman 戳 TDX API。

TDX API 官方範例

基本上 TDX API 官方有提供許多的範例,舉凡 Python、Node.js、JavaScript 到 Golang 都有。

TDX API 官方範例

那麼 Postman 畢竟是前端很常用的工具,所以這邊就讓我們直接 JavaScript 的範例程式碼:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
$(function () {
$.ajax({
type: 'GET',
url: 'https://ptx.transportdata.tw/MOTC/v2/Rail/TRA/Station?$top=10&$format=JSON', //欲呼叫之API網址(此範例為台鐵車站資料)
dataType: 'json',
headers: GetAuthorizationHeader(),
success: function (Data) {
$('body').text(JSON.stringify(Data));
}
});
});

function GetAuthorizationHeader() {
var AppID = 'FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF';
var AppKey = 'FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF';

var GMTString = new Date().toGMTString();
var ShaObj = new jsSHA('SHA-1', 'TEXT');
ShaObj.setHMACKey(AppKey, 'TEXT');
ShaObj.update('x-date: ' + GMTString);
var HMAC = ShaObj.getHMAC('B64');
var Authorization = 'hmac username=\"' + AppID + '\", algorithm=\"hmac-sha1\", headers=\"x-date\", signature=\"' + HMAC + '\"';

return { 'Authorization': Authorization, 'X-Date': GMTString /*,'Accept-Encoding': 'gzip'*/}; //如果要將js運行在伺服器,可額外加入 'Accept-Encoding': 'gzip',要求壓縮以減少網路傳輸資料量
}

那麼如果要在 Postman 上試戳 API 的話該怎麼做呢?繼續往下看

Postman

首先 TDX API 需要身份認證,因此會採用 HMAC 方式認證,我們可以在上方程式碼看到這一段:

1
2
3
var Authorization = 'hmac username=\"' + AppID + '\", algorithm=\"hmac-sha1\", headers=\"x-date\", signature=\"' + HMAC + '\"';

return { 'Authorization': Authorization, 'X-Date': GMTString };

而這兩段就是關鍵處,首先將打開 Postman,然後填入要測試的 API Url,這邊以參考範例的為主:

1
https://ptx.transportdata.tw/MOTC/v2/Rail/TRA/Station?$top=10&$format=JSON

API Url

Headers

接下來切換到 Headers 頁籤,然後新增兩個屬性分別是:

  • Authorization
  • X-Date

Headers

然後依照個別填入以下內容

Authorization

1
hmac username="{{AppID}}", algorithm="hmac-sha1", headers="x-date", signature="{{hmac}}"

X-Date

1
{{GMTString}}

以上都填寫完畢後就要來做一個很特別的設定,也就是我們要寫 script。

Pre-request Script

那麼由於範例程式碼使用的是 jsSHA 套件,而 Postman 本身是沒有這個套件,所以這邊就必須自己撰寫一些程式碼來引入 jsSHA 套件,而 Postman 是允許你可以寫一些自己的程式碼,所以這邊我們會使用 jsSHA 的 CDN:

1
https://cdnjs.cloudflare.com/ajax/libs/jsSHA/3.2.0/sha.js

接下來 Postman 中有一個方法是可以在發送出請求前先執行裡面的程式碼,執行完畢後才真的送出 AJAX,也就是 pm.sendRequest,引入之後要在 res 中使用立即函式執行取回來的 CDN 檔案,這樣才可以正常使用,所以依據範例程式碼調整後結果就會變成以下:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
pm.sendRequest('https://cdnjs.cloudflare.com/ajax/libs/jsSHA/3.2.0/sha.js', (err, res) => {
(new Function(res.text()))();

var AppID = 'FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF';
var AppKey = 'FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF';

var GMTString = new Date().toGMTString();
var ShaObj = new jsSHA('SHA-1', 'TEXT');
ShaObj.setHMACKey(AppKey, 'TEXT');
ShaObj.update('x-date: ' + GMTString);
var HMAC = ShaObj.getHMAC('B64');

// 設定 Postman 全域變數
pm.globals.set("AppID", AppID);
pm.globals.set("HMAC", HMAC);
pm.globals.set("GMTString", GMTString);
});

而後面的三者 pm.globals.set 將會自動設定成 Postman 的全域變數,並且會自動帶入到剛剛設定的 AuthorizationX-Date 屬性中,這樣子就可以輕鬆試戳 TDX API 囉~

參考文獻

Liker 讚賞 (拍手)

如果這一篇筆記文章對你有幫助,希望可以求點支持或 牡蠣 鼓勵 (ノД`)・゜・。

Liker 是一個按讚(拍手)的讚賞機制,每一篇文章最多可以按五下(拍手),按讚過程你是完全不用付費的(除非你想要每個月贊助我 :D),你只需要登入帳號就可以開始按讚。
而 Liker 會依據按讚數量分配獎金給創作者,所以如果你願意按個讚我會非常感謝你唷。

Google AD

撰寫一篇文章其實真的很花時間,如果你願意「關閉 Adblock (廣告阻擋器)」來支持我的話,我會非常感謝你 ヽ(・∀・)ノ