مشاركة عبر

قيود استيراد واجهة برمجة التطبيقات، والمشكلات المعروفة

  • مقالة

ينطبق على: جميع مستويات إدارة واجهة برمجة التطبيقات

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

  • سلوك APIM أثناء استيراد OpenAPI.
  • قيود استيراد OpenAPI وكيف يعمل تصدير OpenAPI.
  • المتطلبات والقيود الخاصة باستيراد WSDL وWADL.

APIM أثناء استيراد OpenAPI

أثناء استيراد OpenAPI، APIM:

  • يتحقق بشكل خاص من معلمات سلسلة الاستعلام المحددة حسب الاقتضاء.
  • بشكل افتراضي، يحول معلمات سلسلة الاستعلام المطلوبة إلى معلمات القالب المطلوبة.

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

بالنسبة لعمليات GET و HEAD و OPTIONS، تتجاهل APIM معلمة نص الطلب إذا تم تعريفها في مواصفات OpenAPI.

قيود استيراد OpenAPI/Swagger

إذا تلقيت أخطاءً أثناء استيراد مستند OpenAPI، فتأكد من التحقق من صحته مسبقًا إما عن طريق:

  • باستخدام المصمم في مدخل Microsoft Azure (Design > Front End > OpenAPI Specification Editor)، أو
  • باستخدام أداة جهة خارجية، مثل Swagger Editor.

العامه

متطلبات قالب URL

المتطلبات الوصف
أسماء فريدة لمعلمات المسار والاستعلام المطلوبة في OpenAPI:
  • يجب أن يكون اسم المعلمة فريدًا فقط داخل الموقع؛ على سبيل المثال: المسار، الاستعلام، العنوان.
في APIM:
  • نسمح بالتمييز بين العمليات من خلال معلمات المسار والاستعلام.
  • لا يدعم OpenAPI هذا التمييز؛ لذلك نطلب أن تكون أسماء المعلمات فريدة في قالب عنوان URL بالكامل. الأسماء غير حساسة لحالة الأحرف.
معلمة URL المعرفة يجب أن تكون جزءًا من قالب URL.
عنوان URL المتوفر لملف المصدر يتم تطبيقه على عناوين URL للخادم ذات الصلة.
\$ref مؤشرات لا يمكن الرجوع إلى الملفات الخارجية.

مواصفات OpenAPI

الإصدارات المدعومة

لا تدعم سوى APIM:

  • OpenAPI الإصدار 2.
  • OpenAPI الإصدار 3.0.x (حتى الإصدار 3.0.3).
  • الإصدار 3.1 من OpenAPI (استيراد فحسب)

قيود الحجم

حد الحجم ‏‏الوصف
ما يصل إلى 4 ميغابايت عندما استيراد مواصفات OpenAPI مضمنة إلى APIM.
حجم طلب واجهة برمجة تطبيقات Azure Resource Manager عندما يتم توفير مستند OpenAPI عبر عنوان URL إلى موقع يمكن الوصول إليه من خدمة APIM. راجع حدود اشتراك Azure.

الملحقات المدعومة

الملحقات المعتمدة الوحيدة هي:

ملحق ‏‏الوصف
x-ms-paths
  • يسمح لك بتحديد المسارات التي يتم تمييزها من خلال معلمات الاستعلام في عنوان URL.
  • مغطى في مستندات AutoRest.
x-servers منفذ خلفي لكائن OpenAPI 3 servers ل OpenAPI 2.

الملحقات غير المعتمدة

ملحق ‏‏الوصف
Recursion لا تدعم APIM التعريفات المحددة بشكل متكرر.
على سبيل المثال، المخططات التي تشير إلى نفسها.
Server الكائن غير معتمدة على مستوى تشغيل API.
Produces الكلمه الاساسيه يصف أنواع MIME التي تم إرجاعها من خلال API.
‏‏غير مدعومة.

الملحقات المخصصة

  • يتم تجاهلها عند الاستيراد.
  • لا يتم حفظها أو الاحتفاظ بها للتصدير.

التعريفات غير المعتمدة

لا يتم دعم تعريفات المخطط المضمن لعمليات API. تعريفات المخطط:

  • يتم تعريفها في نطاق API.
  • يمكن الرجوع إليها في طلبات عمليات API، أو نطاقات الاستجابة.

التعريفات المهملة

يتم تجاهل تعريفات الأمان.

القيود الخاصة بالتعريف

