التكامل مع واجهات API الخارجية
يعرض هذا المقال مثالًا لإنشاء روبوت يعمل مع واجهة API الداخلية Wilfire (ترسل وتستقبل المعلومات)
يمكنك إنشاء روبوتات تتفاعل مع موارد أخرى عبر واجهة برمجة التطبيقات (API). على سبيل المثال، يمكن للروبوتات تلبية الطلبات مع القدرة على التحقق مما إذا كان من الممكن إنشاء موعد في تاريخ معين، أو العثور على منتج في متجر إلكتروني.
كيفية التعامل مع واجهة برمجة تطبيقات جهة خارجية على مثال DaData
لنأخذ نصائح API من https://dadata.ru/api/suggest/address كمثال
اقرأ بعناية وثائق واجهات برمجة التطبيقات التابعة لجهات خارجية
افتح مشروعك في Salebot وافتح الإعدادات المتقدمة في إعدادات الكتلة؛ هناك تحتاج إلى تغيير نوع الطلب إلى POST-json.
في الحقل “طلب URL” أدخل عنوان URL التالي: https://suggestions.dadata.ru/suggestions/api/4_1/rs/suggest/address
في الحقل “رأس الطلب” اكتب الرأس بصيغة JSON:
{ "Content-Type": "application/json", "Accept": "application/json", "Authorization": "Token " + token }
في حقل “معاملات JSON” ضع في الطلب نفسه - { "query": "#{CurrencyType}" }
للحصول على النتائج ستحتاج أيضًا إلى تعبئة تبويب “القيم المخزنة”.
يوجد مثال على الطلب أدناه:
كيفية حفظ القيم من المتغيرات
ليس الجميع يفهمه فورًا، حتى تحاول القيام به بنفسك.
ابدأ بكتابة #{custom_answer} في حقل الإجابة. (المتغير #{custom_answer} يحتوي على الإجابة التي تم الحصول عليها من الخادم والمذكورة في حقل “URL لإجابة من الخادم”)
شغّل الكتلة التي تحتوي على الطلب لإرساله وللحصول على إجابة له. تحتاج إلى تحليل الرد وإعداد الوصول إلى المتغيرات فيه. لهذا، تحتاج إلى العمل مع تبويب “القيم المخزنة”.
لننظر في مثال لفهم العملية بشكل أفضل.
نتيجة لطلبنا #{custom_answer} جاءت إجابة بالشكل التالي:
{"suggestions": [{"value": "الجنيه الإسترليني", "unrestricted_value": "الجنيه الإسترليني", "data": {"code": "826", "strcode": "GBP", "name": "الجنيه الإسترليني", "country": "المملكة المتحدة"}}]}
الآن لنكتب في حقل “القيم المخزنة” الصيغة VALUE->VARIABLE الخاصة بنا
suggestions|0|value->CurrencyType;
suggestions|0|data|code->CurrencyDigCode;
suggestions|0|data|strcode->CurrencyStrCode;
suggestions|0|data|country->CurrencyCountry
suggestions - مفتاح المصفوفة [{"value": "الجنيه الإسترليني", "unrestricted_value": "الجنيه الإسترليني", "data": {"code": "826", "strcode": "GBP", "name": "الجنيه الإسترليني", "country": "المملكة المتحدة"}}]
suggestions|0 - مفتاح أول عنصر في المصفوفة {"value": "الجنيه الإسترليني", "unrestricted_value": "الجنيه الإسترليني", "data": {"code": "826", "strcode": "GBP", "name": "الجنيه الإسترليني", "country": "المملكة المتحدة"}}
suggestions|0|value - المفتاح إلى القيمة “الجنيه الإسترليني”
أطول مفتاح في هذا JSON:
suggestions|0|data|strcode - المفتاح إلى القيمة “GBP”
تُفصل المفاتيح بواسطة الخط العمودي (|). إذا كانت هناك مصفوفة في JSON، فإن الوصول إلى عنصرها يكون مرقّمًا، بدءًا من الرقم 0، ويُكتب أيضًا بواسطة الخط العمودي.
من الضروري تكرار كامل التداخل. وللراحة يمكنك تصور JSON في تطبيق JSON-viewer.
تُفصل مستويات التداخل بواسطة الخطوط العمودية. لذا تحتاج إلى سرد جميع المفاتيح مفصولة بالخط للوصول إلى القيمة.
إذا كانت هناك مصفوفة في JSON، فبدلًا من المفتاح تحتاج إلى ذكر رقم العنصر ابتداءً من 0.
افصل العبارات الخاصة بالحصول على المتغيرات برمز الفاصلة المنقوطة (;). تتكون العبارات من الرابط إلى البيانات في الإجابة واسم المتغير الذي سيتم حفظها فيه، وهما مفصولان بالرمزين -> (الشرطة + علامة الزاوية).
استعلام البحث هو، بطريقة ما، مسار داخل JSON إلى القيمة المطلوبة.
تطوير API للروبوتات
لتطوير API، ستحتاج إلى استضافة سيتم الاعتماد عليها. إذا لم يكن لديك واحدة أو لم تكن بارعًا في البرمجة، فيمكنك التواصل معنا وسنقوم بتطوير API لروبوتك ونستضيفه على خوادمنا. الاستضافة نفسها مجانية، وستدفع فقط مقابل التطوير.
لكن الآن قليل من النظرية.
يدعم الروبوت GET و POST طلبات، وهذه هي الأنواع الرئيسية المستخدمة في معظم واجهات API العامة.
GET هو طلب يحدث عند النقر على الرابط أو عند فتح الرابط في المتصفح. تُنقل المعلمات في مثل هذا الطلب إلى طلبات URL.
صياغة المعلمات المنقولة: بعد الرابط يوجد علامة استفهام (?) ثم يُفصل كل معلم بعلامة العطف (&). يتكون المعلم من الاسم وقيمته بعد علامة يساوي (=). مثال على URL يحتوي على معلم:
هنا يمكنك أن ترى أنه يتم تمرير معلم واحد باسم “search_query” وأن قيمته هي “queen live aid”. علامة ‘+’ هنا تمثل المسافة بين الكلمات؛ وعند العمل باستخدام برنامج التحرير يمكنك ببساطة ترك المسافات - وسيقوم الروبوت بتغييرها بنفسه.
POST هو نوع من الطلبات يُرسل غالبًا عند ملء نموذج على موقع إلكتروني. ينقل الطلب المعلمات في الجسم؛ وبالطبع يمكن تمريرها بالطريقة نفسها مثل GET، لكن هذا نادرًا ما يُفعل. يمكن أن تكون المعلمة في الجسم بصيغة JSON أو كزوج مفتاح-قيمة. كقيم مفتاح-قيمة، تكون المعلمات على شكل حقول، أما صيغة JSON فهي الأكثر استخدامًا لواجهة API.
رأس الطلب. يمكن لكل طلب أن يحتوي على رأس/عنوان مضاف. يُكتب فيه غالبًا تنسيق البيانات المنقولة ومفاتيح الوصول. عادةً نترك هذا التبويب فارغًا، لكنه مطلوب لإدخال API Token أو نوع الطلب “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، فيمكن نقل المعلمات في الطلب فقط. ويُفتح حقل إضافي لـ post: JSON POST-parameters. مهم! يجب كتابة المعلمات بصيغة JSON فقط، فالبوت يعمل بهذه الطريقة فقط.
يمكن تحليل الرد من الخادم وحفظه في المتغيرات.
لا يمكنك تحليل الرد إلا إذا كان بصيغة JSON.
تُكتب المتغيرات المحفوظة في آخر إرسال غير مُعبّأ؛ وإذا تم تمرير الإرسال عبر كتلة حمراء، تُلغى المتغيرات. لذا إذا كنت بحاجة إلى حفظ البيانات، فيجب تمرير المتغيرات عبر الكتلة الصفراء.
وبالمناسبة، يمكنك رؤية ما سجله الروبوت في المتغيرات في قسم Leads:
نقل البيانات ليس كسطر
افتراضيًا تأتي قيمة المتغير بصيغة #{} ولكن بعد ذلك تأتي كسطر. ولكي يتم نقل المتغير كرقم، تحتاج إلى إيقاف التحقق من صيغة معاملات post-json.
بعد ذلك يمكنك فقط ذكر اسم المتغير، مثل {"key": #{variable_name}}، وvariable_name هو المتغير، أي من دون استخدام الأقواس.
بعد إعداد المعلمات يُنصح بإعادة تشغيل التحقق.
Last updated