إنشاء خادم وكيل لواجهة برمجة التطبيقات من مواصفات OpenAPI

أنت الآن بصدد الاطّلاع على مستندات Apigee Edge.
انتقِل إلى مستندات Apigee X. info

ما ستتعلمه

في هذا البرنامج التعليمي، سنتعرّف على ما يلي:

  • إنشاء خادم وكيل لواجهة برمجة تطبيقات Edge من مواصفات OpenAPI
  • استدعاء خادم وكيل لواجهة برمجة التطبيقات باستخدام cURL
  • إضافة سياسة إلى مسار مشروط
  • اختبِر استدعاء السياسة باستخدام cURL.

في هذا الفيديو التعليمي، ستتعرّف على كيفية إنشاء خادم وكيل لواجهة برمجة التطبيقات في Edge من مواصفات OpenAPI باستخدام واجهة مستخدم إدارة Apigee Edge. عندما تستدعي خادم وكيل لواجهة برمجة التطبيقات باستخدام برنامج HTTP، مثل cURL، يرسل خادم وكيل لواجهة برمجة التطبيقات الطلب إلى خدمة الهدف الوهمي في Apigee.

لمحة عن مبادرة Open API

Open API Initiative
"تركز مبادرة Open API (OAI) على إنشاء وتطوير وترويج تنسيق وصف لواجهة برمجة التطبيقات مستقل عن المورّدين استنادًا إلى مواصفات Swagger". لمزيد من المعلومات عن مبادرة Open API، يُرجى الاطّلاع على https://openapis.org.

تستخدم مواصفات OpenAPI تنسيقًا عاديًا لوصف RESTful API. تكون مواصفات OpenAPI مكتوبة بتنسيق JSON أو YAML، وهي قابلة للقراءة آليًا، ولكن يسهل أيضًا على المستخدمين قراءتها وفهمها. يصف هذا المستند عناصر واجهة برمجة التطبيقات، مثل المسار الأساسي والمسارات والأفعال والعناوين ومَعلمات طلب البحث والعمليات وأنواع المحتوى وأوصاف الردود وغير ذلك. بالإضافة إلى ذلك، يتم عادةً استخدام مواصفات OpenAPI لإنشاء مستندات واجهة برمجة التطبيقات.

لمحة عن خدمة الهدف الوهمي في Apigee

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

http://mocktarget.apigee.net

تعرض الخدمة المستهدَفة رسالة الترحيب Hello, guest!

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

http://mocktarget.apigee.net/help

المتطلبات

  • حساب على Apigee Edge إذا لم يكن لديك حساب، يمكنك الاشتراك باتّباع التعليمات الواردة في مقالة إنشاء حساب على Apigee Edge.
  • مواصفات OpenAPI في هذا البرنامج التعليمي، ستستخدم mocktarget.yaml مواصفات OpenAPI التي تصف خدمة الهدف الوهمي في Apigee، http://mocktarget.apigee.net. لمزيد من المعلومات، يُرجى الاطّلاع على https://github.com/apigee/api-platform-samples/tree/master/default-proxies/helloworld/openapi.
  • cURL مثبَّت على جهازك لإجراء طلبات البيانات من واجهة برمجة التطبيقات من سطر الأوامر، أو متصفّح ويب

إنشاء خادم وكيل لواجهة برمجة التطبيقات

Edge

