واجهة برمجة تطبيقات الخادم للبوتات

كل ما تفعله لوحة التحكم يمكن تنفيذه من الكود الخاص بك: تشغيل خادم وفق جدول زمني، وعرض الحالة في Discord، وإرسال الأوامر من بوت.

المفتاح

تتوفر الواجهة البرمجية في أي خطة مدفوعة — في المكان نفسه الذي توجد فيه الملفات وSFTP ووصول الفريق. في الخطة المجانية لا يُصدر مفتاح: فالمفتاح هو نفس وصول المشاركة، لكن للبوت فقط.

قسم «اللاعبون والوصول» ← «مفاتيح API» ← «إصدار». تحقق مما يُسمح للمفتاح بفعله — فالأذونات هي نفسها الخاصة بوصول المشاركة.

يُعرض المفتاح مرة واحدة: نحن نحتفظ ببصمته فقط. إذا فقدته، أصدر مفتاحًا جديدًا وأبطل القديم.

يُمرَّر المفتاح في الترويسة Authorization: Bearer mhk_live_....

الطرق

عنوان الأساس — https://millida.net/v2/hosting/api.

مثال: تشغيل خادم وانتظار اتصاله

KEY="mhk_live_xxx"
API="https://millida.net/v2/hosting/api"

curl -sX POST "$API/start" -H "Authorization: Bearer $KEY"

until curl -s "$API/status" -H "Authorization: Bearer $KEY" | grep -q RUNNING; do
  sleep 5
done
echo "server online"

تُنشأ النسخ الاحتياطية في الخلفية

تُعيد POST /backups القيمة {"id":"..."} فورًا، بينما يُجمَّع الأرشيف نفسه على العقدة: عالم بحجم عدة غيغابايتات يستغرق دقائق. تحقق من الجاهزية في GET /backups عبر الحقل status: pending — لا يزال قيد التجميع، ready — محفوظ في التخزين (عندها يظهر sizeMb الحقيقي)، failed — فشل التجميع.

ID=$(curl -sX POST "$API/backups" -H "Authorization: Bearer $KEY" | jq -r .id)

until curl -s "$API/backups" -H "Authorization: Bearer $KEY" \
  | jq -e --arg id "$ID" '.[] | select(.id==$id) | select(.status=="ready")' >/dev/null; do
  sleep 15
done
echo "backup ready"

أثناء إنشاء نسخة احتياطية، لا يمكنك إنشاء نسخة ثانية على الخادم نفسه — فالعقدة تنشئها واحدة تلو الأخرى.

الطرفية المباشرة

تُعيد GET /console بث Server-Sent Events: يصل كل سطر مع البادئة data:. لا حاجة إلى WebSocket — فـ SSE يمر عبر أي وسيط.

ما ينبغي أن تعرفه

• يُسجَّل كل إجراء للمفتاح في سجل الخادم باسم المؤلف «API key N». وهذا بالضبط ما تحتاجه عندما يشغّل البشر والبوتات الخوادم معًا.
• يُحسب تحديد المعدل لكل مفتاح، لا لكل عنوان: فتغيير IP لا يتجاوز الحد، والجار على شبكة المكتب لا يستهلكه. وهو سخي للأتمتة العادية، لكن استعلام الحالة مرة كل ثانية سيصطدم به — مرة كل 10–15 ثانية تكفي. ويمكن فتح بث الطرفية حتى عشر مرات في الدقيقة: أبقِ اتصالًا واحدًا بدل فتح اتصال جديد لكل رسالة.
• يتوقف المفتاح عن العمل فورًا إذا عُلّق الخادم أو لم تعد الخطة مدفوعة. ولا تحتاج إلى إبطاله يدويًا لذلك.
• حتى خمسة مفاتيح لكل خادم. أبطل ما لا تحتاجه منها.

الحماية من البوتات

تُعيد GET /antibot الإعدادات في حقلين. config — إعدادات الخادم الخاصة؛ وإلى أن توجد، تكون null، ويكون الخادم محميًا افتراضيًا (الحقل default). أما effective فموجود دائمًا: وهي الإعدادات السارية حاليًا أو التي سيبدأ الخادم العمل بها بعد أول تعديل — اقرأ القيم منها.

لا تقبل PUT /antibot سوى الحقول التي تريد تغييرها:

curl -sX PUT "$API/antibot" -H "Authorization: Bearer $KEY"   -H 'Content-Type: application/json'   -d '{"preset":"balanced"}'

