API สำหรับไคลเอ็นต์ FastDDNS

ภาพรวม

FastDDNS Client API ช่วยให้อุปกรณ์ที่รองรับ HTTP ไม่ว่าจะเป็น router กล้อง IP สคริปต์ หรือซอฟต์แวร์อัปเดตเฉพาะ สามารถทำให้ hostname DNS ของคุณชี้ไปยังที่อยู่ IP ปัจจุบันได้ API ใช้รูปแบบคำขอ GET ที่เรียบง่าย โดยไคลเอ็นต์จะส่งข้อมูลรับรองและ hostname จากนั้นเซิร์ฟเวอร์จะตอบกลับด้วยรหัสสถานะสั้น ๆ ที่ระบุผลลัพธ์

เซิร์ฟเวอร์ จะตรวจจับที่อยู่ IP สาธารณะของไคลเอ็นต์โดยอัตโนมัติจากการเชื่อมต่อขาเข้า ไม่จำเป็นต้องใช้พารามิเตอร์เพิ่มเติมเพื่อระบุ IP ของคุณ

การรับรองความถูกต้อง

API รองรับวิธีการรับรองความถูกต้องสองวิธี ทั้งสองวิธีได้รับการยอมรับเท่าเทียมกัน เลือกวิธีที่กำหนดค่าได้ง่ายกว่าบนอุปกรณ์หรือ router ของคุณ

วิธีที่ 1 — HTTP Basic Auth (ฝังอยู่ใน URL)

ข้อมูลเข้าสู่ระบบจะถูกฝังไว้ใน URL โดยใช้รูปแบบuser:password@host มาตรฐาน ซึ่งเราเตอร์ กล้อง และไลบรารีไคลเอ็นต์ HTTP รองรับอย่างแพร่หลาย ใช้คีย์ไคลเอ็นต์ตัวอัปเดตจากแดชบอร์ดของคุณเป็นรหัสผ่าน

วิธีที่ 2 — พารามิเตอร์สตริงแบบสอบถาม

ข้อมูลเข้าสู่ระบบจะถูกส่งเป็นพารามิเตอร์ query แบบข้อความธรรมดาควบคู่ไปกับ hostnameซึ่งเหมาะสำหรับอุปกรณ์และ firmware ที่ไม่สามารถกำหนดค่าส่วนหัว HTTP Basic Auth ได้ แต่รองรับการใช้สตริง URL ที่กำหนดเองได้ทั้งหมด

ตัวอย่างการใช้การตรวจสอบสิทธิ์สตริงการสืบค้น:

ดำเนินการอัปเดต

ส่งคำขอ GET เพียงครั้งเดียวเพื่ออัปเดตที่อยู่ IP ของ hostname ที่ลงทะเบียนไว้กับบัญชีของคุณ คำขอแต่ละครั้งจะอัปเดต ชื่อโฮสต์ทีละชื่อ

ปลายทาง

รูปแบบ URL — วิธีที่ 1: การตรวจสอบสิทธิ์พื้นฐานของ HTTP

รูปแบบ URL — วิธีที่ 2: สตริงการสืบค้น

พารามิเตอร์คิวรี

ตัวอย่างคำขอ

วิธีที่ 1 - การตรวจสอบสิทธิ์พื้นฐาน HTTP ผ่าน HTTPS:

วิธีที่ 2 - สตริงการสืบค้นผ่าน HTTPS:

การใช้ HTTP แบบไม่เข้ารหัส (ใช้สำหรับการทดสอบ / เครือข่ายที่เชื่อถือได้เท่านั้น):

รหัสการตอบกลับ

การตอบกลับการอัปเดตทั้งหมดจะแสดงสถานะ HTTP 200 ตกลง พร้อมเนื้อความแบบข้อความธรรมดา ไคลเอ็นต์ของคุณต้องแยกวิเคราะห์เนื้อความนี้เพื่อระบุผลลัพธ์ที่แท้จริงของการอัปเดต

สรุปการตอบกลับ

รับ IP ของไคลเอ็นต์

FastDDNS มี endpoint ยูทิลิตี้อย่างง่ายที่ส่งคืนที่อยู่ IP สาธารณะตามที่เซิร์ฟเวอร์มองเห็น วิธีนี้มีประโยชน์สำหรับการดีบัก เพื่อตรวจสอบว่าอุปกรณ์ของคุณส่งคำขอมาจาก IP ใด หรือใช้ในสคริปต์แบบกำหนดเองก่อนเรียก endpoint การอัปเดต

ปลายทาง

การตอบสนอง

ส่งกลับ HTTP 200 ตกลง พร้อมที่อยู่ IP สาธารณะที่ตรวจพบในรูปแบบข้อความธรรมดาในเนื้อหาการตอบกลับ

# Example response body
203.0.113.45RESPONSE

ตัวอย่างคําขอ

ใช้ curl:

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

ตัวอย่างโค้ด

เชลล์ / cURL