عند استيراد معلمات الاستعلام، يُدعم أسلوب إنشاء تسلسل الصفيف الافتراضي (style: form، explode: true) فحسب. للحصول علي المزيد من التفاصيل حول معلمات الاستعلام في مواصفات OpenAPI، راجع مواصفات إنشاء التسلسل.

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

OpenAPI الإصدار 2

يقتصر دعم OpenAPI الإصدار 2 على تنسيق JSON فقط.

معلمات نوع "النموذج" غير مدعومة. لا يزال بإمكانك استخدام النهج لفك تشفير البيانات الأساسية والتحقق من صحتهاapplication/x-www-form-urlencoded.application/form-data

الإصدار 3.x من OpenAPI

تدعم APIM إصدارات المواصفات الآتية:

عناوين URL لـ HTTPS

  • إذا تم تحديد متعدد servers ، فستستخدم إدارة واجهة برمجة التطبيقات عنوان URL HTTPS الأول الذي تعثر عليه.
  • إذا لم يكن هناك أي عناوين URL ل HTTPS، يكون عنوان URL للخادم فارغا.

مدعوم

  • example

غير مدعوم

يتم تضمين الحقول التالية في الإصدار 3.0.x من OpenAPI أو OpenAPI الإصدار 3.1.x، ولكنها غير مدعومة:

‏‏الكائن الحقل
OpenAPI externalDocs
معلومات summary
المكونات
  • responses
  • parameters
  • examples
  • requestBodies
  • headers
  • securitySchemes
  • links
  • callbacks
PathItem
  • trace
  • servers
العملية
  • externalDocs
  • callbacks
  • security
  • servers
المعلمة‬
  • allowEmptyValue
  • style
  • explode
  • allowReserved

آليات استيراد OpenAPI وتحديثها وتصديرها

العامه

تعريفات API المصدرة من خدمة APIM هي:

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

لإدارة تكوين تعريفات API عبر خدمات/ بيئات مختلفة، ارجع إلى الوثائق المتعلقة باستخدام خدمة APIM مع Git.

إضافة API جديدة عبر استيراد OpenAPI

لكل عملية تم العثور عليها في مستند OpenAPI، يتم إنشاء عملية جديدة باستخدام:

  • تم تعيين اسم مورد Azure إلى operationId.

    • operationId يتم تسوية القيمة.
    • إذا operationId لم يتم تحديد (غير موجود أو nullأو فارغ)، يتم إنشاء قيمة اسم مورد Azure عن طريق الجمع بين أسلوب HTTP وقالب المسار.
      • على سبيل المثال، get-foo

  • تم تعيين اسم العرض إلى summary.

    • summary قيمه:
      • تم استيراده كما هو.
      • يقتصر الطول على 300 حرفًا.
    • إذا summary لم يتم تحديد (غير موجود أو nullأو فارغ)، فسيتم تعيين قيمة اسم العرض إلى operationId.

قواعد التسوية ل operationId

  • تحويل إلى أحرف صغيرة.
  • استبدل كل تسلسل من الأحرف غير الأبجدية الرقمية بشرطة واحدة.
    • على سبيل المثال، GET-/foo/{bar}?buzz={quix} يتم تحويله إلى get-foo-bar-buzz-quix-.
  • قم بقص الشرطات على كلا الجانبين.
    • على سبيل المثال، get-foo-bar-buzz-quix- يصبح get-foo-bar-buzz-quix
  • قم بالاقتطاع لملاءمة 76 حرفًا؛ أربعة أحرف أقل من الحد الأقصى لاسم المورد.
  • استخدم الأحرف الأربعة المتبقية للاحقة إزالة التكرار، إذا لزم الأمر، في شكل -1, -2, ..., -999.

تحديث API موجود عبر استيراد OpenAPI

أثناء الاستيراد، عملية API الموجودة:

  • التغييرات لمطابقة API الموضحة في مستند OpenAPI.
  • يطابق عملية في مستند OpenAPI عن طريق مقارنة operationId قيمته باسم مورد Azure الخاص بالعملية الحالية.
    • إذا تم العثور على تطابق، يتم تحديث خصائص العملية الحالية "في مكانها".
    • إذا لم يتم العثور على تطابق:
      • يتم إنشاء عملية جديدة عن طريق الجمع بين أسلوب HTTP وقالب المسار، على سبيل المثال، get-foo.
      • لكل عملية جديدة، سيحاول الاستيراد نسخ النُهج من عملية حالية بنفس أسلوب HTTP، ونفس قالب المسار.

يتم حذف كافة العمليات غير المتطابقة الموجودة.

