FastDDNS 클라이언트 API

개요

FastDDNS 클라이언트 API를 사용하면 router, IP 카메라, 스크립트 또는 전용 업데이트 소프트웨어와 같은 HTTP 지원 장치가 DNS hostname이 현재 IP 주소를 가리키도록 유지할 수 있습니다. API는 간단한 GET 요청 방식으로 작동합니다. 클라이언트가 자격 증명과 hostname을 보내면 서버가 결과를 나타내는 짧은 상태 코드를 반환합니다.

서버는 들어오는 연결에서 클라이언트의 공인 IP 주소를 자동으로 감지합니다. IP를 지정하기 위한 추가 매개변수는 필요하지 않습니다.

인증

API는 두 가지 인증 방식을 지원합니다. 두 방식 모두 동일하게 사용할 수 있으므로 기기나 router에서 설정하기 편한 방식을 선택하면 됩니다.

방법 1 — HTTP 기본 인증 (URL 임베디드)

자격 증명은 표준 user:password@host 형식으로 URL에 삽입됩니다. 이는 router, 카메라, HTTP 클라이언트 라이브러리에서 널리 지원됩니다. 대시보드의 Updater 클라이언트 키를 비밀번호로 사용하세요.

방법 2 — 쿼리 문자열 매개변수

자격 증명은 hostname. 이는 HTTP Basic Auth 헤더를 구성할 수 없지만 완전히 사용자 정의된 URL 문자열을 허용하는 장치와 firmware에 유용합니다.

쿼리 문자열 인증 예시:

업데이트 수행

계정에 등록된 hostname의 IP 주소를 업데이트하는 단일 GET 요청을 보내세요. 각 요청은 한 번에 한 호스트명씩 업데이트됩니다.

종착점

URL 형식 — 방법 1: HTTP 기본 인증

URL 형식 — 방법 2: 쿼리 문자열

쿼리 매개변수

요청 예시

방법 1 — HTTPS를 통한 HTTP 기본 인증:

방법 2 — HTTPS를 통한 쿼리 문자열:

일반 HTTP 사용(테스트 또는 신뢰할 수 있는 네트워크에서만):

반환 코드

모든 업데이트 응답은 HTTP 상태 200 알겠습니다와 평문 본문을 반환합니다. 클라이언트는 이 텍스트 본문을 분석하여 업데이트의 실제 결과를 확인해야 합니다.

응답 요약

클라이언트 IP 가져오기

FastDDNS는 서버에서 확인되는 공인 IP 주소를 반환하는 간단한 유틸리티 엔드포인트를 제공합니다. 이 엔드포인트는 디버깅, 기기가 어떤 IP에서 연결되는지 확인하거나 업데이트 엔드포인트를 호출하기 전에 커스텀 스크립트에서 사용하는 데 유용합니다.

엔드포인트

응답

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

<?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 (크론 / 라우터 스크립트)

#!/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 전용이며 FastDDNS 관리 포털에 로그인하는 데 사용할 수 없습니다. 최근에 자격 증명을 재설정했다면 해당 hostname을 사용하는 모든 기기의 설정을 업데이트하세요.

나는 nohost

hostname 매개변수의 hostname이 존재하지 않거나 제공된 자격 증명으로 식별되는 계정에 속하지 않습니다. hostname의 오타를 확인하고 대시보드에 등록되어 있는지 확인하세요. 또한 user_name와 user_pass가 일치하는지 확인하세요. 그 특정 호스트네임 .

서버가 잘못된 IP를 감지합니다

서버는 TCP 연결의 소스 IP를 사용합니다. 기기가 NAT router 뒤에 있으면 router의 공인 IP가 감지됩니다. 이는 일반적으로 원하는 동작입니다. VPN이나 proxy를 사용 중이면 서버는 VPN 또는 proxy의 출구 IP를 확인합니다. getip endpoint를 사용하여 서버가 기기에서 확인하는 IP를 검증하세요.

받아요 911

이는 일시적인 서버 측 문제를 나타냅니다. 재시도하기 전에 최소 5분 동안 기다리세요. 요청을 빠르게 반복하지 마세요. 속도 제한이 적용될 수 있습니다. FastDDNS 상태 페이지에서 활성화된 장애가 있는지 확인하세요.

업데이트 엔드포인트를 얼마나 자주 폴링해야 하나요?

IP 변경 여부는 5분마다 확인하는 것이 좋습니다. IP가 변경되지 않으면 서버는 nochgnochg 응답을 반환합니다. 이는 서버에 변경 작업이 없는 가벼운 요청입니다. 1분에 한 번보다 자주 폴링하는 것은 권장하지 않으며 속도 제한이 적용될 수 있습니다.