ALGO RESTful API

معلومات المنتج: دليل RESTful API

تسمح واجهة برمجة تطبيقات Algo RESTful للمستخدمين بالوصول إلى الإجراءات ومعالجتها وتشغيلها على Algo IP Endpoints على شبكتهم من خلال طلبات HTTP/HTTPS. يوفر هذا المستند مجموعة موحدة ومحددة مسبقًا من العمليات عديمة الحالة التي يمكن استخدامها للتفاعل مع أجهزة Algo. تدعم واجهة برمجة التطبيقات طلبات HTTP/HTTPS GET وPOST وPUT مع حمولات JSON.

المصادقة

هناك ثلاثة أنواع من المصادقة المتاحة مع Algo RESTful API:

• المصادقة القياسية (ممكّنة افتراضيًا)
• المصادقة الأساسية (اختياري)
• لا توجد طريقة مصادقة (غير مستحسن؛ فقط لأغراض الاختبار)

تعليمات استخدام المنتج: RESTful API

المتطلبات الأساسية

قبل تمكين RESTful API، تأكد من أن الجهاز لديه اتصال بالإنترنت للوصول إلى خوادم NTP التي تم تكوينها مسبقًا. في حالة عدم توفر اتصال بالإنترنت، قم بتكوين خادم NTP محلي وأدخل عنوان IP الخاص به.

تمكين RESTful API

1. قم بتسجيل الدخول إلى ملف web الواجهة وانتقل إلى علامة التبويب Advanced Settings Admin.
2. قم بالتمرير لأسفل إلى قسم دعم واجهة برمجة التطبيقات (API) وقم بتمكين RESTful API.
3. قم بتعيين كلمة المرور المطلوبة (كلمة المرور الافتراضية: algo). لاحظ أن المصادقة القياسية ممكّنة بشكل افتراضي.

تمكين المصادقة الأساسية (اختياري)

1. في web واجهة ، انتقل إلى علامة التبويب صيانة النظام وقم بتنزيل التكوين file.
2. افتح التكوين file باستخدام أي محرر نصوص وأضف السطر التالي: api.auth.basic = 1
3. حفظ وتحميل التكوين المعدل file العودة إلى الجهاز باستخدام استعادة التكوين File ميزة في علامة التبويب صيانة النظام.

عدم تمكين أي أسلوب مصادقة (اختياري)

لتمكين طريقة عدم المصادقة ، اترك حقل RESTful API Password فارغًا. هذه الطريقة غير موصى بها ويجب استخدامها فقط لأغراض الاختبار فقط لأنها لا توفر أي أمان.

تمكين واجهة تحكم بسيطة (اختياري)

1. على web واجهة ، انتقل إلى علامة التبويب صيانة النظام وقم بتنزيل التكوين file.
2. افتح التكوين file باستخدام محرر النصوص وإضافة سطرين. قم بتغيير كلمة المرور إلى رغبتك.
3. مسؤل.web.العلم = 1
4. Sci.admin.pwd =
5. حفظ وتحميل التكوين المعدل file العودة إلى الجهاز باستخدام استعادة التكوين File ميزة في علامة التبويب صيانة النظام.

المصادقة Sampلو كود

يرجى إرسال بريد إلكتروني support@algosolutions.com إذا كنت ترغب في الحصول على مصادقة قياسية أو أساسيةampالرمز.
للحصول على دعم إضافي، اتصل 604-454-3792 أو البريد الإلكتروني support@algosolutions.com

إشعارات المعلومات

ملحوظة
تشير الملاحظة إلى التحديثات والمعلومات والتعليمات المفيدة التي يجب اتباعها

تنصل

يُعتقد أن المعلومات الواردة في هذا المستند دقيقة من جميع النواحي ولكن لا تضمنها شركة Algo. تخضع المعلومات للتغيير دون إشعار مسبق ولا ينبغي تفسيرها بأي شكل من الأشكال على أنها التزام من جانب Algo أو أي من الشركات التابعة لها أو الشركات التابعة لها. لا تتحمل شركة Algo والشركات التابعة لها والشركات التابعة لها أي مسؤولية عن أي أخطاء أو سهو في هذه الوثيقة. قد يتم إصدار مراجعات لهذه الوثيقة أو إصدارات جديدة منها لدمج هذه التغييرات. لا تتحمل Algo أي مسؤولية عن الأضرار أو المطالبات الناتجة عن أي استخدام لهذا الدليل أو هذه المنتجات و/أو البرامج و/أو البرامج الثابتة و/أو الأجهزة. لا يجوز إعادة إنتاج أي جزء من هذه الوثيقة أو نقله بأي شكل أو بأي وسيلة - إلكترونية أو ميكانيكية - لأي غرض دون الحصول على إذن كتابي من Algo.
للحصول على معلومات إضافية أو مساعدة فنية في أمريكا الشمالية، يرجى الاتصال بفريق دعم Algo:

