أدوات OpenAPI

أداة OpenAPI هي مستند Swagger أو OpenAPI واحد مستورد. تصبح واجهة API كاملة صفاً واحداً في أدوات مساحة العمل في مكتبة الأدوات، ويجد الوكيل العملية المناسبة داخلها أثناء المحادثة. استورد المستند مرة واحدة، بدلاً من بناء أداة Webhook لكل عملية على حدة.

ما تحتاج إليه

• مستند Swagger أو OpenAPI بصيغة JSON، سواء كان ملفاً أو رابطاً عاماً بـ HTTPS. لا يُقبل YAML.
• الرابط الأساسي الذي تُخدَم منه واجهة API فعلاً. هو مطلوب، وإليه تذهب كل الاستدعاءات.
• عضوية في مساحة العمل. الاستيراد لا يحتاج إلى صلاحية إضافية.
• أي بيانات اعتماد تطلبها واجهة API، تحفظها أولاً كـاتصال مصادقة.

الخطوات

الخطوة 1: افتح نموذج الاستيراد

في الوكيل، انتقل إلى تبويب الأدوات واضغط إضافة أداة، ثم اختر تبويب OpenAPI. النافذة نفسها موجودة في صفحة مكتبة الأدوات، وتصفها هناك بالعبارة «أنشئ وأدر أدوات قابلة لإعادة الاستخدام في مساحة عملك.»

الخطوة 2: سمِّ الأداة

الاسم مطلوب، ويجب أن يكون فريداً في مساحة العمل، وبحد أقصى 120 حرفاً. هو الصف الذي تراه في المكتبة، لذا سمِّه باسم واجهة API نفسها، لا باسم إحدى عملياتها.

الخطوة 3: أعطِ المستند

يختار تبويبان على شكل أزرار المصدر، وتستخدم واحداً منهما فقط.

رفع ملف Json يفتح منطقة إفلات تقرأ «أفلت ملفاً هنا أو اضغط للتصفح»، وتحتها «حتى 5 ميجابايت لكل ملف». يُقرأ الملف في متصفحك قبل إرسال أي شيء، فيُكتشف الملف السيئ فوراً.

من رابط يأخذ رابط HTTPS عاماً يشير إلى المستند. يجلب إيكونوڤا المستند بالقواعد نفسها التي تطبق على أي استدعاء خارجي: HTTPS فقط، ومضيفات عامة فقط، وJSON فقط، وبحد أقصى 5 ميجابايت، ومهلة 30 ثانية.

الخطوة 4: حدّد عنوان الأساس

عنوان الأساس مطلوب. التلميح تحته يوضح السبب: «رابط الأساس مطلوب — البوابة تستخدمه لاستدعاء الـ API.»

يبقى الحقل servers في المستند كخيار احتياطي، لكن القيمة التي تكتبها هي التي تستخدمها كل الاستدعاءات. لذلك لن يرسل مستندٌ يشير servers فيه إلى بيئة تجريبية حركة مرور إليها بصمت.

يجب أن تكون القيمة رابط HTTPS عاماً كاملاً، يطابق المثال https://api.example.com. تُحذف الشرطة المائلة في النهاية إن وُجدت.

الخطوة 5: اضغط الاستيراد

اضغط استيراد نقاط النهاية؛ يظهر معه عدد النقاط المختارة من إجماليها. يقرأ إيكونوڤا المستند وينشئ صف المكتبة، ويظهر الصف مع شريحة عدد نقاط النهاية وشارة الحالة.

للحصول على أفضل نتيجة

يجد الوكيل العملية بمطابقة ما قاله المتصل مع وصف العملية، لذا هذا الوصف هو ما يحدد هل تُستدعى العملية أصلاً. اكتبه بكلام المتصل، لا بكلام واجهة API.

الموصى به

Check where a customer's order is. Use when the caller asks about delivery, a
missing parcel, a tracking number, or when an order will arrive.

الأقل فاعلية

GET /v2/orders/{orderId}/shipment-status

ماذا يحدث بعد ذلك

