API الخاص بعميل FastDDNS

نظرة عامة

تسمح واجهة FastDDNS Client API لأي جهاز يدعم HTTP — مثل أجهزة router وكاميرات IP والسكريبتات أو برامج التحديث المخصصة — بإبقاء hostname الخاص بـ DNS موجّهًا إلى عنوان IP الحالي. تتبع API تصميمًا بسيطًا لطلبات GET: يرسل العميل بيانات الاعتماد وhostname، ويرد الخادم برمز حالة قصير يوضح النتيجة.

يكتشف الخادم عنوان IP العام للعميل تلقائيًا من الاتصال الوارد. لا حاجة إلى معايير إضافية لتحديد عنوان IP الخاص بك.

المصادقة

تدعم API طريقتين للمصادقة. كلتاهما مقبولتان بالتساوي — اختر الطريقة الأسهل للتهيئة على جهازك أو router.

الطريقة 1 — مصادقة HTTP الأساسية (مضمّنة في URL)

تُضمَّن بيانات الاعتماد في الرابط باستخدام صيغة user:password@host القياسية. وتدعمها على نطاق واسع أجهزة router والكاميرات ومكتبات عملاء HTTP. استخدم مفتاح عميل التحديث من لوحة التحكم الخاصة بك ككلمة مرور.

الطريقة 2 — معلمات سلسلة الاستعلام

تُمرَّر بيانات الاعتماد كمعلمات استعلام عادية إلى جانب hostname. يفيد ذلك للأجهزة وfirmware التي لا يمكنها تكوين رؤوس HTTP Basic Auth، لكنها تسمح باستخدام سلسلة URL مخصصة بالكامل.

مثال على استخدام مصادقة سلسلة الاستعلام:

إجراء التحديث

أرسل طلب GET واحدًا لتحديث عنوان IP لـ hostname مسجل في حسابك. يحدّث كل طلب اسم مضيف واحد في كل مرة.

نقطة النهاية

تنسيق URL — الطريقة 1: HTTP Basic Auth

تنسيق URL — الطريقة 2: سلسلة الاستعلام

معلمات الاستعلام

طلبات نموذجية

الطريقة 1 — مصادقة HTTP Basic Auth عبر HTTPS:

الطريقة 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

باش (سكريبت كرون / راوتر)

#!/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، وتأكد من إدراجه في لوحة التحكم، وتحقق من تطابق user_nameاسم المستخدم وكلمة المرورuser_pass ذلك الاسم المضيف المحدد.

يكتشف الخادم عنوان IP غير الصحيح

يستخدم الخادم عنوان IP المصدر لاتصال TCP. إذا كان جهازك خلف router يستخدم NAT، فسيُكتشف عنوان IP العام للـrouter، وهو عادةً السلوك المطلوب. أما إذا كنت تستخدم VPN أو proxy، فسيرى الخادم عنوان IP الخاص بنقطة الخروج من VPN أو proxy بدلاً من ذلك. استخدم getip endpoint للتحقق من أي عنوان IP يراها الخادم من جهازك.

للتحقق من عنوان IP الذي يراه الخادم من جهازك. 911

يشير ذلك إلى مشكلة مؤقتة من جانب الخادم. انتظر 5 دقائق على الأقل قبل إعادة المحاولة. لا تكرر الطلبات بسرعة، فقد يؤدي ذلك إلى تقييد معدل الطلبات. تحقق من صفحة حالة FastDDNS لمعرفة ما إذا كانت هناك حوادث نشطة.

كم مرة ينبغي أن أستعلم عن نقطة نهاية التحديث؟

نوصي بالتحقق من تغيّر عنوان IP كل 5 دقائق. عندما لا يتغير عنوان IP، يعيد الخادم nochgاستجابة no-op، أي لا ينفذ أي إجراء، وهي استجابة خفيفة. لا يُنصح بالاستعلام أكثر من مرة كل دقيقة، فقد يؤدي ذلك إلى تقييد معدل الطلبات.