لجعل الاستيراد أكثر قابلية للتنبؤ به، اتبع الإرشادات التالية:

  • حدد operationId خاصية لكل عملية.
  • الامتناع عن التغيير operationId بعد الاستيراد الأولي.
  • لا تتغير operationId أبدا وأسلوب HTTP أو قالب المسار في نفس الوقت.

قواعد التسوية ل operationId

  • تحويل إلى أحرف صغيرة.
  • استبدل كل تسلسل من الأحرف غير الأبجدية الرقمية بشرطة واحدة.
    • على سبيل المثال، GET-/foo/{bar}?buzz={quix} يتم تحويله إلى get-foo-bar-buzz-quix-.
  • قم بقص الشرطات على كلا الجانبين.
    • على سبيل المثال، get-foo-bar-buzz-quix- يصبح get-foo-bar-buzz-quix
  • قم بالاقتطاع لملاءمة 76 حرفًا؛ أربعة أحرف أقل من الحد الأقصى لاسم المورد.
  • استخدم الأحرف الأربعة المتبقية للاحقة إزالة التكرار، إذا لزم الأمر، في شكل -1, -2, ..., -999.

تصدير API كـ OpenAPI

لكل عملية، يكون:

  • يتم تصدير اسم مورد Azure ك operationId.
  • يتم تصدير اسم العرض ك summary.

لاحظ أن تسوية operationId تتم عند الاستيراد، ليس عند التصدير.

WSDL

يمكنك إنشاء مرور خلال بروتوكول SOAP، وبروتوكول SOAP إلى واجهات برمجيات تطبيقات REST باستخدام ملفات WSDL.

روابط بروتوكول SOAP

  • يتم دعم روابط بروتوكول SOAP فقط لنمط الترميز "المستند" و"القيمة الحرفية".
  • لا يوجد دعم لنمط "rpc"، أو ترميز بروتوكول SOAP.

عمليات الاستيراد وعمليات التضمين

  • التوجيهانwsdl:import، xsd:import، وxsd:include غير مدعومين. بدلًا من ذلك، ادمج التبعيات في مستند واحد.

  • للحصول على أداة مفتوحة المصدر لحل ودمج تبعيات wsdl:import،xsd:import وxsd:include في ملف WSDL، راجع مستودع GitHub هذا.

WS-* specifications

ملفات WSDL التي تتضمن مواصفات WS-* غير مدعومة.

رسائل ذات أجزاء متعددة

نوع الرسالة هذا غير معتمد.

WCF wsHttpBinding

  • يجب أن تستخدم basicHttpBindingخدمات SOAP التي تم إنشاؤها باستخدام Windows Communication Foundation .
  • wsHttpBinding غير مدعوم.

MTOM

  • الخدمات التي تستخدم ⁧MTOM⁩⁧⁩ربما⁧⁩ تعمل.
  • لا يتم تقديم الدعم الرسمي في الوقت الحالي.

الإعادة

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

مساحات أسماء متعددة

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

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

نقاط نهاية متعددة

يمكن لملفات WSDL تعريف خدمات ونقاط نهاية متعددة (منافذ) بمقدار واحد أو أكثر wsdl:service وعناصر wsdl:port . ومع ذلك، فإن بوابة APIM قادرة على استيراد طلبات الوكيل وخدمة واحدة ونقطة نهاية واحدة فقط. إذا تم تعريف خدمات أو نقاط نهاية متعددة في ملف WSDL، فحدد اسم الخدمة الهدف ونقطة النهاية عند استيراد واجهة برمجة التطبيقات باستخدام خاصية wsdlSelector .

تلميح

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

الصفائف

يدعم تحويل بروتوكول SOAP إلى واجهة برمجة تطبيقات REST المصفوفات المغلفة الموضحة في المثال أدناه:

    <complexType name="arrayTypeName">
        <sequence>
            <element name="arrayElementValue" type="arrayElementType" minOccurs="0" maxOccurs="unbounded"/>
        </sequence>
    </complexType>
    <complexType name="typeName">
        <sequence>
            <element name="element1" type="someTypeName" minOccurs="1" maxOccurs="1"/>
            <element name="element2" type="someOtherTypeName" minOccurs="0" maxOccurs="1" nillable="true"/>
            <element name="arrayElement" type="arrayTypeName" minOccurs="1" maxOccurs="1"/>
        </sequence>
    </complexType>

WADL

حاليًا، لا توجد مشكلات معروفة في استيراد WADL.