Postman 如何使用 HMAC 以 TDX API 為例

前言

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

TDX API 官方範例

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

TDX API 官方範例

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

$(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 方式認證，我們可以在上方程式碼看到這一段：

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

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

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

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

Headers

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

• Authorization
• X-Date

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

Authorization

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

X-Date

{{GMTString}}

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

Pre-request Script

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

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

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

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 的全域變數，並且會自動帶入到剛剛設定的 Authorization 與 X-Date 屬性中，這樣子就可以輕鬆試戳 TDX API 囉~

參考文獻

• Adding external libraries to postman
• Postman pm.sendRequest example