————-تحقق من إضافة الأشياء————–

توثيق واجهة برمجة التطبيقات I2PControl

I2PControl هو واجهة برمجة تطبيقات JSON-RPC 2.0 مدمجة مع router I2P (منذ الإصدار 0.9.39). يمكّن من المراقبة والتحكم المصادق عليه في router عبر طلبات JSON منظمة.

كلمة المرور الافتراضية: itoopie — هذه هي القيمة الافتراضية من المصنع ويجب تغييرها فوراً لأغراض الأمان.

1. نظرة عامة والوصول

2. تنسيق JSON-RPC

جميع الطلبات تتبع بنية JSON-RPC 2.0:

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "MethodName",
  "params": {
    /* named parameters */
  }
}

تتضمن الاستجابة الناجحة حقل result؛ وفي حالة الفشل، يتم إرجاع كائن error:

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": { /* data */ }
}

أو

{
  "jsonrpc": "2.0",
  "id": "1",
  "error": {
    "code": -32001,
    "message": "Invalid password"
  }
}

3. تدفق المصادقة

طلب (المصادقة)

curl -s -H "Content-Type: application/json" \
  -d '{
        "jsonrpc": "2.0",
        "id": "1",
        "method": "Authenticate",
        "params": {
          "API": 1,
          "Password": "itoopie"
        }
      }' \
  http://127.0.0.1:7657/jsonrpc/

استجابة ناجحة

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "Token": "a1b2c3d4e5",
    "API": 1
  }
}

يجب أن تتضمن هذا Token في جميع الطلبات اللاحقة ضمن params.

4. الطرق والنقاط النهائية

4.1 معلومات الموجه (RouterInfo)

يجلب بيانات القياس الرئيسية حول الـ router.

مثال على الطلب

curl -s -H "Content-Type: application/json" \
  -d '{
        "jsonrpc": "2.0",
        "id": "2",
        "method": "RouterInfo",
        "params": {
          "Token": "a1b2c3d4e5",
          "i2p.router.version": "",
          "i2p.router.status": "",
          "i2p.router.net.status": "",
          "i2p.router.net.tunnels.participating": "",
          "i2p.router.net.bw.inbound.1s": "",
          "i2p.router.net.bw.outbound.1s": ""
        }
      }' \
  http://127.0.0.1:7657/jsonrpc/

حقول الاستجابة (result) وفقاً للوثائق الرسمية (GetI2P): - i2p.router.status (String) — حالة قابلة للقراءة البشرية - i2p.router.uptime (long) — بالميلي ثانية (أو نص لإصدارات i2pd الأقدم) :contentReference[oaicite:0]{index=0} - i2p.router.version (String) — نص الإصدار :contentReference[oaicite:1]{index=1} - i2p.router.net.bw.inbound.1s, i2p.router.net.bw.inbound.15s (double) — عرض النطاق الداخل بوحدة B/s :contentReference[oaicite:2]{index=2} - i2p.router.net.bw.outbound.1s, i2p.router.net.bw.outbound.15s (double) — عرض النطاق الخارج بوحدة B/s :contentReference[oaicite:3]{index=3} - i2p.router.net.status (long) — رمز الحالة الرقمي (انظر التعداد أدناه) :contentReference[oaicite:4]{index=4} - i2p.router.net.tunnels.participating (long) — عدد الأنفاق المشاركة :contentReference[oaicite:5]{index=5} - i2p.router.netdb.activepeers, fastpeers, highcapacitypeers (long) — إحصائيات النظراء في netDB :contentReference[oaicite:6]{index=6} - i2p.router.netdb.isreseeding (boolean) — ما إذا كانت إعادة البذر نشطة :contentReference[oaicite:7]{index=7} - i2p.router.netdb.knownpeers (long) — إجمالي النظراء المعروفين :contentReference[oaicite:8]{index=8}

تعداد رمز الحالة (i2p.router.net.status)

4.2 GetRate

يُستخدم لجلب مقاييس المعدل (مثل عرض النطاق الترددي، نجاح tunnel) خلال إطار زمني محدد.

