HTTPDNS：調度服務介面

1. 前言

調度介面是 HTTPDNS 高可用架構的核心組件，負責根據用戶端地理位置和網路狀況，智能分配最優的解析服務節點。通過調度介面，用戶端可以擷取就近、健康的服務 IP 列表，實現高效能的網域名稱解析服務。

以下將詳細介紹調度介面的使用方法，包括介面形式、參數配置、安全機制和響應處理，主要內容為：

• 介面形式：介紹調度介面的基本形式和 URL 構造方法

• 參數說明：詳細說明調度介面的參數配置，包括必選參數和選擇性參數

• 請求加簽：闡述請求籤名機制，提升調度請求的安全性

• API響應說明：說明 API 響應格式和錯誤處理機制

• 服務 IP 更新機制：提供服務 IP 更新策略和最佳實務建議

2. 介面形式

調度介面支援通過 HTTP 或 HTTPS 進行訪問，介面形式如下：

• 服務 URL：http(s)://{啟動存取點}/{account_id}/ss? + {請求參數}

• 請求方式：GET

3. 參數說明

調度介面通過請求參數控制調度策略和安全機制。您可以靈活設定參數，實現基礎調度、簽名驗證等功能。

3.1 參數列表

3.2 請求參數樣本

• 指定地區調度請求

GET https://{啟動IP}/{account_id}/ss?region=cn&n=abcdef2345&t=1632912372&s=de7be63a9f19cf11e9d455d7d4f23cb4 HTTP/1.1

• 按照用戶端就近調度請求

GET https://{啟動IP}/{account_id}/ss?region=global&n=abcdef2345&t=1632912372&s=de7be63a9f19cf11e9d455d7d4f23cb4 HTTP/1.1

4. 請求籤名（可選）

為提高調度請求的安全性，建議啟用請求籤名功能。簽名機制可以防止請求被篡改。

4.1 簽名演算法

• 演算法：HMAC-MD5

• 密鑰：加簽密鑰，可以在開發配置擷取

• 輸入：按照 {n}-{secret}-{t} 格式構造的字串

• 輸出：32 位小寫十六進位字串

4.2 簽名步驟

1. 產生隨機數 n：16 進位字串，長度 8-16 位

2. 擷取有效時間戳記 t：目前時間 + 有效時間（秒），有效時間建議 30-300 秒

3. 建構簽章字串：按照 {n}-{secret}-{t} 格式拼接

4. 計算簽名：使用 HMAC-MD5 演算法計算簽名值

4.3 簽名樣本

假設：

• 隨機數 n = abcdef2345

• SecretKey = 123456

• 時間戳記 t = 1632912372

• 地區 region = cn

簽名計算過程：

簽名字串 = "abcdef2345-123456-1632912372"
s = HMAC-MD5("123456", "abcdef2345-123456-1632912372")
  = "de7be63a9f19cf11e9d455d7d4f23cb4"

最終請求：

GET https://{啟動IP}/{account_id}/ss?region=cn&n=abcdef2345&t=1632912372&s=de7be63a9f19cf11e9d455d7d4f23cb4 HTTP/1.1

5. API 響應說明

調度介面返回的響應包含服務 IP 列表和相關中繼資料，下面將詳細介紹成功響應的資料結構、欄位含義以及各種錯誤情況的處理方法。

5.1 響應格式

請求成功時，HTTP 響應狀態代碼為 200，響應結果用 JSON 格式表示：

{
  "service_ip": [
    "203.107.1.xx",
    "106.xxx.1.xx"
  ],
  "service_ipv6": [
    "64:ff9b::xxx:121",
    "64:ff9b::xxx:122"
  ]
}

5.2 響應欄位說明

5.3 錯誤響應

請求失敗時，HTTP 響應狀態代碼為 4xx/5xx，響應結果用 JSON 格式表示：

{
  "code": "MissingArgument"
}

常見錯誤碼：

6. 總結

本文詳細介紹了 HTTPDNS 調度介面的使用方法和技術細節，包括介面形式、參數配置、安全機制和響應處理等關鍵環節。通過調度介面，開發人員可以擷取最優的解析服務 IP 列表。在擷取解析服務 IP 列表後，即可進行具體的網域名稱解析操作， 參考網域名稱解析介面。