لإنشاء خادم وكيل لواجهة برمجة التطبيقات من مواصفات OpenAPI باستخدام واجهة مستخدم Edge، اتّبِع الخطوات التالية:

  1. سجِّل الدخول إلى https://apigee.com/edge.
  2. انقر على "خوادم وكيلة لواجهة برمجة التطبيقات" (API Proxies) في النافذة الرئيسية.

    بدلاً من ذلك، يمكنك النقر على تطوير > خوادم وكيلة لواجهة برمجة التطبيقات في شريط التنقّل الأيمن.

    انقر على "خوادم وكيلة لواجهة برمجة التطبيقات" في الصفحة المقصودة

  3. انقر على + خادم وكيل.
    إضافة خادم وكيل لواجهة برمجة التطبيقات
  4. في معالج "إنشاء خادم وكيل"، انقر على استخدام مواصفات OpenAPI لنموذج الخادم الوكيل العكسي (الأكثر شيوعًا).
    إنشاء نوع خادم وكيل
  5. انقر على الاستيراد من عنوان URL وأدخِل المعلومات التالية:
    • عنوان URL لمواصفات OpenAPI: مسار المحتوى الأولي على GitHub لمواصفات OpenAPI في حقل عنوان URL: 
      https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget3.0.yaml
    • اسم المواصفات: اسم مواصفات OpenAPI، مثل Mock Target

      يُستخدَم هذا الاسم لتخزين مواصفات OpenAPI في متجر المواصفات. راجِع إدارة المواصفات.

  6. انقر على استيراد.

    تظهر صفحة "التفاصيل" في معالج "إنشاء وكيل". يتم ملء الحقول مسبقًا باستخدام القيم المحدّدة في مواصفات OpenAPI، كما هو موضّح في ما يلي

    يوضّح الجدول التالي القيم التلقائية التي تتم تعبئتها مسبقًا باستخدام السمات في مواصفات OpenAPI. يتم عرض مقتطف من مواصفات OpenAPI يوضّح الخصائص المستخدَمة بعد الجدول.

    الحقل الوصف تلقائي
    الاسم اسم خادم وكيل لواجهة برمجة التطبيقات على سبيل المثال: Mock-Target-API. السمة title من مواصفات OpenAPI مع استبدال المسافات بشرطات
    المسار الأساسي مكوّن المسار الذي يحدّد بشكل فريد خادم وكيل واجهة برمجة التطبيقات هذا داخل المؤسسة يتألف عنوان URL المتاح للجميع لخادم وكيل واجهة برمجة التطبيقات هذا من اسم مؤسستك والبيئة التي تم نشر خادم وكيل واجهة برمجة التطبيقات فيها والمسار الأساسي هذا. على سبيل المثال: http://myorg-test.apigee.net/mock-target-api تم تحويل محتوى حقل الاسم إلى أحرف صغيرة
    الوصف وصف لخادم وكيل واجهة برمجة التطبيقات description property من مواصفات OpenAPI
    الهدف (واجهة برمجة التطبيقات الحالية) عنوان URL المستهدَف الذي يتم استدعاؤه نيابةً عن خادم وكيل لواجهة برمجة التطبيقات هذا. يمكن استخدام أي عنوان URL يمكن الوصول إليه عبر الإنترنت المفتوح. على سبيل المثال: http://mocktarget.apigee.net servers property من مواصفات OpenAPI

    يوضّح ما يلي مقتطفًا من مواصفات OpenAPI يعرض الخصائص المستخدَمة لتعبئة الحقول مسبقًا.

    openapi: 3.0.0
info:
  description: OpenAPI Specification for the Apigee mock target service endpoint.
  version: 1.0.0
  title: Mock Target API
paths:
  /:
    get:
      summary: View personalized greeting
      operationId: View a personalized greeting
      description: View a personalized greeting for the specified or guest user.
      parameters:
        - name: user
          in: query
          description: Your user name.
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Success
...
servers:
  - url: http://mocktarget.apigee.net
  - url: https://mocktarget.apigee.net
...
  7. عدِّل حقل الوصف على النحو التالي: API proxy for the Apigee mock target service endpoint.
  8. انقر على التالي.
  9. في صفحة السياسات الشائعة، ضِمن "الأمان: التفويض"، تأكَّد من اختيار التمرير (بدون تفويض)، ثم انقر على التالي:

    تم اختيار "التمرير" (بدون تفويض) في صفحة "السياسات العامة"

  10. في صفحة "عمليات سير البيانات"، تأكَّد من اختيار جميع العمليات. إنشاء تدفقات خادم وكيل
  11. انقر على التالي.
  12. في صفحة المضيفون الافتراضيون، اختَر تلقائي وآمن، ثم انقر على التالي.
    تم اختيار الخيارين التلقائي والآمن في صفحة "المضيفات الافتراضية"
  13. في صفحة الملخّص، تأكَّد من اختيار بيئة الاختبار ضمن النشر الاختياري، ثم انقر على إنشاء ونشر:

    تنشئ Apigee خادم وكيل جديدًا لواجهة برمجة التطبيقات وتنشره في بيئة الاختبار:

  14. انقر على تعديل الخادم الوكيل لعرض صفحة "نظرة عامة" الخاصة بخادم واجهة برمجة التطبيقات الوكيل.
    ملخّص لخادم Mock Target API الوكيل

Classic Edge (Private Cloud)