تظهر الأداة في أدوات مساحة العمل مع اسم واجهة API وعدد نقاط النهاية وشارة الحالة. اخترها على وكيل بالطريقة نفسها التي تختار بها أي أداة في مساحة العمل، ويستطيع الوكيل الوصول إلى عملياتها من المحادثة التالية.

افتح الصف لترى ما تم استيراده. تعرض صفحة التفاصيل كل عملية في تبويب نقاط النهاية، في شريط على اليسار، وتعرض على اليمين معاملات العملية المختارة وجسم طلبها. يُشرح هذا التبويب، وأوضاع المصادقة لكل عملية، ومفتاح التفعيل، في صفحة عمليات أداة OpenAPI.

حالات الاستيراد الثلاث

عادةً تكون الأداة جاهزة عند إغلاق النافذة. وطالما تُظهر أي أداة في القائمة شارة جارٍ الاستيراد، تحدّث الصفحة القائمة وحدها حتى تنتهي كلها. وقد تتحول أداة إلى فشل بعد أن ظهرت أول مرة، ويُعرض السبب على الصف.

ويمكن أن يفشل الاستيراد قبل إنشاء أي صف، وهذه هي الحالة الشائعة: مستند لا يمكن قراءته، أو رابط لا يستجيب، أو اختيار يتجاوز حد العمليات. عندها لا يُحفظ شيء، وتعرض النافذة الخطأ.

كيف يصل الوكيل إلى العملية

لا تُعرض واجهة API المستوردة على الوكيل كقائمة عمليات. أدوات Webhook والتكامل والنظام أمامه في كل دور، أما العمليات المستوردة فلا. في كل دور يبحث الوكيل في عملياتك المستوردة عن الأقرب إلى ما قاله المتصل للتو، ويحتفظ بأعلى 5 نتائج، ويتجاهل أي نتيجة تقل درجتها عن 0.5.

ولهذا تعمل واجهة API الكبيرة. مستند فيه مئتا عملية سيُغرق الوكيل لو عُرضت كلها، فيرى حفنة من العمليات المناسبة، ويطرح سؤالاً توضيحياً عندما لا تتجاوز أي عملية الحد.

ويغيّر هذا معنى الاستدعاء الذي لم يحدث. أداة Webhook لا تُطلق تعني أن وصف الأداة يحتاج إلى تعديل في صياغته. أما العملية المستوردة فيجب أن تفوز في البحث أولاً، لذلك قد تفوتها المطابقة أيضاً إذا لم تظهر عبارة المتصل في وصف العملية أبداً.

تُبحث أسئلة قواعد البيانات في المرور نفسه، فإذا كان للوكيل قاعدة بيانات وواجهة API مستوردة معاً، فهو يختار بينهما في كل دور.

اختبار ما سيصل إليه الوكيل

افتح الأداة من تبويب الأدوات في الوكيل، ثم افتح تبويب الاختبارات فيها. اكتب ما قد يقوله المتصل واضغط تشغيل. يشرح التلميح الغرض: «اكتب ما قد يقوله المتصل. يُشغّل هذا البحث الدلالي نفسه الذي يجريه الوكيل في كل مرة، حتى تتمكن من اكتشاف أي تطابق غير صحيح قبل إطلاقه.»

تُرتَّب النتائج بدرجة، وهي تشابه لا احتمال. ولا يُعد عدم وجود نتيجة فوق الحد نتيجةً أيضاً: «لا يوجد تطابق يتجاوز الحد الأدنى المحدد. سيطرح الوكيل سؤالاً توضيحياً بدلاً من استدعاء نقطة نهاية.»

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

تحديث مستند تغيّر

تحتفظ الأداة المستوردة بالعمليات التي أُنشئت بها. والمستند الذي يضيف عملية أو يحذفها أو يعيد تسميتها يحتاج إلى استيراد جديد:

1. استورد المستند الجديد كأداة جديدة.
2. اخترها على الوكلاء الذين يحتاجونها.
3. تحقق منها في تبويب الاختبارات الخاص بها.
4. احذف الصف القديم.

الحذف يزيل الأداة وعملياتها ويلغي اختيارها من كل وكيل استخدمها، لذلك افعله آخراً. اتصال المصادقة قابل لإعادة الاستخدام ولا يُحذف مع الأداة.

