FastDDNS クライアントAPI

概要

FastDDNSクライアントAPIを使用すると、router、IPカメラ、スクリプト、専用のアップデーターソフトウェアなど、HTTPに対応したデバイスでDNSのhostnameを現在のIPアドレスに向け続けることができます。 APIはシンプルなGETリクエスト方式に従います。クライアントが認証情報とhostnameを送信すると、サーバーは結果を示す短いステータスコードを返します。

サーバーは、受信した接続からクライアントのパブリックIPアドレスを自動的に検出します。IPを指定するための追加パラメータは必要ありません。

認証

APIは2つの認証方法をサポートしています。どちらも同じように受け入れられます。デバイスやルーターで設定しやすい方を選んでください。

方法1 — HTTP基本認証（URL埋め込み）

認証情報は標準のuser:password@host形式でURLに埋め込まれます。これはrouter、カメラ、HTTPクライアントライブラリで広くサポートされています。ダッシュボードのUpdater Client Keyをパスワードとして使ってください。

方法2 — クエリ文字列パラメータ

認証情報はhostname認証情報はプレーンなクエリパラメータとして渡されます。これは、HTTP Basic Authヘッダーを設定できないものの、完全にカスタムしたURL文字列を指定できるデバイスやfirmwareに便利です。

クエリ文字列認証の使用例:

更新を実行

アカウントに登録されているhostnameのIPアドレスを更新するためのGETリクエストを1回送信します。各リクエストは一度に1つのホスト名を更新します。

エンドポイント

URL形式 — 方法1: HTTP基本認証

URL形式 — 方法2: クエリ文字列

クエリパラメータ

リクエスト例

方法1 — HTTPS経由のHTTP Basic Auth:

方法2 — HTTPS経由のクエリ文字列:

プレーンHTTPを使用する場合（テストまたは信頼できるネットワークのみ）:

戻りコード

すべての更新応答はHTTPステータス 200 OK を返し、本文はプレーンテキストです。 クライアントはこのテキスト本文を解析して、更新の実際の結果を判断する必要があります。

応答概要

クライアントIPを取得

FastDDNSは、サーバーから見たパブリックIPアドレスを返すシンプルなユーティリティエンドポイントを提供します。 デバッグ、デバイスがどのIPから送信しているかの確認、または更新エンドポイントを呼び出す前にカスタムスクリプトで使用する場合に便利です。

エンドポイント

レスポンス

HTTP 200 OK とともに、検出されたパブリック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 (Cron / routerスクリプト)

#!/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の入力ミスがないか、ダッシュボードにそのhostnameが登録されているか、user_nameとuser_passが一致しているか確認してくださいその特定のホスト名が正しいか確認してください。

サーバーが誤ったIPを検出しています

サーバーはTCP接続の送信元IPを使用します。デバイスがNAT routerの背後にある場合は、routerのパブリックIPが検出されます。これは通常、意図した動作です。VPNまたはプロキシを使用している場合、サーバーにはVPNまたはプロキシの出口IPが表示されます。 getip endpointを使って、サーバーがあなたのデバイスからどのIPを認識しているか確認してください。

次のエラーを受け取ります：911を受け取っています。

これは一時的なサーバー側の問題を示します。再試行する前に少なくとも5分待ってください。リクエストを短時間に繰り返し送信しないでください。rate limitingが発生する可能性があります。FastDDNSのステータスページで進行中のインシデントを確認してください。

アップデートエンドポイントはどのくらいの頻度でポーリングすべきでしょうか?

IPの変更は5分です。IPが変わっていない場合、サーバーはnochgを返しますが、これは軽量なノーオペレーションです。1分に1回以上の投票は推奨されず、速度制限につながる可能性があります。