يمكنك إنشاء بوتات تتفاعل مع موارد أخرى عبر API. على سبيل المثال، يمكن للبوتات تلبية الطلبات مع إمكانية التحقق من إمكانية حجز موعد لتاريخ معين، أو العثور على منتج في متجر إلكتروني.
كيفية التعامل مع API تابع لجهة خارجية على مثال DaData
لنأخذ نصائح API من https://dadata.ru/api/suggest/address كمثال
اقرأ وثائق واجهات برمجة التطبيقات التابعة لجهات خارجية بعناية
افتح مشروعك في Mavibot وافتح الإعدادات المتقدمة في إعدادات الكتلة؛ هناك تحتاج إلى تغيير نوع الطلب إلى POST-json.
في حقل "URL request" أدخل عنوان URL التالي: https://suggestions.dadata.ru/suggestions/api/4_1/rs/suggest/address
في حقل "Request header" اكتب الرأس بتنسيق JSON:
{ "Content-Type": "application/json", "Accept": "application/json", "Authorization": "Token " + token }
في "JSON parameters" ضع الطلب نفسه - { "query": "#{CurrencyType}" }
للحصول على النتائج، ستحتاج أيضًا إلى ملء علامة التبويب "Stored values".
مثال على الطلب أدناه:
كيفية حفظ القيم من المتغيرات
لا ينجح الجميع في ذلك فورًا، حتى تحاول القيام بذلك بنفسك.
للبدء، اكتب #{custom_answer} في حقل الإجابة. (المتغير #{custom_answer} يحمل الإجابة التي تم الحصول عليها من الخادم المذكور في حقل "URL for an answer from the server")
قم بتشغيل الكتلة مع الطلب لإرسال الطلب والحصول على إجابة عليه. تحتاج إلى تحليل الرد وإعداد الوصول إلى المتغيرات فيه. لهذا، تحتاج إلى العمل مع علامة التبويب "Stored values".
دعنا نلقي نظرة على مثال لفهم العملية بشكل أفضل.
نتيجة لطلبنا #{custom_answer}، وصلت إجابة بالتنسيق:
{"suggestions": [{"value": "British pound", "unrestricted_value": "British pound", "data": {"code": "826", "strcode": "GBP", "name": "British pound", "country": "The UK"}}]}
الآن دعنا نكتب في حقل "Stored values" القيمة->المتغير الخاص بنا
suggestions|0|value->CurrencyType;
suggestions|0|data|code->CurrencyDigCode;
suggestions|0|data|strcode->CurrencyStrCode;
suggestions|0|data|country->CurrencyCountry
suggestions - مفتاح المصفوفة [{"value": "British pound", "unrestricted_value": "British pound", "data": {"code": "826", "strcode": "GBP", "name": "British pound", "country": "The UK"}}]
suggestions|0 - مفتاح العنصر الأول في المصفوفة {"value": "British pound", "unrestricted_value": "British pound", "data": {"code": "826", "strcode": "GBP", "name": "British pound", "country": "The UK"}}
suggestions|0|value - مفتاح القيمة "British pound"
أطول مفتاح في هذا JSON:
suggestions|0|data|strcode - مفتاح القيمة "GBP"
يتم فصل المفاتيح بالخط العمودي (|). إذا كان هناك مصفوفة في JSON، فإن الوصول إلى عنصرها يتم ترقيمه بدءًا من الرقم 0 ويتم كتابته أيضًا بالخط العمودي.
من الضروري تكرار كل التداخل. للراحة، يمكنك تصور JSON في تطبيق JSON-viewer.
يتم فصل مستويات التداخل بخطوط عمودية. لذلك تحتاج إلى سرد جميع المفاتيح مفصولة بالخط للوصول إلى القيمة.
إذا كان هناك مصفوفة في JSON، فبدلاً من المفتاح تحتاج إلى ذكر رقم العنصر بدءًا من 0.
افصل عبارات الحصول على المتغيرات بفاصلة منقوطة (;). تتكون العبارات من الرابط إلى البيانات في الرد واسم المتغير لحفظه فيه، مفصولة بالرموز -> (شرطة + قوس زاوية).
استعلام البحث هو، بطريقة ما، مسار في JSON إلى القيمة المطلوبة.
تطوير API للبوتات
لتطوير API، ستحتاج إلى استضافة سيكون عليها الأساس. إذا لم يكن لديك واحدة أو لم تكن خبيرًا في البرمجة، فيمكنك التواصل معنا وسنقوم بتطوير API للبوت الخاص بك ووضعه على استضافتنا. الاستضافة نفسها مجانية، ستدفع فقط مقابل التطوير.
لكن الآن القليل من النظرية.
يدعم البوت طلبات GET و POST، وهما النوعان الرئيسيان المستخدمان في معظم واجهات برمجة التطبيقات العامة.
GET هو طلب يحدث عند النقر على الرابط أو عند فتح الرابط في المتصفح. يتم نقل المعلمات في مثل هذا الطلب إلى URL-requests.
صيغة المعلمات المنقولة: بعد url هناك علامة استفهام (?) ثم يتم فصل كل معلمة بعلامة العطف (&). تتكون المعلمة من الاسم وقيمته بعد علامة المساواة (=). مثال على URL مع معلمة:
هنا يمكنك رؤية أن معلمة واحدة باسم "search_query" تتم مشاركتها وأن قيمتها هي "queen live aid". '+' هنا هي المسافة بين الكلمات؛ عند العمل مع برنامج التحرير يمكنك فقط ترك المسافات – سيقوم البوت بتغييرها بنفسه.
POST هو نوع من الطلبات يتم إرساله غالبًا عند ملء نموذج على موقع ويب. ينقل الطلب المعلمات في الجسم؛ بالطبع، يمكن مشاركتها بنفس طريقة GET ولكن نادرًا ما يتم ذلك بهذه الطريقة. يمكن أن تكون المعلمة في الجسم بتنسيق JSON أو كمفتاح-قيمة. كمفاتيح-قيم، تشارك المعلمات النماذج، تنسيق JSON هو الأكثر استخدامًا لـ API.
Request header. يمكن إضافة رأس/عنوان لكل طلب. يتم كتابة تنسيق البيانات المشتركة ومفاتيح الوصول فيه غالبًا. عادةً نترك علامة التبويب هذه فارغة، ولكن من الضروري وضع رمز API أو نوع الطلب "Content-type": "application/json" في حالات نادرة.
JSON - (JavaScript Object Notation) هو معيار مفتوح لتنسيق الملفات وتنسيق تبادل البيانات يستخدم نصًا يمكن قراءته بواسطة الإنسان لتخزين ونقل كائنات البيانات التي تتكون من أزواج سمة-قيمة ومصفوفات. للعمل مع API في البوتات، يجب أن تعرف هذا التنسيق، كل شيء مبني عليه.
قبل المتابعة، اقرأ المقالات التالية:
https://www.json.org/json-en.html
https://developer.mozilla.org/en-US/docs/learn/javascript/objects/json
وحاول أيضًا إنشاء ملف JSON الخاص بك على هذا الموقع:
التطبيق العملي
يمكن للكتل والشروط تلبية الطلبات. يتم إنشاء طلبات الشروط لفهم ما إذا كان الحوار يمكن أن يسير في مسار معين على الموقع أم لا. يحدث الطلب في هذه الحالة في كل مرة يتم فيها التحقق من شرط المسار. طلبات الكتل على العكس من ذلك يتم تشغيلها فقط عند حدوث الانتقال إلى الكتلة.
قبل إنشاء طلب، تحتاج إلى اختيار نوعه:
يتم تمييز POST-data و POST-json بطريقة نقل المعلمات كما هو مذكور أعلاه (تنسيق JSON أو كمفتاح-قيمة). إذا اخترت JSON، فيمكن نقل المعلمات في الطلب فقط. يتم فتح حقل إضافي للنشر: JSON POST-parameters. مهم! يجب كتابة المعلمات بتنسيق JSON فقط، البوت يعمل بهذه الطريقة فقط.
يمكن تحليل الرد من الخادم وحفظه في المتغيرات.
يمكنك تحليل الرد فقط إذا كان بتنسيق JSON.
تتم كتابة المتغيرات المحفوظة في آخر إرسال لم يتم ملؤه؛ إذا تم نقل الإرسال عبر كتلة حمراء، يتم إلغاء المتغيرات. لذلك إذا كنت بحاجة إلى حفظ البيانات، فأنت بحاجة إلى نقل المتغيرات عبر الكتلة الصفراء.
بالمناسبة، يمكنك رؤية ما كتبه البوت في المتغيرات في قسم Leads:
نقل البيانات ليس كسطر
بشكل افتراضي، تأتي قيمة المتغير بتنسيق #{} ولكنها تأتي كسطر. لجعل المتغير يُنقل كرقم، تحتاج إلى إيقاف تشغيل التحقق من تنسيق معلمات post-json.
ثم يمكنك فقط ذكر اسم المتغير، مثل {"key": #{variable_name}}، variable_name هو المتغير، لذلك بدون استخدام الأقواس.
بعد إعداد المعلمات، يوصى بإعادة تشغيل التحقق.