هناك تغييران لا يحتاجان إلى استيراد جديد: إيقاف عملية ثم تشغيلها من جديد، وتغيير بيانات الاعتماد التي تستخدمها الأداة.

الحدود

حل المشكلات

«يجب ألا يتجاوز ملف OpenAPI 5 ميجابايت.»

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

«اختر مستند OpenAPI بصيغة JSON.» أو «الملف المحدد ليس كائن OpenAPI صالحاً.»

الملف ليس JSON، أو هو JSON لكنه ليس كائناً، مثل مصفوفة. حوّل مستند YAML إلى JSON أولاً.

"The URL did not return a JSON OpenAPI document"

الرابط أجاب، لكن النص لم يكن كائن JSON. أشر إلى المستند الخام، لا إلى صفحة توثيق تعرضه.

"Fetching the OpenAPI document failed with status 404"

الرابط أجاب بحالة غير ناجحة، وتظهر الحالة في الرسالة. يُجلب الرابط بدون أي بيانات اعتماد، لذلك إذا كان المستند خلف مصادقة فيجب رفعه كملف بدلاً من ذلك.

"Fetching the OpenAPI document failed or timed out"

المضيف لم يجب خلال 30 ثانية، أو أنه غير متاح للعامة عبر HTTPS.

"Base URL is required"

الحقل كان فارغاً أو مسافات فقط. لا يمكن استيراد واجهة API بدون معرفة المكان الذي تُستدعى منه.

"This import would persist 2400 operations, which exceeds the 2000-operation limit"

المستند أكبر من أن تحتفظ به أداة واحدة. استورد مستنداً يغطي مسارات أقل. استيراد جزء من عمليات المستند غير متاح من البوابة حالياً.

الصف يعرض «فشل»

افتحه واقرأ السبب تحت فشل الاستيراد. تبقى الأداة في المكتبة وتظل قابلة للاختيار، لكن الوكيل لا يستطيع الوصول إلى أي من عملياتها. أصلح المستند واستورده من جديد.

الأسئلة الشائعة

هل كل استيراد يساوي أداة واحدة؟

نعم. يصبح المستند الواحد صفاً واحداً في المكتبة يحمل واجهة API كاملة، ولا يمكن لمستند كبير أن يتجاوز حجم ذلك الصف.

هل تُستورد كل العمليات؟

نعم. استيراد جزء من عمليات المستند غير متاح من البوابة حالياً. ولإيقاف الوكيل عن استدعاء عملية بعد الاستيراد، أوقف تلك العملية.

هل يستطيع الوكيل استدعاء واجهة API عبر HTTP العادي؟

لا. الرابط الأساسي ورابط المستند وكل استدعاء خارجي يعملون عبر HTTPS فقط، ومع مضيفات عامة فقط.

هل يُحفظ المستند؟

تُحفظ العمليات التي قرأها إيكونوڤا، مع معاملاتها وحقول جسم طلبها، حتى تعرض صفحة التفاصيل العقد دون الرجوع إلى المستند. وحذف الأداة يزيلها.

لماذا يطرح الوكيل سؤالاً توضيحياً بدلاً من استدعاء واجهة API؟

لم تتجاوز أي عملية الحد في ذلك الدور. شغّل الجملة نفسها في تبويب الاختبارات الخاص بالأداة. إذا كانت درجتها أقل من الحد، فوصف العملية هو ما يجب تعديله.

هل أستطيع تغيير الرابط الأساسي لاحقاً؟

الرابط الأساسي يُثبَّت عند الاستيراد. لنقل واجهة API إلى مضيف آخر، استورد المستند من جديد كأداة جديدة، واخترها على الوكلاء الذين يحتاجونها، ثم احذف الصف القديم.

صفحات ذات صلة

• عمليات أداة OpenAPI: المصادقة لكل عملية، والقيم الثابتة، والمفاتيح
• اختبار الاسترجاع: تحقق من العملية التي تصل إليها عبارة المتصل
• اتصالات المصادقة: بيانات الاعتماد التي ترسلها هذه الأداة
• أدوات Webhook: الشكل المناسب لنقطة نهاية واحدة
• نظرة عامة على الأدوات: الفرق بين الأنواع الأربعة