عمليات أداة OpenAPI

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

قائمة العمليات

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

الشريط قائمة مسطحة عنوانها «نقاط النهاية (N)»، وبجانبها عداد مثل «12 مفعّلة، 3 معطّلة»، وحقل بحث عنوانه «ابحث في نقاط النهاية». يعرض كل صف الطريقة والمسار والوصف ومفتاح التفعيل. وإذا لم تطابق التصفية أي شيء، تظهر الرسالة «لا توجد نقاط نهاية مطابقة للتصفية.» والعملية التي يعلّمها المستند بأنها تغيّر الحالة تعرض شارة مُعدِّلة في جزء العقد.

عند الضغط على صف، تفتح العقد الخاص به. يعرض المعاملات جدولاً بالأعمدة الاسم والموضع والنوع ومطلوب والوصف، ويظهر جسم الطلب تحت عنوان يحمل نوع محتواه، مثل جسم الطلب (application/json). وإذا لم تكن للعملية معاملات ولا حقول موثّقة، تظهر الرسالتان «لا توجد معاملات» و«لا توجد حقول موثّقة».

ما تحمله كل عملية

تُقرأ العقود على عمق مستوى واحد: يُتبع المرجع المحلي $ref مرة واحدة، ويُفضَّل application/json عندما تعلن العملية عدة أنواع لجسم الطلب، ويُتخطى الجزء الذي لا يمكن قراءته بدلاً من إفشال الاستيراد كله. العملية التي تعذّرت قراءة معاملاتها تُستورد وتعمل، لكن عقدها يظهر فارغاً. والأداة التي استُوردت قبل حفظ العقود تعرض «تفاصيل نقاط النهاية غير مخزّنة لهذه الأداة.»

أوضاع المصادقة

لكل أداة مستوردة اتصال مصادقة واحد لواجهة API كلها، يُختار عند الاستيراد. ويمكن لكل عملية أن تتجاوزه، وinherit هو الافتراضي.

يكتب العقد نتيجة الوضع على سطر عنوان العملية: auth: <name> لاتصال الأداة، وauth override: <name> لاتصال خاص بالعملية، وno auth عندما لا ينطبق أي منهما. وفي الواجهة العربية تظهر هذه العبارات كـ«المصادقة: <name>» و«تجاوز المصادقة: <name>» و«بدون مصادقة».

مهما كان الوضع، يصل الاتصال إلى واجهة API كـ header Authorization. هناك أربعة أنواع: basic، وbearer، وOAuth2 client credentials، وOAuth2 JWT. ويُكتب هذا الـ header في آخر الترتيب، فيحل محل أي header بالاسم نفسه كانت قيمة ثابتة قد ضبطته، ولا تُفرّق المقارنة بين الحروف الكبيرة والصغيرة في الأسماء.

لا تعرض نافذة الاستيراد وضعاً للمصادقة لكل عملية. كل عملية تستخدم اتصال الأداة، إلا إذا ضُبطت بطريقة أخرى عند الاستيراد.

القيم الثابتة للحقول

يمكن تثبيت حقل يعلنه المستند على قيمة لا يراها الوكيل أبداً. وهناك نوعان:

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

لا يُضبط أي من النوعين في نافذة الاستيراد. يُضبطان عند الاستيراد، ويُتحقق منهما مقابل العقد الحقيقي للعملية، وهناك ثلاثة رفضات ممكنة:

في جزء العقد تكتسب العملية التي فيها حقول مثبَّتة عموداً اسمه القيمة، ويُعلَّم الصف المرتبط بسر بشريحة سر بدلاً من قيمة.

استدعِ بإحكام

أي شيء يستطيع الوكيل ملأه قد يملؤه بشكل خاطئ. ثبّت القيم التي لا تتغير أبداً، واترك للوكيل الحقول التي يقدّمها المتصل فعلاً فقط.

الموصى به

apiKey     header  pinned to a workspace secret
tenantId   query   pinned constant "acme"
orderId    path    filled by the agent from what the caller said

الأقل فاعلية

apiKey     header  filled by the agent
tenantId   query   filled by the agent
orderId    path    filled by the agent