Algo الدعم الفني
1-604-454-3792
support@algosolutions.com

©2022 Algo هي علامة تجارية مسجلة لشركة Algo Communication Products Ltd.
كل الحقوق محفوظة. جميع العلامات التجارية الأخرى هي ملك لأصحابها. جميع المواصفات عرضة للتغيير دون إشعار.

 عام

مقدمة

يصف هذا المستند كيف يمكن استخدام Algo RESTful API للوصول إلى الإجراءات ومعالجتها وتشغيلها على Algo IP Endpoints على شبكتك من خلال طلبات HTTP/HTTPS، بالإضافة إلى طريقتين مختلفتين للمصادقة بمستويات مختلفة من الأمان. يمكن أن تتفاعل الأنظمة الطالبة مع أجهزة Algo من خلال مجموعة موحدة ومحددة مسبقًا من العمليات عديمة الحالة المحددة في هذه الوثيقة. يتم تقديم الطلبات إلى URI الخاص بالمورد باستخدام حمولة JSON وتستدعي استجابة JSON. يتم إجراء طلبات HTTP/HTTPS GET وPOST وPUT على URI للمورد بالإضافة إلى حمولة JSON (راجع قسم الأوامر للحصول على قائمة الحمولات).

 المصادقة

هناك ثلاثة أنواع من المصادقة:

•  قياسي (مستحسن)
•  أساسي
•  لا شيء (غير مستحسن)

تستخدم المصادقة القياسية رمز مصادقة الرسائل المستند إلى التجزئة (HMAC) مع ملخص مشفر SHA-256. تستخدم المصادقة الأساسية ترميز Base64 ويجب استخدامها فقط عبر HTTPS. لا ينبغي استخدام أي مصادقة إلا بحذر شديد لأنها لا توفر أي مصادقة. راجع قسم متطلبات المصادقة لمزيد من التفاصيل.

الإعداد والتكوين

المتطلبات الأساسية

•  يفترض هذا المستند أن نقطة نهاية Algo تعمل بإصدار البرنامج الثابت 3.3 أو أعلى.
•  يجب أن يكون الفارق الزمني بين الطالب وأجهزة Algo أقل من 30 ثانية لاستخدام المصادقة القياسية.
• تأكد من استخدام NTP (بروتوكول وقت الشبكة). يمكن تكوين عناوين خوادم NTP المخصصة في الإعدادات المتقدمة → علامة التبويب الوقت.

ملحوظة
تتم استضافة خوادم NTP التي تم تكوينها مسبقًا بشكل عام، وبالتالي يلزم الاتصال بالإنترنت للوصول إليها. في حالة عدم توفر اتصال بالإنترنت، قم بتكوين خادم NTP محلي وأدخل عنوان IP الخاص به.

• تأكد من ضبط وقت نظام جهاز Algo على المنطقة الزمنية الصحيحة. يمكن القيام بذلك عن طريق الانتقال إلى الإعدادات المتقدمة → علامة التبويب الوقت.

 تمكين RESTful API

1. تسجيل الدخول إلى web الواجهة وانتقل إلى الإعدادات المتقدمة → علامة التبويب المسؤول.
2. قم بالتمرير لأسفل إلى قسم دعم API، وقم بتمكين RESTful API وقم بتعيين كلمة المرور حسب الرغبة (كلمة المرور الافتراضية: algo)
   ملحوظة
   يتم تمكين المصادقة القياسية بشكل افتراضي.

تمكين المصادقة الأساسية (اختياري)

1. في web واجهة، انتقل إلى علامة التبويب النظام → الصيانة وقم بتنزيل التكوين file.
2. افتح التكوين file باستخدام أي محرر نصوص وأضف السطر التالي: api.auth.basic = 1
3.  حفظ وتحميل التكوين المعدل file العودة إلى الجهاز باستخدام استعادة التكوين File الميزة في علامة التبويب النظام → الصيانة.

لا توجد طريقة مصادقة (اختياري)

لتمكين طريقة عدم المصادقة ، اترك حقل RESTful API Password فارغًا. هذه الطريقة غير موصى بها ويجب استخدامها فقط لأغراض الاختبار فقط لأنها لا توفر أي أمان.

تمكين واجهة تحكم بسيطة (اختياري)