مثال على الطلب

curl -s -H "Content-Type: application/json" \
  -d '{
        "jsonrpc": "2.0",
        "id": "3",
        "method": "GetRate",
        "params": {
          "Token": "a1b2c3d4e5",
          "Stat": "bw.combined",
          "Period": 60000
        }
      }' \
  http://127.0.0.1:7657/jsonrpc/

استجابة نموذجية

{
  "jsonrpc": "2.0",
  "id": "3",
  "result": {
    "Rate": 12345.67
  }
}

4.3 RouterManager

تنفيذ الإجراءات الإدارية.

المعاملات / الطرق المسموحة - Restart, RestartGraceful - Shutdown, ShutdownGraceful - Reseed, FindUpdates, Update :contentReference[oaicite:10]{index=10}

مثال على الطلب

curl -s -H "Content-Type: application/json" \
  -d '{
        "jsonrpc": "2.0",
        "id": "4",
        "method": "RouterManager",
        "params": {
          "Token": "a1b2c3d4e5",
          "Restart": true
        }
      }' \
  http://127.0.0.1:7657/jsonrpc/

الاستجابة الناجحة

{
  "jsonrpc": "2.0",
  "id": "4",
  "result": {
    "Restart": null
  }
}

4.4 NetworkSetting

الحصول على أو تعيين معاملات تكوين الشبكة (المنافذ، upnp، مشاركة عرض النطاق الترددي، إلخ)

مثال على الطلب (الحصول على القيم الحالية)

curl -s -H "Content-Type: application/json" \
  -d '{
        "jsonrpc": "2.0",
        "id": "5",
        "method": "NetworkSetting",
        "params": {
          "Token": "a1b2c3d4e5",
          "i2p.router.net.ntcp.port": null,
          "i2p.router.net.ssu.port": null,
          "i2p.router.net.bw.share": null,
          "i2p.router.net.upnp": null
        }
      }' \
  http://127.0.0.1:7657/jsonrpc/

نموذج الاستجابة

{
  "jsonrpc": "2.0",
  "id": "5",
  "result": {
    "i2p.router.net.ntcp.port": "1234",
    "i2p.router.net.ssu.port": "5678",
    "i2p.router.net.bw.share": "50",
    "i2p.router.net.upnp": "true",
    "SettingsSaved": true,
    "RestartNeeded": false
  }
}

ملاحظة: إصدارات i2pd السابقة للإصدار 2.41 قد ترجع أنواع رقمية بدلاً من النصوص — يجب على العملاء التعامل مع كلا النوعين. :contentReference[oaicite:11]{index=11}

4.5 الإعدادات المتقدمة

يسمح بالتلاعب في معاملات router الداخلية.

مثال على الطلب

curl -s -H "Content-Type: application/json" \
  -d '{
        "jsonrpc": "2.0",
        "id": "6",
        "method": "AdvancedSettings",
        "params": {
          "Token": "a1b2c3d4e5",
          "Set": {
            "router.sharePercentage": "75",
            "i2np.flushInterval": "6000"
          }
        }
      }' \
  http://127.0.0.1:7657/jsonrpc/

مثال على الاستجابة

{
  "jsonrpc": "2.0",
  "id": "6",
  "result": {
    "Set": {
      "router.sharePercentage": "75",
      "i2np.flushInterval": "6000"
    }
  }
}

5. رموز الخطأ

رموز أخطاء JSON-RPC2 المعيارية

6. الاستخدام وأفضل الممارسات

• قم دائماً بتضمين معامل Token (عدا عند المصادقة).
• غيّر كلمة المرور الافتراضية (itoopie) عند الاستخدام الأول.
• لـ Java I2P، تأكد من تمكين تطبيق I2PControl عبر WebApps.
• كن مستعداً لاختلافات طفيفة: قد تكون بعض الحقول أرقاماً أو نصوصاً، حسب إصدار I2P.
• قم بلف سلاسل الحالة الطويلة للحصول على مخرجات سهلة القراءة.