FastDDNS 用戶端 API

概述

FastDDNS 用戶端 API 允許任何支援 HTTP 的裝置——路由器、IP 攝影機、腳本或專用更新軟體——都能讓你的 DNS 主機名稱指向你目前的 IP 位址。 API 採用簡單的 GET 請求設計：客戶端傳送憑證和主機名稱，伺服器會以簡短的狀態碼回應結果。

伺服器會自動偵測到用戶端的公共 IP 位址。指定 IP 不需要額外參數。

認證

API 支援兩種認證方法。兩者都一樣被接受——選擇在你的裝置或路由器上較容易設定的那個。

方法一 — HTTP 基本認證（URL 嵌入）

憑證會以標準的 user:password@host 格式嵌入網址中。這在路由器、攝影機和 HTTP 用戶端函式庫中被廣泛支援。用儀表板上的更新器客戶端金鑰當作密碼。

方法二 — 查詢字串參數

憑證以純查詢參數的形式傳遞，與 hostname 一同傳遞。這對於無法設定 HTTP Basic Auth 標頭但允許完全自訂 URL 字串的裝置和韌體非常有用。

使用查詢字串驗證的範例：

執行更新

發送一個 GET 請求，更新你帳號註冊的主機名稱的 IP 位址。每次請求會更新一個主機名稱。

終點

URL 格式 — 方法一：HTTP 基本認證

URL 格式 — 方法二：查詢字串

查詢參數

請求範例

方法一 — HTTP基本認證（HTTPS over HTTPS）：

方法二 — 透過 HTTPS 查詢字串：

使用純 HTTP（僅限測試/受信任網路）：

退回代碼

所有更新回應都會回傳 HTTP 狀態200 OK 正文是純文字。 你的客戶必須解析此文字內容，以判斷更新的實際結果。

回應摘要

取得用戶端 IP

FastDDNS 提供一個簡單的工具端點，回傳伺服器所見的公共 IP 位址。 這對於除錯、驗證裝置從哪個 IP 發送，或是在呼叫更新端點前的自訂腳本中非常有用。

終點

回應

回傳 HTTP200 OK 在回應文中，偵測到的公共 IP 位址以明文形式呈現。

# Example response body
203.0.113.45RESPONSE

請求範例

使用 curl：

curl https://client.fastddns.net/dyndns/getipSHELL

程式碼範例

殼層 / cURL

# Method 1: HTTP Basic Auth (HTTPS, IP auto-detected)
curl "https://fastddnstest:[email protected]/?hostname=testhost.fastddns.org"
# Method 2: Query string credentials
curl "https://client.fastddns.net/?hostname=testhost.fastddns.org&user_name=fastddnstest&user_pass=569832"
# Check what IP the server sees from your device
curl "https://client.fastddns.net/dyndns/getip"SHELL

Python

import requests
HOSTNAME  = "testhost.fastddns.org"
USER_NAME = "fastddnstest"
USER_PASS = "569832"
# Method 1: HTTP Basic Auth
resp = requests.get(
    "https://client.fastddns.net/",
    auth=(USER_NAME, USER_PASS),
    params={"hostname": HOSTNAME}
)
# Method 2: Query string
# resp = requests.get("https://client.fastddns.net/", params={
#     "hostname": HOSTNAME, "user_name": USER_NAME, "user_pass": USER_PASS
# })
body = resp.text.strip()
if body.startswith("good"):
    print(f"Updated successfully: {body}")
elif body.startswith("nochg"):
    print(f"No change needed: {body}")
elif body == "badauth":
    print("Authentication failed. Check credentials.")
elif body == "nohost":
    print("Hostname not found.")
elif body == "911":
    print("Server error. Try again later.")PYTHON

PHP

<?php
$hostname  = 'testhost.fastddns.org';
$user_name = 'fastddnstest';
$user_pass = '569832';
// Method 1: HTTP Basic Auth embedded in URL
$url = "https://{$user_name}:{$user_pass}@client.fastddns.net/?hostname=" . urlencode($hostname);
// Method 2: Query string credentials
// $url = "https://client.fastddns.net/?hostname=" . urlencode($hostname)
//      . "&user_name=" . urlencode($user_name)
//      . "&user_pass=" . urlencode($user_pass);
$ctx = stream_context_create(['http' => ['timeout' => 10]]);
$body = trim(file_get_contents($url, false, $ctx));
switch (true) {
    case str_starts_with($body, 'good'):
        echo "Updated: {$body}\n"; break;
    case str_starts_with($body, 'nochg'):
        echo "No change: {$body}\n"; break;
    case $body === 'badauth':
        echo "Auth failed. Check hostname credentials.\n"; break;
    case $body === 'nohost':
        echo "Hostname not found.\n"; break;
    case $body === '911':
        echo "Server error, retry later.\n"; break;
}PHP

Bash（Cron / 路由器腳本）

#!/bin/bash
HOSTNAME="testhost.fastddns.org"
USER_NAME="fastddnstest"
USER_PASS="569832"
# Method 1: HTTP Basic Auth
RESULT=$(curl -s "https://${USER_NAME}:${USER_PASS}@client.fastddns.net/?hostname=${HOSTNAME}")
# Method 2: Query string (uncomment to use instead)
# RESULT=$(curl -s "https://client.fastddns.net/?hostname=${HOSTNAME}&user_name=${USER_NAME}&user_pass=${USER_PASS}")
case "$RESULT" in
  good*)   echo "[OK] $RESULT" ;;
  nochg*)  echo "[OK] $RESULT" ;;
  badauth) echo "[ERR] Bad credentials — check hostname user/pass"; exit 1 ;;
  nohost)  echo "[ERR] Hostname not found"; exit 1 ;;
  911)     echo "[ERR] Server error, retry later"; exit 1 ;;
  *)       echo "[WARN] Unknown response: $RESULT" ;;
esacBASH

故障排除

我收到badauth

所提供的 user_name 或 user_pass 與該主機名稱所分配的憑證不符。 每個主機名稱都有獨立的憑證——可以在你的儀表板下找到主機名稱→細節 . 請注意，這些憑證是針對主機名稱的，無法用來登入 FastDDNS 管理入口網站。 如果你最近重設了憑證，請更新所有使用該主機名稱的裝置。

我收到nohost

hostname 參數中的主機名稱不存在，或不屬於所提供憑證所識別的帳號。 檢查主機名稱有沒有錯字，確認它在你的儀表板上有列出，並確認 user_name 和 user_pass 是否相符那個特定的主機名稱 .

伺服器偵測到錯誤的 IP

伺服器會使用 TCP 連線的來源 IP。如果你的裝置在 NAT 路由器後面，路由器的公共 IP 會被偵測到——這通常是理想的行為。如果你在 VPN 或代理伺服器上，伺服器會看到 VPN/代理的出口 IP。 用 getip endpoint 來確認伺服器從你的裝置看到的是哪個 IP。

我收到911

這表示伺服器端存在暫時性問題。至少等5分鐘再重試。請勿快速迴圈請求——這可能會觸發速率限制。請查看FastDDNS狀態頁面是否有任何活躍事件。

我應該多久輪詢一次更新端點？

我們建議每5分鐘檢查一次IP變更。當你的 IP 沒有變動時，伺服器會回傳 nochg，這是輕量級的 no-op。不建議每分鐘超過一次輪詢，且可能導致速率限制。