أصبح لدى ZimaOS الآن توثيق لـ OpenAPI، ولكن ينبغي اعتبار نمط 2024 القديم المتمثل في استدعاء /v1/users/login وإعادة استخدام رمز الوصول المُعاد تقنيةً لمصادقة الجلسة، وليس نظامًا لمفاتيح API دائمة. وقد أوضحت IceWhale صراحةً في ذلك النقاش أن الرموز الدائمة غير مدعومة.
يركز توثيق OpenAPI الحالي على العملاء المُولَّدين ونقاط نهاية الخدمات، وليس على واجهة لرموز الوصول الشخصية. بالنسبة إلى الأتمتة مثل Home Assistant، احرص على إبقاء المصادقة محلية، وتجنب إتاحة نقطة نهاية تسجيل الدخول للعامة، وصمّم تكاملك لإعادة المصادقة عند انتهاء صلاحية رمز الجلسة.
استخدم مواصفات OpenAPI الحالية
يوجّه دليل ZimaOS OpenAPI الحالي المطورين إلى مستودع OpenAPI الخاص بـ IceWhale، ويوضح كيفية إنشاء عملاء لخدمات التخزين وغيرها.
كانت نقطة نهاية تسجيل الدخول التاريخية تُعيد رمز وصول
في النقاش الأصلي، أرسل المستخدم بيانات الاعتماد بنجاح عبر POST إلى /v1/users/login، ووجد رمز وصول في الاستجابة. ثم أوضحت IceWhale أن الرموز الدائمة غير مدعومة.
لا تُثبّت رمزًا مؤقتًا إلى الأبد
قد تنتهي صلاحية رمز الجلسة أو يُبطَل بسبب تغييرات تسجيل الدخول أو الأمان. خزّن بيانات الاعتماد أو حالة الجلسة المُحدَّثة بأمان، وتعامل مع حالات فشل المصادقة بشكل صريح.
أبقِ واجهة API ضمن شبكة موثوقة
لا تُحوِّل نقاط نهاية ZimaOS الداخلية إلى الإنترنت العام عبر إعادة توجيه المنافذ. استخدم الشبكة المحلية أو VPN أو ZimaClient/شبكة خاصة للوصول إلى الخادم أولًا.
حدّث إصدارات ZimaOS القديمة قبل التطوير باستخدام واجهات تسجيل الدخول
كان لدى ZimaOS ثغرة خطيرة لتجاوز المصادقة في الإصدارات حتى 1.5.0، وكانت تؤثر في /v1/users/login؛ وقد أُصلحت في الإصدار 1.5.3. طوّر دائمًا باستخدام إصدار مستقر حديث.
يوثّق التنبيه الأمني لتسجيل الدخول في ZimaOS ذلك الحد الأمني.
استخدم أقل قدر من الصلاحيات في Home Assistant
إذا كنت تجمع مقاييس درجة الحرارة أو وحدة المعالجة المركزية أو الطاقة أو الأقراص، فاطلب البيانات التي يحتاج إليها تكاملك فقط. تجنب إنشاء أتمتة يمكنها أيضًا تعديل المستخدمين أو التخزين أو إعدادات النظام، إلا عند الضرورة القصوى.
توقّع تغيّر إصدارات API
يشير الدليل الحالي إلى مسارات خدمات مُرقّمة مثل /v2/local_storage. لا تفترض أن كل نقطة نهاية من عام 2024 ستظل الواجهة المفضلة إلى أجل غير مسمى؛ بل أنشئ العملاء أو حدّثهم انطلاقًا من مخططات OpenAPI الحالية.
يوفر دليل الوصول الخاص نموذج الشبكة الأكثر أمانًا.
تعامل مع استجابات 401 بإعادة المصادقة
ينبغي لتكامل متين أن يتعامل مع استجابة HTTP 401 أو انتهاء الجلسة باعتبارها إشارة للحصول على جلسة جديدة، بدلًا من إعادة محاولة استخدام الرمز نفسه مرارًا. أضف مسار إعادة محاولة محدودًا، حتى لا يؤدي تعطل تسجيل الدخول إلى إنشاء حلقة طلبات لا نهائية.
لا تضع الرموز في السجلات
تُعد سجلات تصحيح أخطاء Home Assistant وسجل أوامر الصدفة ولقطات الشاشة ومستودعات Git أماكن شائعة لتسرّب الرموز. احجب ترويسات التفويض واستجابات تسجيل الدخول بصيغة JSON قبل مشاركة بيانات التشخيص علنًا.
ثبّت عقد API الذي تعتمد عليه
إذا كان تكاملك يستخدم عملاء OpenAPI مُولَّدين، فاحتفظ بالمخطط والإصدار إلى جانب الشيفرة، وراجع التغييرات الواردة من المصدر قبل إعادة التوليد. يوضح ذلك متى تغيّرت نقطة نهاية أو بنية استجابة، بدلًا من أن تتعطل الأتمتة بصمت.
الأسئلة الشائعة
هل يستطيع ZimaOS إنشاء رمز API دائم؟
ذكرت إجابة IceWhale في المصدر أن الرموز الدائمة غير مدعومة، كما أن الوثائق العامة الحالية لا توثّق واجهة لرموز الوصول الشخصية.
كيف تم الحصول على رمز الوصول القديم؟
حصل عليه مستخدم المنتدى بعد إرسال طلب POST ناجح إلى /v1/users/login.
هل ينبغي إتاحة API عبر الإنترنت؟
لا. أبقِها ضمن شبكة موثوقة أو خاصة، واستخدم مسار مصادقة حاليًا ومدعومًا.
هل يمكنني إنشاء تكامل مع Home Assistant؟
نعم، ولكن صمّمه للتعامل مع انتهاء صلاحية الرموز وتغيّر إصدارات API والوصول بأقل قدر من الصلاحيات.