1. على web واجهة، انتقل إلى علامة التبويب النظام → الصيانة وقم بتنزيل التكوين file.
2.  افتح التكوين file باستخدام محرر النصوص وإضافة سطرين. غير ال إلى كلمة المرور التي تريدها. مسؤل.web.العلم = 1
   Sci.admin.pwd =
3.  حفظ وتحميل التكوين المعدل file العودة إلى الجهاز باستخدام استعادة التكوين File الميزة في علامة التبويب النظام → الصيانة.

متطلبات المصادقة

يرجى إرسال بريد إلكتروني support@algosolutions.com إذا كنت ترغب في الحصول على مصادقة قياسية أو أساسيةampالرمز.

طلب المصادقة القياسي مع حمولة JSON

الرؤوس المطلوبة في طلب HTTP/HTTPS
> نوع المحتوى: "application/json"
> المحتوى-MD5: [content_md5] مثالample
Content-MD5: 74362cc86588b2b3c5a4491baf80375b

التفويض: مسؤول hmac:[nonce]:[hmac_output]
تتكون رؤوس التفويض من:

1. السلسلة "hmac admin" متبوعة بنقطتين ':'.
2. Nonce – قيمة عشوائية أو غير متكررة، متبوعة بنقطتين ':'.
3. Hmac_output - تم إنشاؤه بواسطة كلمة مرور RESTful API (المفتاح السري) التي تم تكوينها على جهازك وإدخال HMAC، كما هو موضح أدناه:
   [request_method]:[request_uri]:[content_md5]:[content_type]:[timestamp]:[مرة واحدة]

مدخلات HMAC على سبيل المثالample: (باستخدام "algo" كمفتاح سري)
POST:/api/controls/tone/start:6e43c05d82f71e77c586e29edb93b129:application/json:1601312252:49936 أنشئ HMAC باستخدام كلمة المرور وسلسلة إدخال HMAC كملخص باستخدام SHA-256:
إخراج HMAC على سبيل المثالample: 2e109d7aeed54a1cb04c6b72b1d854f442cf1ca15eb0af32f2512dd77ab6b330

التاريخ: اليوم، التاريخ، الشهر، السنة، الساعة:الدقيقة:الثانية بتوقيت جرينتش
Example
التاريخ: الخميس 22 سبتمبر 2022 02:33:07 بتوقيت جرينتش
المصادقة القياسية مع الحمولة على سبيل المثالampعلى:

 طلب المصادقة القياسي بدون حمولة JSON

مطابق للإصدار 3.1 مع حذف الرؤوس/مدخلات hmac ذات الصلة بالمحتوى.
إدخال HMAC: [request_method]:[request_uri]:[timestamp]: [nonce] مدخلات HMAC على سبيل المثالample: (باستخدام "algo" كمفتاح سري)
الحصول على:/api/settings/audio.page.vol:1601312252:49936
قم بإنشاء HMAC باستخدام كلمة المرور وسلسلة إدخال HMAC باستخدام SHA-256:
إخراج HMAC على سبيل المثالample: c5b349415bce0b9e1b8122829d32fbe0a078791b311c4cf40369c7ab4eb165a8
المصادقة القياسية دون حمولة على سبيل المثالampعلى:

 طلب المصادقة الأساسية

يجب استخدام طريقة المصادقة هذه بعناية لأنها أقل أمانًا من الطريقة القياسية.

التفويض: أساسي [base64]
Exampعلى:
التفويض: YWRtaW46YWxnbwo = الأساسي
المصادقة الأساسية على سبيل المثالampعلى:

الأوامر

 أوامر RESTful API

فيما يلي قائمة بجميع أوامر API المدعومة.

ملحوظة
يتغير طلب PUT أو ينشئ موردًا دائمًا ينجو من إعادة التشغيل، بينما يتحكم طلب POST في الجهاز للجلسة الحالية فقط.

