التعامل مع واجهة برمجة تطبيقات الخادم
التعامل مع واجهة برمجة تطبيقات الخادم
يمكن تعزيز قدرات استخدام TrueConf Server باستخدام واجهة برمجة التطبيقات RESTful المتاحة في جميع الإصدارات، بما في ذلك المجانية.
مبادئ عمل واجهة برمجة التطبيقات وOAuth 2.0
القسم API → OAuth2 مخصص لإدارة التطبيقات أو الخدمات التي تعمل مع TrueConf Server API. يتم إدارة الوصول وفقًا لبروتوكول التفويض OAuth 2.0، الذي يمكنك قراءة المزيد عنه في التوثيق الرسمي لـ RFC 6749، وكذلك في المربع أدناه.
الفكرة الأساسية لبروتوكول OAuth 2.0 تكمن في منح حقوق الوصول إلى API للتطبيقات الفردية (المعروفة باسم client في مصطلحات OAuth) مع نطاق وحقوق محدودة. يتيح هذا النهج إمكانية قطع الوصول إلى تطبيق معين أو مستخدمه إلى موارد الخادم في أي وقت. كما يسمح البروتوكول بالتفويض الآمن للتطبيقات الخارجية وتنفيذ الإجراءات على الخادم عبر API باسم المستخدم، دون أن يضطر المستخدم إلى مشاركة اسم المستخدم أو كلمة المرور الخاصة به مع التطبيق الخارجي (طريقة Authorization Code).
يجب على كل تطبيق طرف ثالث الحصول على رمز وصول (access token) نتيجة عملية التفويض على TrueConf Server بواسطة بروتوكول OAuth 2.0. التطبيقات التي تمتلك رمز وصول صالح يمكنها الوصول في أي وقت إلى واجهة برمجة التطبيقات TrueConf Server، والتي تم وصف قائمة استدعاءاتها في الوثائق. من خلال هذا القسم من لوحة التحكم، يمكن للمسؤول TrueConf Server التحكم ليس فقط في وصول التطبيقات الطرف الثالث، ولكن أيضًا في المفاتيح التي تم الحصول عليها من خلال هذه التطبيقات.
يتم عرض أمثلة على استخدام TrueConf API في مدونتنا.
بعد التفويض، تحصل التطبيق على رمز وصول (access token) له فترة صلاحية محدودة ويمكن أن يكون له نطاق خادم أو نطاق مستخدم. على سبيل المثال، يسمح نطاق الخادم بالحصول على بيانات حول أي مؤتمرات، بينما يسمح النطاق المستخدم فقط بالحصول على بيانات المؤتمرات التي يكون المستخدم فيها مشاركًا أو مالكًا. يتم تحديد النطاق وفقًا لنوع التفويض الذي اختاره مطور التطبيق الخارجي، بينما يتم تحديد مجموعة حقوق الوصول إلى موارد الخادم من قبل مدير الخادم.
يتطلب كل طلب لإنشاء مفتاح وصول تحديد معرف التطبيق (Application ID) وسر التطبيق (Secret). يمكن الحصول عليهما وتحديثهما عن طريق إنشاء التطبيق أو تعديله في هذا القسم. يتم إنشاء معرف التطبيق تلقائيًا ولا يمكن تغييره لاحقًا، على عكس سر التطبيق الذي يمكن إعادة توليده.
| طريقة المصادقة OAuth 2.0 | نطاق رؤية مفتاح الوصول | نتيجة التفويض |
|---|---|---|
| بيانات اعتماد العميل يحصل التطبيق على مفتاح وصول، نطاقه غير مقيد ببيانات مستخدم معين. لا يتطلب تفويضًا للمستخدم. يوصى باستخدامه فقط للتطبيقات الموثوقة. | غير محدودة. | يتم إصدار رمز وصول (access token) مع صلاحية لمدة ساعة واحدة. |
| بيانات اعتماد المستخدم (المعروفة أيضًا باسم تفويض بيانات اعتماد مالك المورد) للحصول على رمز الوصول، من الضروري إرسال اسم المستخدم وكلمة المرور الخاصة بالمستخدم، التي يتم الحصول عليها من جانب التطبيق. | مقيد بمجال رؤية المستخدم المخول. | يتم إصدار مفتاح وصول لمدة ساعة واحدة، بالإضافة إلى مفتاح تجديد الوصول (refresh token) لمدة 7 أيام. |
| رمز التفويض يتم إصدار مفتاح الوصول (access token) بعد أن يقوم المستخدم بتوثيق نفسه بشكل مستقل على الجانب. اسم المستخدم وكلمة المرور غير متاحين للتطبيق. | مقيد بمجال رؤية المستخدم المخول. | يتم إصدار مفتاح وصول لمدة ساعة واحدة، بالإضافة إلى مفتاح تمديد الوصول لمدة 7 أيام. |
| رمز التحديث تتيح طريقة التفويض هذه الحصول على رمز وصول جديد (access token) بناءً على رمز تجديد الوصول الحالي (refresh token). | مقيد بمنطقة رؤية المستخدم الذي تم منحه مفتاح تمديد الوصول. | يتم إصدار مفتاح وصول جديد لمدة ساعة واحدة. لا يمكن تحديثه باستخدام هذه الطريقة. |
وصف الأذونات
تعتمد إمكانيات تطبيق الطرف الثالث في التعامل مع واجهة برمجة التطبيقات (API) على الأذونات الممنوحة له.
تزداد قائمة الأذونات مع كل إصدار من API مع زيادة قدرات خادم مؤتمرات الفيديو. يمكنك الاطلاع على قائمة توافق API وإصدارات الخادم في وثائق API.
تحتوي وثائق TrueConf Server API على مجموعة الأذونات المطلوبة لكل طريقة لاستدعائها بنجاح.
لإضافة حق معين للقراءة/الكتابة لبعض الكيانات، يرجى اختيار هذا الحق صراحةً. على سبيل المثال، لكي يتمكن تطبيقك من قراءة قائمة المستخدمين، قم بتعيين users:read. لا يتضمن حق الكتابة تلقائياً حق القراءة.
ميزة اختيار الأذونات لـ API v3.x
إذا كان تطبيق OAuth يتطلب الوصول للقراءة والكتابة على حد سواء لبعض المعايير، فيمكنك بدلاً من تعيين الأذونات <permission>:read و <permission>:write تعيين إذن عام <permission> إذا كان ذلك متاحًا. على سبيل المثال، لكي يتمكن التطبيق من قراءة وتحرير حسابات مستخدمي الخادم، يمكنك بدلاً من اختيار كلا المربعين users:read و users:write تعيين واحد فقط users.
نموذج إنشاء تطبيق OAuth 2.0 جديد
لإضافة تطبيق OAuth 2.0:
اضغط Create a new application.
حدد معرّفه في الحقل Name. يُستخدم فقط للعرض في قائمة التطبيقات.
للتفويض باستخدام طريقة Authorization Code في الحقل Redirect URL، حدد عنوان URL الذي سيتم إعادة توجيه التطبيق إليه. بالنسبة لطرق التفويض الأخرى، يمكنك تحديد العنوان
https://localhost/. يتم تحديد نوع التفويض نفسه أدناه.في القائمة Grant types حدد طرق التفويض التي يجب أن تكون متاحة لتطبيق OAuth الخاص بك. يجب اختيار نوع واحد على الأقل.
في قائمة Permissions، حدد الأذونات اللازمة لتطبيقك.
احفظ التغييرات باستخدام الزر Create.
صفحة تحرير التطبيق
في صفحة التطبيق، بالإضافة إلى تعديل خصائصه، يمكنك أيضًا رؤية قائمة بمفاتيح الوصول التي حصل عليها مستخدمو هذا التطبيق. يمكنك في أي وقت حذف مفاتيح الوصول لمستخدمين محددين، مما سيمنعهم من الوصول إلى موارد الخادم عبر API.
يمكنك أيضًا Regenerate مفتاح التطبيق، وهو ما قد يكون مفيدًا لأغراض الأمان لقطع الوصول إلى الخادم لهذا التطبيق، وكذلك لجميع مستخدميه الجدد. يرجى ملاحظة أن مفاتيح الوصول وتجديد الوصول التي تم الحصول عليها باستخدام المفتاح القديم ستستمر في العمل حتى انتهاء صلاحيتها.
التوثيق المدمج لواجهة برمجة التطبيقات (API)
تتوفر التعليمات المدمجة لـ API v4 بدءًا من الإصدار 5.5.3 من الخادم وما بعده.
تحتوي تثبيتة الخادم الخاص بك بالفعل على وثائق مدمجة لتسهيل العمل مع API (كما هو الحال مع وثائق المسؤول هذه). لن يحتاج مطوروك إلى البحث عن تعليمات على الإنترنت، ويمكنهم إنشاء سكربتات وتطبيقات باستخدام API TrueConf Server حتى عند العمل في شبكة مغلقة (كـСПД).
وثائق API المدمجة متاحة عبر الرابط:
https://[server-address]/api/v4/docs/
حيث أن [server-address] هو عنوان IP أو عنوان FQDN الخاص بخادمك.
تدعم الوثائق المدمجة وضع اختبار أي طلب. للقيام بذلك:
قم بإنشاء رمز للتطبيق OAuth 2.0 مع الصلاحيات اللازمة (أو استخدم لأغراض الاختبار الرمز من القسم Web → Security).
حدد الرمز المميز في القسم Introduction ضمن الكتلة Bearer Token:
الآن سيتم حفظ هذه الرمزية داخل جلسة هذه الصفحة في المتصفح ويمكنك تنفيذ أي طلب عبر الزر Test Request:
سيتم حفظ الرمز الوارد في النقطة 1 لجميع الطلبات إذا تم تحديده في أي طلب قبل الإرسال:
عند تغيير اللغة على الصفحة أو تحديثها، سيتم نسيان رمز API المحدد للاختبارات وسيتعين إدخاله مرة أخرى. وقد تم تنفيذ ذلك لأغراض أمنية، حيث لا يتم حفظ الرمز في ملفات تعريف الارتباط.