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

يتم الآن عرض مستندات Apigee Edge.
انتقِل إلى مستندات Apigee X.
المعلومات

المعلومات التي ستطّلع عليها

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

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

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

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

مبادرة واجهة برمجة التطبيقات المفتوحة
"تركّز "مبادرة 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. في هذا الفيديو التعليمي، ستستخدم مواصفات OpenAPI الخاصة mocktarget.yaml التي توضّح نموذج خدمة الهدف http://mocktarget.apigee.net الخاص بـ Apigee. ولمزيد من المعلومات، يمكنك الاطّلاع على https://github.com/apigee/api-platform-samples/tree/master/default-proxies/helloworld/openapi.
  • cURL على جهازك لإجراء طلبات بيانات من واجهة برمجة التطبيقات من سطر الأوامر أو من متصفح ويب.

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

Edge

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

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

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

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

  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، مثل الهدف التجريبي.

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

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

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

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

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

كلاسيكي Edge (السحابة الإلكترونية الخاصة)

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

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

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

  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 من مواصفات OpenAPI
    الوصف وصف الخادم الوكيل لواجهة برمجة التطبيقات. السمة description من مواصفات 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. في صفحة "المضيفون الافتراضيون"، تأكَّد من اختيار جميع المضيفين الافتراضيين، وانقر على التالي.
  14. في صفحة الإصدار، تأكَّد من اختيار بيئة الاختبار، ثم انقر على إنشاء ونشر.
  15. في صفحة "الملخّص"، ترى إقرارًا بأنّه تم إنشاء الخادم الوكيل الجديد لواجهة برمجة التطبيقات بنجاح وتم نشره في بيئة الاختبار.
    إنشاء ملخص خادم وكيل
  16. انقر على 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 إلى المسار المشروط لعرض استجابة XML في الخادم الوكيل لواجهة برمجة التطبيقات.

  1. انقر على علامة التبويب Develop (تطوير) في أعلى يسار صفحة النظرة العامة على واجهة برمجة التطبيقات (Mock-Target-API) في واجهة مستخدم Edge.
    علامة التبويب &quot;المطوّر&quot;
  2. في لوحة المستكشف اليمنى، ضمن نقاط نهاية الخادم الوكيل > تلقائي، انقر على التدفق الشرطي عرض استجابة XML.
    اختيار عرض استجابة XML
  3. انقر على زر +خطوة السفلي الذي يتطابق مع الاستجابة للمسار.
    تحديد &quot;+خطوة&quot;
    يفتح مربّع حوار "إضافة خطوة" لعرض قائمة مصنَّفة بجميع السياسات التي يمكنك إضافتها.
  4. انتقِل إلى فئة "التوسّط" واختَر XML to JSON.
    مربع حوار إضافة الخطوة
  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"}}

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