يمكنك إنشاء بوتات تتفاعل مع الخدمات الأخرى عبر واجهات برمجة التطبيقات (APIs). على سبيل المثال، يمكن للبوتات إرسال طلبات للتحقق من التوفر لتاريخ معين أو للعثور على منتج في متجر إلكتروني.
كيفية التفاعل مع واجهات برمجة التطبيقات التابعة لجهات خارجية باستخدام Dadata كمثال
لنأخذ واجهة برمجة تطبيقات لاقتراح العناوين كمثال: https://dadata.ru/api/suggest/address/ الرابط سيكون مختلفاً
اقرأ وثائق واجهات برمجة التطبيقات التابعة لجهات خارجية بعناية.
يرجى الملاحظة! تتطلب واجهات برمجة التطبيقات التابعة لجهات خارجية عناوين IP التي سيتم إرسال الطلبات منها: 158.160.49.208 – الموقع الإلكتروني.
في حقل "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}"}.
للحصول على نتيجة الطلب، املأ حقل "Saved values".
يظهر مثال على الطلب في الرسم التوضيحي أدناه.
كيفية حفظ القيم من المتغيرات
قد لا يكون الأمر واضحاً تماماً في المرة الأولى—تحتاج حقاً إلى تجربته بنفسك.
أولاً، أدخل #{custom_answer} في حقل "Answer". (يحتوي المتغير #{custom_answer} على الرد المستلم من الخادم المحدد في حقل "Response URL".)
قم بتشغيل كتلة الطلب لإرسال الطلب والحصول على الرد. يجب تحليل الرد المستلم، وتحتاج إلى إعداد المتغيرات التي سيتم استخراجها منه. لهذا، استخدم حقل "Saved Values".
دعنا نستعرض المثال الموصوف أعلاه.
أفضل طريقة لفهم كيفية التعامل مع البيانات في JSON هي من خلال المثال. كنتيجة لطلبنا، يبدو الرد المستلم في #{custom_answer} كما يلي:
{ "suggestions": [ { "value": "US Dollar", "unrestricted_value": "US Dollar", "data": { "code": "840", "strcode": "USD", "name": "US Dollar", "country": "United States" } } ] }
في حقل "Saved values"، أدخل VALUE -> VARIABLE:
suggestions|0|value->CurrencyType;
suggestions|0|data|code->CurrencyDigCode;
suggestions|0|data|strcode->CurrencyStrCode;
suggestions|0|data|country->CurrencyCountry
suggestions - مفتاح المصفوفة [{"value": "US Dollar", "unrestricted_value": "US Dollar", "data": {"code": "840", "strcode": "USD", "name": "US Dollar", "country": "United States"}}]
suggestions|0 - مفتاح العنصر الأول من المصفوفة {"value": "US Dollar", "unrestricted_value": "US Dollar", "data": {"code": "840", "strcode": "USD", "name": "US Dollar", "country": "United States"}}
suggestions|0|value - مفتاح القيمة "US Dollar"
أطول مفتاح في هذا JSON:
suggestions|0|data|strcode - مفتاح القيمة "USD"
يتم فصل المفاتيح بواسطة شريط عمودي (|). إذا كان عنصر JSON عبارة عن مصفوفة، فإنك تصل إلى عناصره بواسطة الفهرس، بدءاً من 0، ويتم كتابة ذلك أيضاً باستخدام شريط عمودي.
تحتاج إلى تكرار التسلسل الهرمي بأكمله. للراحة، يمكنك تصور JSON باستخدام تطبيق عارض JSON.
يتم فصل مستوى التسلسل الهرمي بواسطة شريط عمودي. أي أنك تحتاج إلى سرد جميع المفاتيح للوصول إلى القيمة، وفصلها بشريط عمودي.
إذا كان JSON يحتوي على مصفوفة، استخدم فهرس العنصر بدلاً من المفتاح، بدءاً من الصفر.
افصل التعبيرات للحصول على متغيراتنا بفاصلة منقوطة ;.
يتكون كل تعبير من المسار إلى البيانات في الرد واسم المتغير لحفظه فيه، مفصولين بـ ->.
يمثل استعلام البحث المسار في JSON إلى القيمة المطلوبة.
تطوير واجهة برمجة التطبيقات للبوتات
يدعم البوت طلبات GET و POST، وهي الأنواع الرئيسية المستخدمة في معظم واجهات برمجة التطبيقات العامة.
GET هو طلب يحدث عند النقر على رابط أو فتح عنوان URL في المتصفح. يتم تمرير المعلمات في هذا الطلب في عنوان URL.
صيغة تمرير المعلمات: بعد عنوان URL، ضع علامة استفهام ?، ثم افصل كل معلمة بعلامة العطف &. تتكون كل معلمة من اسم متبوعاً بـ = وقيمتها.
مثال على عنوان URL مع معلمة:
هنا، يتم تمرير معلمة واحدة q بقيمة "good music". يمثل %20 مسافة.
عند العمل مع المنشئ، يمكنك فقط استخدام مسافة—سيقوم البوت باستبدالها تلقائياً.
POST هو طلب يتم إرساله غالباً عند تقديم نموذج على موقع ويب. يتم إرسال المعلمات في نص الطلب. بينما يمكن أيضاً إرسالها في عنوان URL كما في طلبات GET، إلا أن هذا غير شائع. يمكن أن تكون المعلمات في النص بتنسيق JSON أو كأزواج مفتاح-قيمة. ترسل النماذج عادةً أزواج مفتاح-قيمة، بينما تستخدم واجهات برمجة التطبيقات غالباً JSON.
Request header - يمكنك إضافة رأس لكل طلب. غالباً ما يحدد تنسيق البيانات ومفاتيح الوصول. عادةً ما يُترك هذا الحقل فارغاً، ولكن في حالات نادرة، تحتاج إلى تضمين رمز API أو نوع طلب، على سبيل المثال، "Content-Type": "application/json".
JSON (JavaScript Object Notation، يُنطق عادةً /ˈdʒeɪsən/ JAY-sən) هو تنسيق لتبادل البيانات يعتمد على النص ومبني على JavaScript. مثل العديد من تنسيقات النص الأخرى، JSON سهل القراءة للبشر. للعمل مع واجهات برمجة التطبيقات في البوت، تحتاج إلى فهم هذا التنسيق، لأنه أساس جميع التفاعلات.
قبل المتابعة، اقرأ المقالات التالية:
https://www.json.org/json-ru.html
https://developer.mozilla.org/ru/docs/Learn/JavaScript/%D0%9E%D0%B1%D1%8A%D0%B5%D0%BA%D1%82%D1%8B/JSON
أيضاً، حاول إنشاء ملف JSON خاص بك على هذا الموقع:
ممارسة
يمكن تنفيذ الطلبات بواسطة الكتل والشروط. تم تصميم الطلبات الشرطية للتحقق مما إذا كان الحوار يمكنه اتباع فرع معين على الموقع. في هذه الحالة، يتم إرسال الطلب في كل مرة يتم فيها تقييم شرط الفرع. من ناحية أخرى، يتم تنفيذ الطلبات في الكتل فقط عندما يدخل الحوار في تلك الحالة.
قبل إنشاء طلب، تحتاج إلى اختيار نوعه:
تختلف POST-data و POST-JSON في كيفية إرسال المعلمات، كما ذكر سابقاً (إما بتنسيق JSON أو كأزواج مفتاح-قيمة). إذا اخترت JSON، يمكن إرسال المعلمات فقط في نص الطلب. سيظهر حقل إضافي لمعلمات POST بتنسيق JSON.
مهم! يجب كتابة المعلمات بتنسيق JSON فقط، لأن البوت يعمل حصرياً معه. لقد تدربت بالفعل على كتابة JSON.
يمكن تحليل الرد من الخادم وحفظه في متغيرات.
يمكنك تحليل الرد فقط إذا كان بتنسيق JSON.
يتم تسجيل المتغيرات المحفوظة في آخر نموذج غير مملوء. إذا تم إرسال النموذج عبر كتلة حمراء، يتم تجاهل المتغيرات. لذلك، إذا كنت بحاجة إلى حفظ هذه البيانات، قم بتمرير المتغيرات إلى نظام CRM عبر كتلة صفراء.
يمكنك أيضاً رؤية ما سجله البوت في المتغيرات في قسم "Leads".
تمرير المتغيرات ليس كسلسلة نصية
بشكل افتراضي، يجب أن تكون قيم المتغيرات سلاسل نصية بتنسيق "#{}"، ولكن في هذه الحالة، يتم إرسال المتغير كسلسلة نصية. لتمرير متغير كرقم، تحتاج إلى تعطيل التحقق من تنسيق المعلمة في إعدادات المشروع:
ثم يمكنك ببساطة استخدام اسم المتغير، على سبيل المثال: {"key": #{variable_name}}، حيث variable_name هو المتغير نفسه—بدون علامات اقتباس محيطة.
يُوصى بإعادة تمكين التحقق من التنسيق بعد تعيين المعلمات.