المطورون / Tools
معاينة استيراد OpenAPI
https://api.echonova.ai/v1/tools/openapi/previewيقرأ مستند OpenAPI، مضمَّنًا أو من عنوان URL عام، ويسرد العمليات التي ستستوردها الأداة. لا يُحفظ شيء. الحد الأقصى 5 استدعاءات في الدقيقة لكل مفتاح. الخدمة مجانية. يحتاج المفتاح إلى النطاق `tools:write`.
Headers
كلمة Bearer ثم مسافة ثم مفتاح API الذي يبدأ بـ ek_. أنشئ المفاتيح في البوابة من المطورون، ثم مفاتيح واجهة برمجة التطبيقات.
متن الطلب
application/json
مستند OpenAPI بصيغة JSON، بحجم يصل إلى 5 ميغابايت. أرسل واحدًا فقط من `spec` أو `url`.
عنوان URL عام بروتوكول https لمستند OpenAPI. أرسل واحدًا فقط من `spec` أو `url`.
الخادم الذي تستدعيه الأداة، ويحل محل خوادم المستند. مطلوب عند الإنشاء.
الاستجابة
200 application/json كل استجابة تستخدم هذا الغلاف.
النتيجة.
عنوان المستند.
عدد العمليات في المستند.
أمور سيتخطاها الاستيراد أو يغيّرها.
الخادم الذي يعلنه المستند، أو سلسلة نصية فارغة.
العمليات التي ستستوردها الأداة.
اسم العملية، كما يستخدمه `operationEdits`.
طريقة HTTP.
المسار في المستند.
ما تفعله العملية.
هل تغيّر العملية البيانات.
معاملات العملية.
اسم المعامل.
`path` أو `query` أو `header` أو `cookie`.
هل تحتاج العملية إلى هذا المعامل.
نوع القيمة التي يأخذها المعامل.
حقول جسم الطلب على المستوى الأعلى.
اسم حقل الجسم.
نوع القيمة التي يأخذها الحقل.
هل تحتاج العملية إلى هذا الحقل.
قيمته true عند نجاح الطلب.
يكرر رمز حالة HTTP.
قيمته null عند النجاح.
الأخطاء
الغلاف نفسه، مع success بقيمة false و data بقيمة null. كل الأخطاء
متى يحدث. معامل أو عنصر في `fieldValues` قيمته `constant` واسمه يبدو كبيانات اعتماد، مثل Authorization أو token أو api key أو cookie. تذكر الرسالة الحقل ولا تذكر قيمته أبدًا.
الحل. احفظ القيمة في خزنة البوابة، ثم أرسلها كترويسة سرية مع `secretId` الخاص بها، أو استخدم اتصال مصادقة.
متى يحدث. قيمة ثابتة تبدأ بـ Bearer أو Basic أو Token أو Digest، أو لها شكل JWT. تذكر الرسالة الحقل ولا تذكر قيمته أبدًا.
الحل. احفظ القيمة في خزنة البوابة، ثم أرسلها كترويسة سرية مع `secretId` الخاص بها، أو استخدم اتصال مصادقة.
متى يحدث. عنوان webhook أو `baseUrlOverride` فيه مفتاح استعلام يبدو كبيانات اعتماد. تذكر الرسالة المفتاح ولا تذكر قيمته أبدًا.
الحل. احفظ القيمة في خزنة البوابة، ثم أرسلها كترويسة سرية مع `secretId` الخاص بها، أو استخدم اتصال مصادقة.
متى يحدث. مفتاح يشبه بيانات الاعتماد مخفي في جزء الاستعلام أو في جزء المرجع (fragment) من عنوان webhook أو `baseUrlOverride`.
الحل. احفظ القيمة في خزنة البوابة، ثم أرسلها كترويسة سرية مع `secretId` الخاص بها، أو استخدم اتصال مصادقة.
متى يحدث. عنوان `url` للوثيقة لا يستخدم https، أو يشير إلى عنوان loopback أو خاص أو link-local، أو ليس عنوان URL.
الحل. أرسل عنوان https عامًا، أو أرسل الوثيقة مضمّنة في `spec`.
متى يحدث. عنوان `url` للوثيقة يحمل اسم مستخدم أو كلمة مرور.
الحل. أرسل العنوان بدونهما، واستخدم header سريًّا أو اتصال مصادقة.
متى يحدث. قيمة `baseUrlOverride` لا تستخدم https، أو تشير إلى عنوان loopback أو خاص أو link-local، أو ليست عنوان URL.
الحل. أرسل عنوان https عامًا.
متى يحدث. قيمة `baseUrlOverride` تحمل اسم مستخدم أو كلمة مرور.
الحل. أرسل العنوان بدونهما، واستخدم header سريًّا أو اتصال مصادقة.
متى يحدث. تعذّرت قراءة المستند بوصفه مستند OpenAPI. يسمّي النص ما هو خاطئ، لذلك يختلف.
الحل. صحّح الوثيقة كما تقول الرسالة، ثم عاين الاستيراد من جديد.
متى يحدث. الجسم يحتوي على `spec` و`url` معًا، أو لا يحتوي على أيٍّ منهما.
الحل. أرسل واحدًا فقط منهما.
متى يحدث. مستند `spec` المضمَّن أكبر من 5 ميغابايت.
الحل. أرسله كعنوان `url` عام بدلًا من ذلك.
متى يحدث. المستند عند العنوان `url` أكبر من 5 ميغابايت.
الحل. أرسل مستندًا أصغر.
متى يحدث. لم يردّ عنوان `url` في الوقت المحدد، أو تعذّرت قراءته.
الحل. تحقّق من أن عنوان `url` عام ويردّ بسرعة، أو أرسل المستند مضمّنًا.
متى يحدث. ردّ عنوان `url` برمز خطأ. تذكر الرسالة الرمز.
الحل. تحقّق من عنوان `url`.
متى يحدث. ردّ عنوان `url` بشيء ليس مستند JSON.
الحل. أرسل المستند بصيغة JSON.
متى يحدث. متن الطلب أو الاستعلام يحمل حقلًا لا تعرّفه نقطة النهاية.
الحل. احذف الحقل.
متى يحدث. header `Authorization` مفقود، أو قيمته لا تبدأ بـ `Bearer ek_...`، أو أن الرمز لا يطابق أي مفتاح، أو أن المفتاح محذوف أو معطّل أو منتهي الصلاحية، أو أن حسابه مغلق.
الحل. أرسل `Authorization: Bearer ek_...` بمفتاح API مفعّل.
متى يحدث. مساحة العمل التي يتبعها المفتاح ليس لديها اشتراك.
الحل. تحقّق من خطة مساحة العمل في البوابة.
متى يحدث. حالة الاشتراك ليست نشطة ولا تجريبية.
الحل. جدّد الاشتراك.
متى يحدث. المفتاح لا يملك النطاق `tools:write`. النطاق `agents:write` لا يمنح هذا الحق.
الحل. عدّل المفتاح وامنحه النطاق `tools:write`، أو استخدم مفتاحًا آخر.
متى يحدث. العضو الذي أنشأ المفتاح غادر مساحة العمل، أو لم يعد يملك الصلاحيتين معًا: إدارة الأدوات وإدارة واجهة برمجة التطبيقات للمطورين. يُفحص ذلك مع كل استدعاء.
الحل. امنح ذلك العضو الصلاحيتين مرة أخرى، أو أنشئ مفتاحًا بعضو يملكهما.
متى يحدث. جسم JSON لمعاينة OpenAPI أو إنشائها أكبر من 6 ميغابايت. يُرفض الطلب قبل فحص مفتاح API، لذلك لا يظهر له سطر في سجل النشاط.
الحل. أرسل المستند كعنوان `url` عام بدلًا من المضمَّن.
متى يحدث. للطلب جسم وقيمة `Content-Type` فيه ليست `application/json`.
الحل. أرسل `Content-Type: application/json`.
متى يحدث. أرسل المفتاح أكثر من 5 طلبات إلى هذه النقطة خلال 60 ثانية. ترويسة `Retry-After` تحمل عدد الثواني للانتظار.
الحل. انتظر عدد الثواني في `Retry-After`، ثم أعد المحاولة.
متى يحدث. خطأ لم تصنّفه API.
الحل. تحقّق من الطلب، ثم أعد المحاولة بعد لحظة قصيرة؛ وتواصل مع الدعم إذا تكرر الخطأ.
متى يحدث. انقطاع مؤقت داخل API.
الحل. أعد المحاولة بعد لحظة قصيرة.
متى يحدث. انتهاء مهلة مؤقت داخل API.
الحل. أعد المحاولة بعد لحظة قصيرة.
curl -X POST "https://api.echonova.ai/v1/tools/openapi/preview" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'{
"data": {
"apiTitle": "Orders API",
"operationCount": 12,
"warnings": [
"Skipped 2 operations without an operationId"
],
"baseUrl": "https://api.example.com",
"operations": [
{
"name": "getOrder",
"method": "GET",
"path": "/orders/{orderId}",
"description": "Find an order.",
"mutating": false,
"parameters": [
{
"name": "orderId",
"location": "path",
"required": true,
"type": "string"
}
],
"bodyFields": [
{
"name": "quantity",
"type": "integer",
"required": false
}
]
}
]
},
"success": true,
"statusCode": 200,
"errorMessage": null
}