تفعيل العملية وإيقافها

يحمل كل صف في الشريط مفتاحاً. إيقاف المفتاح يمنع الوكيل من استدعاء تلك العملية، ويُحفظ التغيير فوراً دون زر حفظ.

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

ما تستقبله واجهة API

يذهب كل استدعاء إلى الرابط الأساسي الذي ضبطته على الأداة. تُستبدل القيم الثابتة للمسار أولاً، ثم تُملأ العناصر النائبة {curly} من ما أرسله الوكيل بعد ترميزها للرابط؛ والعنصر النائب الذي لا قيمة له يبقى كما هو. ثم تُوضع البقية حسب الطريقة: GET وHEAD وDELETE تضعها في سلسلة الاستعلام، وأي طريقة أخرى تضعها في جسم JSON مع Content-Type: application/json. وتُضاف الثوابت والأسرار بعد ذلك، ويُكتب header Authorization في الآخر.

ترى واجهة API طلباً عادياً. لا يوجد عليه أي توقيع من إيكونوڤا، ولا يحدد أي شيء فيه المحادثة التي جاء منها. خذ عملية GET /orders/{orderId}، ومتصلاً يسأل عن الطلب 4512، وقيمة استعلام ثابتة locale، واتصال bearer للمصادقة:

GET /orders/4512?locale=en HTTP/1.1
Host: api.example.com
Authorization: Bearer <resolved from the auth connection>

يمكنك إعادة إنتاج هذا الطلب على واجهة API الخاصة بك أثناء فحص الاستيراد:

curl "https://api.example.com/orders/4512?locale=en" \
  -H "Authorization: Bearer $MY_API_TOKEN"

import os
import requests

response = requests.get(
    "https://api.example.com/orders/4512",
    params={"locale": "en"},
    headers={"Authorization": f"Bearer {os.environ['MY_API_TOKEN']}"},
    timeout=15,
)
print(response.status_code, response.text[:500])

const response = await fetch('https://api.example.com/orders/4512?locale=en', {
  headers: { Authorization: `Bearer ${process.env.MY_API_TOKEN}` },
});
console.log(response.status, (await response.text()).slice(0, 500));

يعود ردّ واجهة API إلى الوكيل كحالة، وعلامة ok، وجسم، ويقرؤه الوكيل ويكمل الحديث.

عندما يفشل الاستدعاء

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

لا يظهر في هذا الجدول أي حالة غير ناجحة تأتي من واجهة API نفسها. فهي تمر كما هي، مع جسم ردّها، فيصل 404 من خدمتك إلى الوكيل كـ404.

هناك إعادة محاولة واحدة فقط. عندما ترد واجهة API بـ401 والاستدعاء استخدم اتصال OAuth2، يجلب إيكونوڤا رمزاً جديداً ويرسل الطلب مرة أخرى.

الحدود

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

كيف أوقف الوكيل عن استدعاء عملية واحدة؟

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

هل أستطيع منح عملية واحدة بيانات اعتماد مختلفة عن بقية واجهة API؟

ليس من نافذة الاستيراد. كل عملية تستخدم اتصال الأداة إلا إذا ضُبطت بطريقة أخرى عند الاستيراد، وجزء العقد يُظهر أي اتصال يسري: auth: <name> أو auth override: <name> أو no auth.

هل يستطيع الوكيل رؤية مفتاح API مثبَّت؟

لا. يُزال الحقل المثبَّت من العملية قبل أن يراه الوكيل، ويُعاد وضعه عند الاستدعاء، ولا تُعيد أي شاشة أو رد قيمة السر أبداً.

لماذا وصل إلى واجهة API طلب فيه {placeholder} غير مملوء؟

لم يُرسل الوكيل قيمة لمعامل المسار هذا. علّم المعامل بأنه مطلوب في المستند، أو ثبّته على قيمة ثابتة إذا كان لا يتغير أبداً.

هل تعرف واجهة API أي محادثة ينتمي إليها الاستدعاء؟

لا. يحمل الطلب بيانات الاعتماد والقيم التي ضبطتها فقط.

صفحات ذات صلة

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