FastDDNS 클라이언트 API

개요

FastDDNS 클라이언트 API는 라우터, IP 카메라, 스크립트, 전용 업데이트 소프트웨어 등 HTTP 지원 장치가 현재 IP 주소를 DNS 호스트네임으로 유지할 수 있도록 합니다. API는 간단한 GET-request 설계를 따릅니다: 클라이언트가 자격 증명과 호스트명을 보내면 서버가 결과를 알리는 짧은 상태 코드를 응답합니다.

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

인증

API는 두 가지 인증 방식을 지원합니다. 둘 다 동등하게 허용됩니다 — 기기나 라우터에서 설정하기 쉬운 쪽을 선택하세요.

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

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

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

자격 증명은 hostname와 함께 일반 쿼리 매개변수로 전달됩니다. 이는 HTTP Basic Auth 헤더를 구성할 수 없지만 완전히 사용자 정의된 URL 문자열을 허용하는 장치와 펌웨어에 유용합니다.

쿼리 문자열 인증 예시:

업데이트 수행

계정에 등록된 호스트 이름의 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

# 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

파이썬

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

#!/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 상태 페이지에서 활성 사건이 있는지 확인해 보세요.

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

IP 변경 여부를 5분마다 확인하는 것을 권장합니다. IP가 변경되지 않으면 서버가 nochg를 반환하는데, 이는 경량 노옵입니다. 분당 한 번 이상 자주 폴링하는 것은 권장되지 않으며, 이는 속도 제한으로 이어질 수 있습니다.