API khách hàng FastDDNS

Tổng quan

API Máy khách FastDDNS cho phép bất kỳ thiết bị hỗ trợ HTTP nào — bộ định tuyến, camera IP, tập lệnh hoặc phần mềm cập nhật chuyên dụng — giữ tên máy chủ DNS trỏ đến địa chỉ IP hiện tại của bạn. API tuân theo một thiết kế yêu cầu GET đơn giản: máy khách của bạn gửi thông tin đăng nhập và tên máy chủ và máy chủ phản hồi bằng mã trạng thái ngắn cho biết kết quả.

Máy chủ tự động phát hiện địa chỉ IP công cộng của máy khách từ kết nối đến. Không cần thêm thông số để chỉ định IP của bạn.

Xác thực

API hỗ trợ hai phương thức xác thực. Cả hai đều được chấp nhận như nhau — chọn cái nào dễ cấu hình hơn trên thiết bị hoặc bộ định tuyến của bạn.

Phương pháp 1 - Xác thực cơ bản HTTP (nhúng URL)

Thông tin đăng nhập được nhúng trong URL bằng định dạng user:password@host tiêu chuẩn. Điều này được hỗ trợ rộng rãi bởi bộ định tuyến, máy ảnh và thư viện máy khách HTTP. Sử dụng Khóa máy khách cập nhật từ bảng điều khiển của bạn làm mật khẩu.

Phương pháp 2 - Tham số chuỗi truy vấn

Thông tin đăng nhập được chuyển dưới dạng tham số truy vấn thuần túy cùng với hostname. Điều này hữu ích cho các thiết bị và chương trình cơ sở không thể định cấu hình tiêu đề HTTP Basic Auth nhưng cho phép chuỗi URL hoàn toàn tùy chỉnh.

Ví dụ về cách sử dụng xác thực chuỗi truy vấn:

Thực hiện cập nhật

Gửi một yêu cầu GET duy nhất để cập nhật địa chỉ IP của tên máy chủ đã đăng ký với tài khoản của bạn. Mỗi yêu cầu cập nhật một tên máy chủ tại một thời điểm.

Điểm cuối

Định dạng URL - Phương pháp 1: Xác thực cơ bản HTTP

Định dạng URL - Phương pháp 2: Chuỗi truy vấn

Tham số truy vấn

Yêu cầu ví dụ

Phương pháp 1 - Xác thực cơ bản HTTP qua HTTPS:

Phương pháp 2 - Truy vấn chuỗi qua HTTPS:

Sử dụng HTTP thuần túy (chỉ thử nghiệm / mạng đáng tin cậy):

Mã trả lại

Tất cả các phản hồi cập nhật đều trả về trạng thái HTTP 200 được với nội dung văn bản thuần túy. Khách hàng của bạn phải phân tích cú pháp nội dung văn bản này để xác định kết quả thực tế của bản cập nhật.

Tóm tắt phản hồi

Nhận IP khách hàng

FastDDNS cung cấp một điểm cuối tiện ích đơn giản trả về địa chỉ IP công cộng như được máy chủ nhìn thấy. Điều này hữu ích để gỡ lỗi, để xác minh thiết bị của bạn đang gửi từ IP nào hoặc để sử dụng trong tập lệnh tùy chỉnh trước khi gọi điểm cuối cập nhật.

Điểm cuối

Câu trả lời

Trả về HTTP 200 được với địa chỉ IP công cộng được phát hiện dưới dạng văn bản thuần túy trong nội dung phản hồi.

# Example response body
203.0.113.45RESPONSE

Yêu cầu ví dụ

Sử dụng curl:

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

Ví dụ về mã

Shell / 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 (Tập lệnh Cron / Bộ định tuyến)

#!/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

Khắc phục sự cố

Tôi nhận được badauth

user_name hoặc user_pass được cung cấp không khớp với thông tin đăng nhập được gán cho tên máy chủ đó. Mỗi tên máy chủ có thông tin đăng nhập độc lập riêng — tìm chúng trong bảng điều khiển của bạn trong Tên máy chủ → chi tiết . Lưu ý rằng các thông tin đăng nhập này dành riêng cho tên máy chủ và không thể được sử dụng để đăng nhập vào cổng quản lý FastDDNS. Nếu gần đây bạn đã đặt lại thông tin đăng nhập, hãy cập nhật tất cả các thiết bị bằng tên máy chủ đó.

Tôi nhận được nohost

Tên máy chủ trong tham số hostname không tồn tại hoặc không thuộc về tài khoản được xác định bởi thông tin đăng nhập được cung cấp. Kiểm tra lỗi chính tả trong tên máy chủ, xác nhận tên máy chủ được liệt kê trong trang tổng quan của bạn và xác minh rằng user_name và user_pass khớp tên máy chủ cụ thể đó .

Máy chủ phát hiện sai IP

Máy chủ sử dụng IP nguồn của kết nối TCP. Nếu thiết bị của bạn nằm sau bộ định tuyến NAT, IP công cộng của bộ định tuyến sẽ được phát hiện - đây thường là hành vi mong muốn. Nếu bạn đang sử dụng VPN hoặc proxy, máy chủ sẽ thấy IP thoát VPN/proxy thay thế. Sử dụng getip endpoint để xác minh IP mà máy chủ nhìn thấy từ thiết bị của bạn.

Tôi nhận được 911

Điều này cho thấy sự cố phía máy chủ tạm thời. Chờ ít nhất 5 phút trước khi thử lại. Không lặp lại các yêu cầu nhanh chóng - điều này có thể kích hoạt giới hạn tốc độ. Kiểm tra trang trạng thái FastDDNS để biết bất kỳ sự cố nào đang hoạt động.

Tôi nên thăm dò điểm cuối cập nhật bao lâu một lần?

Chúng tôi khuyên bạn nên kiểm tra các thay đổi IP sau mỗi 5 phút. Khi IP của bạn không thay đổi, máy chủ trả về nochg, đây là một no-op nhẹ. Việc bỏ phiếu thường xuyên hơn một lần mỗi phút không được khuyến khích và có thể dẫn đến giới hạn tỷ lệ.