وصف	طريقة	عنوان URL	الحمولة حدود	يعود Example	منتج	FW
استرجع قيمة معلمة معينة.	يحصل	/ api / settings / [اسم المفتاح] Ex./api/settings/audio.page.vol	غير متاح	{"audio.page.vol": "-18 ديسيبل"}	الجميع	> 3.3
إرجاع مستوى الضوضاء المحيطة المقاسة بالديسيبل. يجب تمكين تعويض الضوضاء المحيطة في الإعدادات الأساسية -> علامة تبويب الميزات.	يحصل	/api/info/audio.noise.level	غير متاح	{"audio.noise.level": 72}	مكبرات الصوت عرض مكبرات الصوت	> 3.3
استخرج حالة محطة إدخال الترحيل.	يحصل	/api/info/input.relay.status	غير متاح	{"input.relay.status": "خامل"} أو {"input.relay.status": "نشط"}	جميع المنتجات ذات مدخل الترحيل، باستثناء 8063. انظر أدناه.	> 4.1
استخرج حالة طرفي الإدخال 1 أو الإدخال 2.	يحصل	/api/info/input.relay1.status أو /api/info/input.relay2.status	غير متاح	{"input.relay1.status": "خامل"} أو {"input.relay1.status": "نشط"}	8063	> 4.1
استرجع قائمة النغمات fileمثبتة حاليا.	يحصل	/ api / info / tonelist	غير متاح	{"tonelist":["bell-na.wav"،"bell uk.wav"،"buzzer.wav"،...]}	الجميع	> 5.0
قم باسترجاع معلومات الجهاز التي يتم عرضها على صفحة الحالة.	يحصل	/ api / info / status	غير متاح	القائمة الكاملة للمعلومات من علامة التبويب الحالة.	الجميع	> 5.4

استرجع معلومات المنتج التي يتم عرضها في صفحة "حول".	يحصل	/api/info/about	غير متاح	جميع المعلومات موجودة في علامة التبويب حول.	الجميع	> 5.4
قم بتنشيط الستروب باستخدام معلمات اللون والنمط المرغوبة.	بريد	/ api / الضوابط / القوية / البدء	النمط: {0 - 15} اللون 1: {أزرق، أحمر، كهرماني، أخضر} اللون 2: {أزرق، أحمر، كهرماني، أخضر} اللون: {1 – 255} الاحتفاظ: {صحيح ، خطأ}	غير متاح	8128 (خ 2) 8138 8190 ثانية	> 3.3
وقف القوية.	بريد	/ api / الضوابط / القوية / التوقف	غير متاح	غير متاح	8128 (خ 2) 8138 8190 ثانية	> 3.3
قم بتشغيل نغمة مرة واحدة أو تكرارها.	بريد	/ api / الضوابط / نغمة / بدء	المسار: {نغمة} أي. chime.wav الحلقة: {true، false} أو {0، 1} على سبيل المثال ، {"path": "chime.wav"، "loop": true}	غير متاح	المتحدثون 8301 8373 8028 (خ 2) 8201 8039	> 3.3
توقف عن النغمة.	بريد	/ api / الضوابط / لهجة / توقف	غير متاح	غير متاح	المتحدثون 8301 8373 8028 (خ 2) 8201 8039	> 3.3
اتصل برقم الهاتف الداخلي برسالة مسجلة مسبقًا.	بريد	/ api / controls / call / start	{"الامتداد":"2099"، “نغمة”:”gong.wav”، “فاصل زمني”:”0″، “maxdur”:”10″}	غير متاح	المتحدثون 8301 8410 8420	> 3.3
إنهاء المكالمة.	بريد	/ api / الضوابط / الاتصال / التوقف	غير متاح	غير متاح	المتحدثون 8301 8410 8420	> 3.3

ابدأ مكالمة أحادية الاتجاه. سيتلقى الجهاز دفق الصوت من الامتداد الهدف.	بريد	/api/controls/call/page	{"امتداد":" "}	غير متاح	المتحدثون 8410 8420	> 5.3.4
أعد تمهيد نقطة النهاية الهدف.	بريد	/api/controls/reboot	غير متاح	غير متاح	الجميع	> 3.3
افتح الباب. يتحكم "محلي" في الترحيل المحلي يتحكم "netdc1" في وحدة تحكم باب الشبكة البعيدة (8063)	بريد	/api/controls/door/unlock	معرف الباب: {محلي، netdc1} *اختياري	غير متاح	8039 8028 (خ 2) 8201 8063	> 3.3
اقفل الباب.	بريد	/ api / الضوابط / الباب / القفل	معرف الباب: {محلي، netdc1} *اختياري	غير متاح	8039 8028 (خ 2) 8201 8063	> 3.3
قم بتمكين مرحل إخراج AUX 24 فولت.	بريد	API/controls/24v/enable	غير متاح	غير متاح	8063	> 5.0
قم بتعطيل مرحل مخرج AUX 24 فولت.	بريد	API/controls/24v/disable	غير متاح	غير متاح	8063	> 5.0
تمكين تتابع الإخراج.	بريد	/api/controls/relay/enable	غير متاح	غير متاح	8063	> 5.0
تعطيل تتابع الإخراج.	بريد	/api/controls/relay/disable	غير متاح	غير متاح	8063	> 5.0
تحقق من خادم البرنامج الثابت الخاص بـ Algo للحصول على أحدث إصدار من البرنامج الثابت.	بريد	/ api / الضوابط / الترقية / الاختيار	غير متاح	{"الإصدار": "محدث"} أو {"إصدار": " "}	الجميع	> 4.1
تحقق من خادم البرامج الثابتة الخاص بـ Algo للحصول على أحدث إصدار للبرنامج الثابت وقم بالترقية إلى هذا الإصدار.	بريد	/ api / الضوابط / الترقية / البدء	غير متاح	{"الحالة": "محدث"} أو {"الحالة": "الترقية "،"url": url>} أو {"حالة": " "}	الجميع	> 4.1
اعرض صورة أو نقشًا على الشاشة.	بريد	/api/controls/screen/start	يرى أقل	غير متاح	8410 8420	> 5.3.4
قم بإيقاف نمط الشاشة والعودة إلى الشاشة الافتراضية.	بريد	/api/controls/screen/stop	غير متاح	غير متاح	8410 8420	> 5.3.4