لإنشاء خادم وكيل لواجهة برمجة التطبيقات من مواصفات OpenAPI باستخدام واجهة مستخدم Classic Edge، اتّبِع الخطوات التالية:

  1. سجِّل الدخول إلى https://apigee.com/edge.
  2. انقر على "خوادم وكيلة لواجهة برمجة التطبيقات" (API Proxies) في النافذة الرئيسية.

    بدلاً من ذلك، يمكنك النقر على تطوير > خوادم وكيلة لواجهة برمجة التطبيقات في شريط التنقّل الأيمن.

  3. انقر على + خادم وكيل.
    إضافة خادم وكيل لواجهة برمجة التطبيقات
  4. في معالج "إنشاء وكيل"، اختَر الوكيل العكسي (الأكثر شيوعًا) وانقر على استخدام OpenAPI.
    إنشاء نوع خادم وكيل
  5. انقر على الاستيراد من عنوان URL، وأدخِل اسمًا لمواصفات OpenAPI، ثم أدخِل مسار المحتوى الأولي على GitHub لمواصفات OpenAPI في حقل عنوان URL:

    https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget.yaml
  6. انقر على اختيار.
  7. انقر على التالي.

    تظهر صفحة "التفاصيل" في معالج "إنشاء وكيل". تتم تعبئة الحقول مسبقًا باستخدام القيم المحدّدة في مواصفات OpenAPI، كما هو موضّح في الشكل التالي.

    إنشاء تفاصيل الخادم الوكيل

    يوضّح الجدول التالي القيم التلقائية التي تتم تعبئتها مسبقًا باستخدام السمات في مواصفات OpenAPI. يتم عرض مقتطف من مواصفات OpenAPI يوضّح الخصائص المستخدَمة بعد الجدول.

    الحقل الوصف تلقائي
    اسم الخادم الوكيل اسم خادم وكيل لواجهة برمجة التطبيقات على سبيل المثال: Mock-Target-API. السمة title من مواصفات OpenAPI مع استبدال المسافات بشرطات
    مسار قاعدة الخادم الوكيل مكوّن المسار الذي يحدّد بشكل فريد خادم وكيل واجهة برمجة التطبيقات هذا داخل المؤسسة يتألف عنوان URL المتاح للجميع لخادم وكيل واجهة برمجة التطبيقات هذا من اسم مؤسستك والبيئة التي تم نشر خادم وكيل واجهة برمجة التطبيقات فيها والمسار الأساسي هذا. على سبيل المثال: http://myorg-test.apigee.net/mock-target-api تم تحويل محتوى حقل الاسم إلى أحرف صغيرة
    واجهة برمجة التطبيقات الحالية عنوان URL المستهدَف الذي يتم استدعاؤه نيابةً عن خادم وكيل لواجهة برمجة التطبيقات هذا. يمكن استخدام أي عنوان URL يمكن الوصول إليه عبر الإنترنت المفتوح. على سبيل المثال: http://mocktarget.apigee.net servers property من مواصفات OpenAPI
    الوصف وصف لخادم وكيل واجهة برمجة التطبيقات description property من مواصفات OpenAPI

    يوضّح ما يلي مقتطفًا من مواصفات OpenAPI يعرض الخصائص المستخدَمة لتعبئة الحقول مسبقًا.

    openapi: 3.0.0
info:
  description: OpenAPI Specification for the Apigee mock target service endpoint.
  version: 1.0.0
  title: Mock Target API
paths:
  /:
    get:
      summary: View personalized greeting
      operationId: View a personalized greeting
      description: View a personalized greeting for the specified or guest user.
      parameters:
        - name: user
          in: query
          description: Your user name.
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Success
...
servers:
  - url: http://mocktarget.apigee.net
  - url: https://mocktarget.apigee.net
...
  8. عدِّل حقل الوصف على النحو التالي: API proxy for the Apigee mock target service endpoint.
  9. انقر على التالي.
  10. في صفحة "عمليات سير البيانات"، تأكَّد من اختيار جميع العمليات. إنشاء تدفقات خادم وكيل
  11. انقر على التالي.
  12. في صفحة "الأمان"، اختَر بدون مصادقة (لا شيء) كخيار الأمان، ثم انقر على التالي.
  13. في صفحة "المضيفات الافتراضية" (Virtual Hosts)، تأكَّد من اختيار جميع المضيفات الافتراضية، ثم انقر على التالي (Next).
  14. في صفحة "إنشاء"، تأكَّد من اختيار بيئة الاختبار، ثم انقر على إنشاء ونشر.
  15. في صفحة "الملخّص"، سيظهر إقرار بأنّه تم إنشاء خادم وكيل جديد لواجهة برمجة التطبيقات بنجاح ونشره في بيئة الاختبار.
    إنشاء ملخّص للخادم الوكيل
  16. انقر على Mock-Target-API لعرض صفحة "نظرة عامة" لخادم وكيل واجهة برمجة التطبيقات.
    ملخّص لخادم Mock Target API الوكيل