# Recommended: let curl build the Authorization header (-u), so the
# credentials never appear in the URL.
HOSTNAME="myhome.fastddns.org"
USER_NAME="YOUR_UPDATE_USERNAME"
USER_PASS="YOUR_UPDATE_PASSWORD"
curl -s -u "${USER_NAME}:${USER_PASS}" "https://client.fastddns.net/?hostname=${HOSTNAME}"
# Legacy form, for devices that can only be given one URL field:
curl -s "https://client.fastddns.net/?hostname=${HOSTNAME}&user_name=${USER_NAME}&user_pass=${USER_PASS}"
# Check what IP the server sees from your device
curl -s "https://client.fastddns.net/dyndns/getip"SHELL

หลาม

import requests
HOSTNAME  = "testhost.fastddns.org"
USER_NAME = "YOUR_UPDATE_USERNAME"
USER_PASS = "YOUR_UPDATE_PASSWORD"
# 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
$hostname  = 'testhost.fastddns.org';
$user_name = 'YOUR_UPDATE_USERNAME';
$user_pass = 'YOUR_UPDATE_PASSWORD';
// Recommended: Basic Auth in a request header, so the password is not
// part of the URL and cannot leak through logs or error messages.
$url = "https://client.fastddns.net/?hostname=" . urlencode($hostname);
$auth = 'Basic ' . base64_encode($user_name . ':' . $user_pass);
// 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,
    'header'  => "Authorization: {$auth}\r\n",
]]);
$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 / Router Script)

#!/bin/bash
HOSTNAME="testhost.fastddns.org"
USER_NAME="YOUR_UPDATE_USERNAME"
USER_PASS="YOUR_UPDATE_PASSWORD"
# Method 1: HTTP Basic Auth
RESULT=$(curl -s -u "${USER_NAME}:${USER_PASS}" "https://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ข้อมูลประจำตัวที่ระบุไม่ตรงกับข้อมูลประจำตัวที่กำหนดให้กับ hostname นั้น ข้อมูลประจำตัวของแต่ละ hostname เป็นข้อมูลเฉพาะของ hostname นั้น โดยดูได้ในแดชบอร์ดของคุณที่ ชื่อโฮสต์→รายละเอียด. โปรดทราบว่าข้อมูลประจำตัวเหล่านี้ใช้ได้เฉพาะกับ hostname และ ไม่สามารถใช้เข้าสู่ระบบพอร์ทัลการจัดการ FastDDNS ได้. หากคุณเพิ่งรีเซ็ตข้อมูลประจำตัว โปรดอัปเดตอุปกรณ์ทั้งหมดที่ใช้ hostname นั้น

ฉันได้รับ nohost

ชื่อโฮสต์ในพารามิเตอร์ hostname ไม่มีอยู่จริง หรือไม่ได้เป็นของบัญชีที่ระบุโดยข้อมูลประจำตัวที่ให้มา ตรวจสอบว่า hostname สะกดถูกต้อง ยืนยันว่ามี hostname นี้อยู่ในแดชบอร์ด และตรวจสอบว่า user_name และ user_pass และ ชื่อโฮสต์ที่เฉพาะเจาะจงนั้น.

เซิร์ฟเวอร์ตรวจพบ IP ไม่ถูกต้อง

เซิร์ฟเวอร์ใช้ IP ต้นทางของการเชื่อมต่อ TCP หากอุปกรณ์ของคุณอยู่หลัง router NAT เซิร์ฟเวอร์จะตรวจพบ IP สาธารณะของ router ซึ่งโดยปกติเป็นพฤติกรรมที่ต้องการ หากคุณใช้ VPN หรือพร็อกซี เซิร์ฟเวอร์จะเห็น IP ทางออกของ VPN/proxy แทน ใช้ getip endpoint เพื่อยืนยันว่าเซิร์ฟเวอร์มองเห็น IP ใดจากอุปกรณ์ของคุณ

ฉันได้รับ 911

แสดงว่ามีปัญหาชั่วคราวที่ฝั่งเซิร์ฟเวอร์ โปรดรออย่างน้อย 5 นาทีก่อนลองอีกครั้ง อย่าส่งคำขอซ้ำอย่างรวดเร็ว เพราะอาจทำให้ถูกจำกัดอัตราการส่งคำขอ ตรวจสอบหน้าสถานะ FastDDNS ว่ามีเหตุขัดข้องที่กำลังดำเนินอยู่หรือไม่

ควรตรวจสอบ endpoint สำหรับอัปเดตบ่อยแค่ไหน

เราแนะนำให้ตรวจสอบการเปลี่ยนแปลงของ IP ทุก ๆ 5 นาที เมื่อ IP ของคุณไม่มีการเปลี่ยนแปลง เซิร์ฟเวอร์จะส่งคืน nochg ซึ่งเป็น no-op ที่มีน้ำหนักเบา ไม่แนะนำให้ทำโพลบ่อยกว่าหนึ่งครั้งต่อนาที เพราะอาจทำให้ถูกจำกัดอัตราการส่งคำขอ