أعد تشغيل التطبيق الرئيسي.	بريد	/api/controls/reload	غير متاح	غير متاح	الجميع	> 5.3.4
ابدأ الاستماع إلى دفق صوتي مباشر. قم بتكوين رقم المنفذ الذي يتم إرسال الدفق إليه.	بريد	/api/controls/rx/start	{"ميناء": }	غير متاح	الجميع	> 5.3.4
توقف عن الاستماع إلى دفق صوتي مباشر.	بريد	/api/controls/rx/stop	غير متاح	غير متاح	الجميع	> 5.3.4
اضبط وضع الإرسال المتعدد.	يضع	/ api / state / mcast / update /	{"الوضع": "المرسل"، "العنوان": ، "ميناء": أو "النوع": "rtp"} أو {"الوضع": "المرسل"، "العنوان": ، "ميناء": ، "النوع":"بولي"، "المجموعة":1} ** ملاحظة **: إذا تم استخدام عناصر التحكم / النغمة / البدء قبل هذا الأمر ، فسيتم تشغيل النغمة باستخدام الإعدادات الحالية في web UI.	غير متاح	8301	> 5.0
أدخل قيمة لمعامل محدد من حمولة JSON.	يضع	/ api / الإعدادات	المعلمة: {القيمة} على سبيل المثال {"audio.page.vol": "-3dB"}	غير متاح	8180 (خ 2) 8186 8190 8190 ثانية 8301 8373	> 3.3

 أوامر واجهة التحكم البسيطة (SCI).

جميع أوامر SCI هي طلبات GET ولها المعلمات المشتركة "usi" و "admin" للمصادقة.
Exampعلى:
احصل على http:// /sci/controls/door/unlock?usr=admin&pwd=algo&doorid=local

وصف	عنوان URL	إضافي الحمولة حدود	منتجات	FW
افتح الباب. "محلي" يتحكم في المرحل المحلي "netdc1" يتحكم في وحدة تحكم باب الشبكة عن بعد (8063)	/ sci / controls / do or / unlock	معرف الباب: {محلي، netdc1} *اختياري	8039 8028 (خ 2) 8201 8063	> 3.3
اقفل الباب.	/ sci / controls / do or / lock	معرف الباب: {محلي، netdc1} *اختياري	8039 8028 (خ 2) 8201 8063	> 3.3
قم بتشغيل نغمة مرة واحدة أو تكرارها.	/ sci / controls / to ne / start	المسار: {نغمة} أي. chime.wav الحلقة: {true، false} أو {0، 1}	الجميع	> 3.3
توقف عن النغمة.	/ sci / controls / to ne / stop	غير متاح	الجميع	> 3.3
قم بتنشيط الستروب باستخدام معلمات اللون والنمط المرغوبة.	/sci/controls/strobe/start	النمط: {0 – 15} اللون 1: {أزرق، أحمر، كهرماني، أخضر} color2: {أزرق ، أحمر ، كهرماني ، أخضر} ledlvl: {1 - 255} الاحتفاظ: {صحيح، خطأ}	8128 (خ 2) 8138 8190 ثانية	> 3.3
وقف القوية.	/sci/controls/strobe/stop	غير متاح	8128 (خ 2) 8138 8190 ثانية	> 3.3

المستندات / الموارد

	ALGO RESTful API [بي دي اف] دليل المستخدم AL061-GU-GF000API-001-R0 ، AL061-GU-CP00TEAM-001-R0 ، RESTful API ، RESTful ، API
	ALGO RESTful API [بي دي اف] دليل المستخدم AL061-GU-CP000API-230717، واجهة برمجة تطبيقات RESTful، واجهة برمجة تطبيقات RESTful، API

مراجع

• دليل المستخدم