API máy khách FastDDNS

Tổng quan

API máy khách FastDDNS cho phép mọi thiết bị có khả năng HTTP — router, camera IP, tập lệnh hoặc phần mềm cập nhật chuyên dụng — duy trì hostname DNS trỏ đến địa chỉ IP hiện tại của bạn. API sử dụng thiết kế yêu cầu GET đơn giản: máy khách gửi thông tin xác thực và hostname, còn máy chủ phản hồi bằng một 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 tham số nào để 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 — hãy chọn phương thức dễ cấu hình hơn trên thiết bị hoặc router của bạn.

Thông tin xác thực được nhúng trong URL bằng cách sử dụng tiêu chuẩn

định dạng này. Định dạng này được router, camera và các thư viện HTTP client hỗ trợ rộng rãi. Hãy sử dụng user:password@hostUpdater Client Key làm mật khẩu. Trường

Thông tin xác thực được truyền dưới dạng các tham số truy vấn thuần văn bản cùng với

. Cách này hữu ích cho các thiết bị và firmware không thể cấu hình header HTTP Basic Auth nhưng cho phép nhập chuỗi URL tùy chỉnh hoàn toàn. hostnameTham số

⚠️

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

một hostname mỗi lần..

Điểm cuối

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

Tham số truy vấn

Tham số

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ỉ dành cho thử nghiệm / mạng đáng tin cậy):

Mã trả về

Tất cả phản hồi cập nhật đều trả về trạng thái HTTP

200 OK200 đượcCập nhật thành công

Văn bản phản hồi

Nhận IP khách hàng

Endpoint

Không yêu cầu xác thực. Cũng có thể truy cập qua HTTP thuần túy.

Trả về HTTP

200 OK200 đượcCác yêu cầu mẫu

# Example response body
203.0.113.45RESPONSE

Sử dụng

:curl:

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

Ví dụ về mã

Python

# 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

PHP

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

Bash (Cron / Tập lệnh router)

<?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

Khắc phục sự cố

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

Tôi nhận đượ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 xác thực được gán cho hostname đó. Mỗi hostname có thông tin xác thực riêng — tìm chúng trong bảng điều khiển, tại Hostnames → Details. Lưu ý rằng thông tin xác thực này chỉ dành cho hostname 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 xác thực, hãy cập nhật tất cả thiết bị đang sử dụng hostname đó.

Tôi nhận được nohost

hostname trong tham số hostname không tồn tại hoặc không thuộc tài khoản được xác định bởi thông tin xác thực đã cung cấp. Kiểm tra lỗi chính tả trong hostname, xác nhận hostname đó có trong bảng điều khiển của bạn, đồng thời xác minh rằng user_name và user_pass khớp với hostname cụ thể đó.

Máy chủ phát hiện IP không chính xác

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 router NAT, máy chủ sẽ phát hiện IP công cộng của router — đâ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 của VPN/proxy. Sử dụng getip endpointendpoint Get Client IP

để xác minh IP mà máy chủ nhìn thấy từ thiết bị của bạn. 911

Điều này cho thấy sự cố tạm thời ở phía máy chủ. Hãy chờ ít nhất 5 phút trước khi thử lại. Không gửi lặp lại các yêu cầu quá nhanh — đ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 để xem có sự cố đang diễn ra hay không.

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

Chúng tôi khuyên bạn nên kiểm tra 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 thao tác không làm gì nhẹ. Không nên thăm dò thường xuyên hơn một lần mỗi phút vì có thể dẫn đến giới hạn tốc độ.