處理 API 簽名

進階功能

處理 API 簽名 是一項 進階功能，需要 JavaScript 知識並理解加密概念。大多數 API 使用較簡單的驗證方法，如 Bearer Token。如果您剛開始接觸 API，可以跳過本文。

某些 API 需要 簽名驗證 以確保請求的完整性和真實性。API 簽名是從請求參數使用密鑰生成的加密雜湊。伺服器驗證簽名以確保請求未被篡改且來自授權來源。

在本文中，我們將學習如何使用 前置處理器腳本 和 公共腳本 在 Apidog 中處理 API 簽名，以自動生成並將簽名新增到您的請求中。

1. 什麼是 API 簽名？

API 簽名 是從您的請求參數和密鑰生成的密碼學數值。它的用途包括：

完整性驗證：確保請求在傳輸過程中未被修改

驗證：證明請求來自授權來源

安全性：防止請求篡改和重放攻擊

簽名如何運作

典型的簽名生成過程：

收集參數：收集所有請求參數（查詢參數、Body 參數等）

排序和連接：按名稱對參數進行排序，並以特定格式連接它們

新增密鑰：將您的密鑰與加密演算法（如 HMAC-SHA256）一起使用

生成雜湊：從連接的字串生成簽名雜湊

新增到請求：將簽名包含在請求標頭中或作為參數

伺服器執行相同的計算並比較結果。如果它們匹配，則請求有效。

2. 為什麼使用腳本進行簽名？

為每個請求手動計算和新增簽名會：

耗時：您需要為每個請求重新計算

容易出錯：計算中容易出錯

不靈活：如果簽名演算法更改，很難更新

Apidog 允許您使用 前置處理器腳本 自動化此過程，該腳本在發送每個請求之前運行。您可以建立一個實現簽名邏輯的 公共腳本，並在多個端點重複使用它。

3. 真實範例：HMAC-SHA256 簽名

許多現實世界的 API 使用 HMAC-SHA256 (Hash-based Message Authentication Code with SHA-256) 進行簽名驗證。這是 Stripe（用於 webhook）、GitHub（用於 webhook 簽名）和許多雲端服務提供商使用的廣泛採用的標準。

HMAC-SHA256 如何運作

HMAC-SHA256 簽名演算法遵循以下步驟：

收集參數：收集所有請求參數（查詢參數、Body 參數、時間戳等）

排序參數：按字母順序（ASCII 順序）對參數名稱進行排序

構建簽名串：以 key=value 格式連接參數，並使用 & 連接

新增時間戳：包含時間戳以防止重放攻擊

生成 HMAC：使用 HMAC-SHA256 演算法和您的密鑰生成簽名

新增到請求：將簽名包含在請求標頭中或作為參數

範例計算

假設我們有一個帶有以下參數的請求：

action: create

resource: pet

timestamp: 1633046400

api_key: your_api_key_12345

步驟 1：按字母順序排序參數：action, api_key, resource, timestamp

步驟 2：構建簽名串：action=create&api_key=your_api_key_12345&resource=pet&timestamp=1633046400

步驟 3：使用密鑰 your_secret_key 生成 HMAC-SHA256：

HMAC-SHA256("action=create&api_key=your_api_key_12345&resource=pet&timestamp=1633046400", "your_secret_key")

步驟 4：將簽名作為查詢參數或在 Authorization 標頭中新增到請求中。

4. 逐步指南

現在讓我們在 Apidog 中實作簽名生成。我們將建立一個自動生成並將簽名新增到您的請求中的公共腳本。

步驟 1：設定環境變數

首先，我們需要安全地儲存密鑰：

打開 Environment Management（點擊右上角的 ≡ 圖示）。

選擇您的環境（例如 "Production" 或 "Sandbox"）。

新增變數：

Variable Name: SECRET_KEY

Initial Value:（留空或使用佔位符）

Current Value: 您的 API 密鑰（由 API 提供商提供）

點擊 "Save"。

安全注意事項：

永遠不要在您的腳本或 API 規範中硬編碼密鑰。

將敏感密鑰儲存在 Current Value 中，而不是 Initial Value 中，因為 Current Value 不會在團隊成員之間同步，且更安全。

始終使用環境變數來儲存敏感資訊，如 API Key 和密鑰。

步驟 2：建立公共腳本