تهانينا! لقد أنشأت خادمًا وكيلاً لواجهة برمجة التطبيقات من مواصفات OpenAPI. بعد ذلك، ستجرّبها لمعرفة طريقة عملها.

اختبار خادم وكيل لواجهة برمجة التطبيقات

يمكنك اختبار واجهة برمجة التطبيقات Mock-Target-API باستخدام cURL أو متصفّح ويب.

في نافذة الوحدة الطرفية، نفِّذ أمر cURL التالي. استبدِل اسم مؤسستك في عنوان URL.

curl http://<org_name>-test.apigee.net/mock-target-api

الردّ

من المفترض أن يظهر لك الردّ التالي:

Hello, Guest!

أحسنت! لقد أنشأت خادم وكيل بسيطًا لواجهة برمجة التطبيقات من مواصفات OpenAPI واختبرته.

إضافة سياسة XML إلى JSON

بعد ذلك، ستضيف سياسة XML إلى JSON إلى التدفق الشرطي عرض استجابة XML الذي تم إنشاؤه تلقائيًا عند إنشاء خادم وكيل لواجهة برمجة التطبيقات من مواصفات OpenAPI. ستحوّل السياسة استجابة XML الخاصة بالهدف إلى استجابة JSON.

أولاً، استدعِ واجهة برمجة التطبيقات حتى تتمكّن من مقارنة النتائج بالنتائج التي تم تلقّيها بعد إضافة السياسة. في نافذة الوحدة الطرفية، نفِّذ أمر cURL التالي. أنت بصدد طلب بيانات من مورد /xml في الخدمة المستهدَفة، والذي يعرض بشكل أصلي مجموعة بسيطة من XML. استبدِل اسم مؤسستك في عنوان URL.

curl http://<org_name>-test.apigee.net/mock-target-api/xml

الردّ

من المفترض أن يظهر لك الردّ التالي:

<root> 
  <city>San Jose</city> 
  <firstName>John</firstName> 
  <lastName>Doe</lastName> 
  <state>CA</state> 
</root>

لننفّذ الآن إجراءً يحوّل استجابة XML إلى JSON. أضِف سياسة XML إلى JSON إلى مسار View XML Response الشرطي في خادم وكيل واجهة برمجة التطبيقات.

  1. انقر على علامة التبويب تطوير في أعلى يسار صفحة &quot;نظرة عامة&quot; على Mock-Target-API في واجهة مستخدم Edge.
    علامة التبويب &quot;المطوّر&quot;
  2. في لوحة Navigator على يمين الشاشة، ضِمن Proxy Endpoints > default، انقر على التدفق الشرطي عرض رد XML.
    اختَر &quot;عرض استجابة XML&quot;
  3. انقر على الزر +الخطوة في أسفل الصفحة، بما يتوافق مع الردّ في المسار.
    انقر على &quot;إضافة خطوة&quot;
    يفتح مربّع الحوار "إضافة خطوة" لعرض قائمة مصنّفة بجميع السياسات التي يمكنك إضافتها.
  4. انتقِل إلى فئة "التوسّط" واختَر XML إلى JSON.
    مربّع حوار &quot;إضافة خطوة&quot;
  5. احتفِظ بالقيم التلقائية لكل من الاسم المعروض والاسم.
  6. انقر على إضافة. يتم تطبيق سياسة XML إلى JSON على الردّ.سياسة XML إلى JSON في التدفق
  7. انقر على حفظ.

بعد إضافة السياسة، اطلب من واجهة برمجة التطبيقات تنفيذ الأمر مرة أخرى باستخدام cURL. لاحظ أنّك ما زلت تطلب الوصول إلى المورد /xml نفسه. لا تزال الخدمة المستهدَفة تعرض مجموعة XML، ولكن ستحوّل السياسة في خادم وكيل واجهة برمجة التطبيقات الاستجابة إلى JSON. أجرِ المكالمة التالية:

curl http://<org_name>-test.apigee.net/mock-target-api/xml

يُرجى العِلم أنّه يتم تحويل استجابة XML إلى JSON:

{"root":{"city":"San Jose","firstName":"John","lastName":"Doe","state":"CA"}}

تهانينا! لقد اختبرت بنجاح تنفيذ سياسة تمت إضافتها إلى مسار مشروط.