المستويات (preset): off، under_attack، balanced، aggressive، custom. يتوسع المستوى إلى قيم الفحوص من تلقاء نفسه، لذا للضبط اليدوي اختر custom وأرسل الفحوص: checkCaptcha، checkPhysics، checkKeepAlive، checkTeleport، checkBrand، checkPing، checkTransfer، checkClientSettings — كل واحد منها off أو under_attack أو always. قوائم العناوين (vpnMode، datacenterMode، torMode) — off أو log أو block. الفلتر الجغرافي — geoMode (off، allow، deny) وgeoCountries (رموز الدول، مثل ["RU","BY"]).

لا يُصدر سر التمرير أو يُغيَّر عبر الواجهة البرمجية: فهو يُعرض للمالك فقط في اللوحة.

إعدادات الملفات

تُعيد GET /files/config?path=server.properties الملف محللًا — كل مدخل مع نوعه وقيمته الحالية وعلامة «يتطلب إعادة تشغيل»:

{
  "path": "server.properties",
  "format": "properties",
  "options": [
    { "key": "pvp", "type": "boolean", "value": "true", "owner": "sync", "requiresRestart": false },
    { "key": "difficulty", "type": "select", "value": "normal", "values": ["peaceful", "easy", "normal", "hard"], "owner": "sync", "requiresRestart": false },
    { "key": "server-port", "type": "integer", "value": "25565", "owner": "platform", "requiresRestart": true }
  ]
}

يخبرك owner بما يمكن فعله بالمدخل: platform — القيمة تحددها الاستضافة، وتُرفض التعديلات؛ sync — المدخل موجود في اللوحة وفي الملف معًا؛ file — الملف وحده يعرف عنه.

يغيّر الكتابة المفاتيح التي ترسلها فقط؛ وكل ما عداها في الملف يبقى دون مساس:

curl -sX POST "$API/files/config" -H "Authorization: Bearer $KEY"   -H 'Content-Type: application/json'   -d '{"path":"server.properties","values":{"pvp":"false","difficulty":"hard"}}'

يقرأ النموذج .properties و.yml/.yaml و.toml — بما في ذلك إعدادات المودات التي لا تعرف اللوحة عنها شيئًا: يُستنتج نوع الحقل من القيمة. وتُعنون المفاتيح المتداخلة بنقطة: settings.bungeecord، advanced.compression-threshold.

لا يزال الملف كاملًا متاحًا عبر GET/PUT /files/content?path= — وكلا المسارين يكتبان في المكان نفسه.

عميل جاهز في Node.js و Python

فيما يلي عميل بسيط: يتحقق من الحالة، ويشغّل الخادم، ويكتب في الدردشة. يُقرأ المفتاح من متغير البيئة MILLIDA_KEY — لا تلصقه في كود ينتهي به المطاف في git. استجابة الخطأ هي JSON تحتوي على حقل message؛ وهذا ما ينبغي أن يسجّله البوت الخاص بك.

Node.js 18+ (دالة fetch المدمجة):

const API = 'https://millida.net/v2/hosting/api';
const KEY = process.env.MILLIDA_KEY;

async function call(method, path, body) {
  const res = await fetch(`${API}${path}`, {
    method,
    headers: { Authorization: `Bearer ${KEY}`, 'Content-Type': 'application/json' },
    body: body ? JSON.stringify(body) : undefined,
  });
  if (!res.ok) throw new Error(`${method} ${path}: ${res.status} ${await res.text()}`);
  return res.status === 204 ? null : res.json();
}

const status = await call('GET', '/status');
if (status.status !== 'RUNNING') await call('POST', '/start');
await call('POST', '/command', { command: 'say Hello from the bot' });

Python 3 مع مكتبة requests، بالإضافة إلى قراءة وحدة التحكم المباشرة:

import os
import requests

API = "https://millida.net/v2/hosting/api"
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['MILLIDA_KEY']}"

def call(method, path, body=None):
    res = session.request(method, API + path, json=body, timeout=15)
    res.raise_for_status()
    return res.json() if res.content else None

status = call("GET", "/status")
if status["status"] != "RUNNING":
    call("POST", "/start")
call("POST", "/command", {"command": "say Hello from the bot"})

with session.get(API + "/console", stream=True, timeout=None) as stream:
    for line in stream.iter_lines(decode_unicode=True):
        if line and line.startswith("data:"):
            print(line[5:].strip())