現在讓我們建立一個可重複使用的公共腳本來生成 HMAC-SHA256 簽名：

在 Apidog 中，前往 Settings → Public Scripts。

點擊 "New Public Script" 或 "+" 按鈕。

為您的腳本輸入名稱（例如 "HMAC-SHA256 Signature Generator"）。

輸入簽名生成程式碼：

點擊 "Save" 儲存公共腳本。

步驟 3：在端點中引用公共腳本

現在我們已建立公共腳本，我們需要在需要簽名的端點中引用它：

打開任何需要簽名驗證的端點（例如 POST /pets）。

切換到 "Run" 分頁。

向下捲動到 Pre Processors 部分。

點擊 "Add PreProcessor" 並選擇 "Public Script"。

選擇您剛剛建立的公共腳本（例如 "HMAC-SHA256 Signature Generator"）。

公共腳本現在將在發送每個請求之前自動運行，生成並新增簽名。

5. 它是如何運作的

當您發送啟用了簽名腳本的請求時：

Pre Processors 運行：公共腳本在發送請求之前執行。

收集參數：腳本收集所有查詢參數和 Body 參數。

新增時間戳：如果不存在，會自動新增 Unix 時間戳以防止重放攻擊。

排序參數：參數名稱按字母順序排序。

構建字串：參數連接為 key=value 對，用 & 連接。

生成簽名：使用您的密鑰應用 HMAC-SHA256 演算法。

新增簽名：簽名會自動作為查詢參數新增到請求中。

發送請求：包含簽名的請求被發送。

您可以透過在發送請求後檢查 "Actual Request" 分頁來驗證這一點。您應該會在查詢字串中看到 signature 參數。

6. 測試您的簽名

要驗證您的簽名是否正常運作：

設定您的端點：建立一個需要簽名驗證的端點（例如 POST /api/resource），並帶有查詢參數或 Body 參數。

新增公共腳本：在 Pre Processors 中引用 "HMAC-SHA256 Signature Generator" 腳本。

發送請求：點擊 "Send" 執行請求。

檢查實際請求：切換到 "Actual Request" 分頁。您應該看到：

timestamp 參數自動新增（如果尚未存在）

signature 參數自動新增，帶有 HMAC-SHA256 雜湊

驗證回應：如果簽名正確，您將收到成功回應。如果您收到簽名驗證錯誤：

驗證 SECRET_KEY 環境變數是否正確設定

檢查控制台日誌以查看 "String to sign" 和 "Generated signature" 值

確保參數排序符合 API 的要求

驗證 HMAC-SHA256 演算法是否正確

檢查時間戳是否在 API 接受的時間窗口內

7. 關鍵重點

API 簽名 使用密碼學雜湊驗證請求的完整性和真實性。

HMAC-SHA256 是廣泛使用的 API 簽名標準，被 Stripe 和 GitHub 等服務使用。

公共腳本 允許您建立可重複使用的簽名生成邏輯。

Pre Processors 在發送請求之前運行，非常適合自動新增簽名。

應使用 環境變數 安全地儲存密鑰。

簽名演算法 因 API 而異——始終遵循 API 提供商的具體要求。

徹底測試 以確保您的簽名符合 API 的預期格式。

透過使用腳本自動生成簽名，您可以與需要簽名驗證的 API 無縫協作，而無需為每個請求手動計算簽名。這使您的 API 測試工作流程更高效且不易出錯。

繼續閱讀 → 腳本簡介

1. 什麼是 API 簽名？#

簽名如何運作#

2. 為什麼使用腳本進行簽名？#

3. 真實範例：HMAC-SHA256 簽名#

HMAC-SHA256 如何運作#

範例計算#

4. 逐步指南#

步驟 1：設定環境變數#

步驟 2：建立公共腳本#

步驟 3：在端點中引用公共腳本#

5. 它是如何運作的#

6. 測試您的簽名#

7. 關鍵重點#

1. 什麼是 API 簽名？

簽名如何運作

2. 為什麼使用腳本進行簽名？

3. 真實範例：HMAC-SHA256 簽名

HMAC-SHA256 如何運作

範例計算

4. 逐步指南

步驟 1：設定環境變數

步驟 2：建立公共腳本

步驟 3：在端點中引用公共腳本

5. 它是如何運作的

6. 測試您的簽名

7. 關鍵重點