יצירת שרת proxy של API ממפרט OpenAPI

כרגע מוצג התיעוד של Apigee Edge.
כניסה למסמכי התיעוד של Apigee X.
מידע

מה תלמדו

במדריך הזה תלמדו:

  • יצירת שרת proxy של Edge API ממפרט של OpenAPI.
  • מפעילים את שרת ה-proxy של ה-API באמצעות cURL.
  • הוספת מדיניות לתהליך מותנה.
  • יש לבדוק את הפעלת המדיניות באמצעות cURL.

במדריך הזה תלמדו איך ליצור שרת proxy של Edge API ממפרט OpenAPI באמצעות ממשק המשתמש לניהול של Apigee Edge. כשקוראים לשרת ה-API של ה-API באמצעות לקוח HTTP, כמו cURL, שרת ה-API של שרת ה-proxy שולח את הבקשה לשירות היעד המדמה Apigee.

מידע על יוזמת ה-Open API

יוזמת ה-Open API
"יוזמת Open API Initiative (OAI) מתמקדת ביצירה, בפיתוח ובקידום של פורמט תיאור API נייטרלי של הספק, על סמך מפרט Swagger". מידע נוסף על יוזמת ה-Open API זמין בכתובת https://openapis.org.

במפרט OpenAPI נעשה שימוש בפורמט סטנדרטי לתיאור API ל-RESTful. מפרט OpenAPI נכתב בפורמט JSON או YAML. הוא גם קריא למחשבים אבל קל לקריאה ולהבנה. במפרט מתוארים הרכיבים האלה ב-API, כמו הנתיב הבסיסי, הנתיבים והפעלים, הכותרות, הפרמטרים של השאילתה, הפעולות, סוגי התוכן, תיאורי התגובות ועוד. בנוסף, בדרך כלל משתמשים במפרט OpenAPI כדי ליצור תיעוד API.

מידע על שירות יעד מדומה של Apigee

שירות היעד לדוגמה של Apigee שבו נעשה שימוש במדריך זה מתארח ב-Apigee ומחזיר נתונים פשוטים. אין צורך במפתח API או באסימון גישה. למעשה, אפשר לגשת אליו בדפדפן אינטרנט. כדי לנסות זאת:

http://mocktarget.apigee.net

שירות היעד מחזיר את הודעת הפתיחה Hello, guest!

כדי לקבל מידע על המערך המלא של ממשקי ה-API שנתמכים על ידי שירות היעד המדמה, אפשר ללחוץ על:

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 שמותקנת במחשב כדי לבצע קריאות ל-API משורת הפקודה או מדפדפן אינטרנט.

יצירת שרת proxy ל-API

Edge

כך יוצרים שרת proxy ל-API ממפרט של OpenAPI באמצעות ממשק המשתמש של Edge:

  1. נכנסים לחשבון בכתובת https://apigee.com/edge.
  2. לוחצים על ממשקי API של API בחלון הראשי.

    לחלופין, אפשר לבחור באפשרות פיתוח > שרתי proxy של API בסרגל הניווט הימני.

    לחיצה על ממשקי proxy של API בדף הנחיתה

  3. לוחצים על + שרת Proxy.
    הוספת שרת proxy ל-API
  4. באשף יצירת שרת Proxy, לוחצים על שימוש במפרט OpenAPI עבור התבנית הפוך שרת proxy (הנפוץ ביותר).
    בניית סוג של שרת proxy
  5. לוחצים על ייבוא מכתובת URL ומזינים את הפרטים הבאים:
    • OpenAPI Spec URL: נתיב לתוכן הגולמי ב-GitHub עבור מפרט OpenAPI בשדה כתובת URL:
      https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget3.0.yaml
    • Spec name: השם למפרט OpenAPI, למשל Mock Target (יעד מדומה).

      השם הזה משמש לאחסון המפרט של OpenAPI בחנות המפרטים. למידע נוסף, אפשר לעיין בניהול המפרטים שלך.

  6. לוחצים על Import.

    דף הפרטים באשף יצירת שרת Proxy מוצג. השדות מאוכלסים מראש באמצעות הערכים שמוגדרים במפרט OpenAPI כפי שמתואר למטה

    בטבלה הבאה מפורטים ערכי ברירת המחדל שמאוכלסים מראש באמצעות מאפיינים במפרט OpenAPI. בהמשך מוצג קטע מהמפרט של OpenAPI שממחיש את המאפיינים שבהם נעשה שימוש.

    שדה התיאור ברירת המחדל
    שם השם של שרת ה-API של שרת ה-API. לדוגמה: Mock-Target-API המאפיין title מהמפרט OpenAPI עם רווחים שהוחלפו במקפים
    נתיב בסיסי רכיב נתיב שמזהה באופן ייחודי את שרת ה-API הזה של שרת proxy בתוך הארגון. כתובת ה-URL הפוכה של ה-API הזה מורכבת משם הארגון, מהסביבה שבה שרת ה-API הזה נפרס, ומהנתיב הבסיסי הזה. לדוגמה: http://myorg-test.apigee.net/mock-target-api התוכן בשדה שם הומר לאותיות קטנות
    תיאור תיאור של שרת proxy ל-API. מאפיין description מהמפרט של OpenAPI
    טירגוט (API קיים) כתובת URL של יעד שמופעלת מטעם שרת proxy זה של API. ניתן להשתמש בכל כתובת 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. בדף 'זרימות', ודא שכל הפעולות מסומנות. בניית תהליכי עבודה לשרת proxy
  11. לוחצים על הבא.
  12. בדף מארחים וירטואליים, בוחרים באפשרות ברירת מחדל ומאובטחת, ולוחצים על Next.
    נבחרו ברירת המחדל ומאובטחת בדף 'מארחים וירטואליים'
  13. בדף Summary (סיכום), מוודאים שסביבת בדיקה מסומנת בקטע Optional Deployment (פריסה אופציונלית) ולוחצים על Create and פריסה (יצירה ופריסה):

    Apigee יוצרת את שרת ה-API החדש ופורסת אותו בסביבת הבדיקה שלך:

  14. לוחצים על Edit proxy כדי להציג את דף הסקירה הכללית של ה-API.
    סיכום של שרת proxy לדוגמה של יעד API

Classic Edge (ענן פרטי)

כדי ליצור שרת proxy של API ממפרט של OpenAPI באמצעות ממשק המשתמש הקלאסי של Edge:

  1. נכנסים לחשבון בכתובת https://apigee.com/edge.
  2. לוחצים על ממשקי API של API בחלון הראשי.

    לחלופין, אפשר לבחור באפשרות פיתוח > שרתי proxy של API בסרגל הניווט הימני.

  3. לוחצים על + שרת Proxy.
    הוספת שרת proxy ל-API
  4. באשף יצירת שרת Proxy, בוחרים באפשרות הפוך שרת Proxy (הנפוץ ביותר) ולוחצים על שימוש ב-OpenAPI.
    בניית סוג של שרת proxy
  5. לוחצים על Import from a URL (ייבוא מכתובת URL), מזינים שם למפרט OpenAPI ומזינים את הנתיב לתוכן הגולמי ב-GitHub עבור המפרט של OpenAPI בשדה URL:

    https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget.yaml
  6. לוחצים על בחירה.
  7. לוחצים על הבא.

    דף הפרטים באשף יצירת שרת Proxy מוצג. השדות מאוכלסים מראש באמצעות הערכים שמוגדרים במפרט OpenAPI כפי שמוצג באיור הבא.

    בניית פרטים של שרת proxy

    בטבלה הבאה מפורטים ערכי ברירת המחדל שמאוכלסים מראש באמצעות מאפיינים במפרט OpenAPI. בהמשך מוצג קטע מהמפרט של OpenAPI שממחיש את המאפיינים שבהם נעשה שימוש.

    שדה התיאור ברירת המחדל
    שם שרת Proxy השם של שרת ה-API של שרת ה-API. לדוגמה: Mock-Target-API המאפיין title מהמפרט OpenAPI עם רווחים שהוחלפו במקפים
    נתיב בסיס של שרת Proxy רכיב נתיב שמזהה באופן ייחודי את שרת ה-API הזה של שרת proxy בתוך הארגון. כתובת ה-URL הפוכה של ה-API הזה מורכבת משם הארגון, מהסביבה שבה שרת ה-API הזה נפרס, ומהנתיב הבסיסי הזה. לדוגמה: http://myorg-test.apigee.net/mock-target-api התוכן בשדה שם הומר לאותיות קטנות
    API קיים כתובת URL של יעד שמופעלת מטעם שרת proxy זה של API. ניתן להשתמש בכל כתובת URL שניתן לגשת אליה דרך האינטרנט הפתוח. לדוגמה: http://mocktarget.apigee.net מאפיין servers מהמפרט של OpenAPI
    תיאור תיאור של שרת proxy ל-API. מאפיין 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. בדף 'זרימות', ודא שכל הפעולות מסומנות. בניית תהליכי עבודה לשרת proxy
  11. לוחצים על הבא.
  12. בדף Security, בוחרים באפשרות Passthrough (none) בתור אפשרות האבטחה ולוחצים על Next.
  13. בדף 'מארחים וירטואליים', מוודאים שכל המארחים הווירטואליים נבחרו ולוחצים על Next (הבא).
  14. בדף Build, מוודאים שסביבת ה-test נבחרה ולוחצים על Build and Deploy (יצירה ופריסה).
  15. בדף הסיכום תופיע אישור על כך ששרת ה-proxy החדש של ה-API נוצר בהצלחה ונפרס בסביבת הבדיקה.
    בניית סיכום של שרת proxy
  16. לוחצים על Mock-Target-API כדי להציג את הדף 'סקירה כללית' של שרת ה-API של שרת ה-API.
    סיכום של שרת proxy לדוגמה של יעד API

כל הכבוד! יצרת שרת proxy ל-API ממפרט של OpenAPI. בשלב הבא צריך לבדוק אותו כדי לראות איך הוא פועל.

בדיקת שרת ה-API

אפשר לבדוק את Mock-Target-API API באמצעות cURL או באמצעות דפדפן אינטרנט.

בחלון טרמינל, מריצים את הפקודה הבאה cURL. מחליפים את שם הארגון בכתובת ה-URL.

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

תשובה

אתם אמורים לראות את התגובה הבאה:

Hello, Guest!        

כל הכבוד! יצרתם שרת proxy פשוט ל-API על סמך מפרט של OpenAPI ובדקתם אותו.

הוספת מדיניות XML ל-JSON

בשלב הבא, צריך להוסיף את מדיניות ה-XML ל-JSON לתהליך המותנה הצגת תגובת XML שנוצרה באופן אוטומטי כשיצרת את שרת ה-API של ה-API מהמפרט OpenAPI. המדיניות תמיר את תגובת ה-XML של היעד לתגובת JSON.

קודם כל, מפעילים את ה-API כדי להשוות בין התוצאות לתוצאות שהתקבלו אחרי הוספת המדיניות. בחלון טרמינל מפעילים את פקודת ה-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' בשרת ה-proxy של ה-API.

  1. לוחצים על הכרטיסייה פיתוח בפינה השמאלית העליונה של הדף 'סקירה כללית של Mock-Target-API' בממשק המשתמש של Edge.
    הכרטיסייה &#39;מפתחים&#39;
  2. בחלונית הניווט הימנית, בקטע Proxy Endpoints > default, לוחצים על התהליך המותנה View XML Response.
    בחירה באפשרות &#39;הצגת תגובת XML&#39;
  3. לוחצים על הלחצן +שלב התחתון, המתאים לתגובה של התהליך.
    בחירת +שלב
    תיבת הדו-שיח 'הוספת שלב' תיפתח ובה תוצג רשימה מסווגת של כל כללי המדיניות שניתן להוסיף.
  4. גלול לקטגוריה 'גישור' ובחר XML ל-JSON.
    תיבת דו-שיח להוספת שלב
  5. משאירים את ערכי ברירת המחדל בשדות Display Name ו-Name.
  6. לוחצים על הוספה. המדיניות מסוג XML ל-JSON חלה על התגובה.בתהליך יצירת מדיניות XML ל-JSON
  7. לוחצים על שמירה.

אחרי שהוספתם את המדיניות, עליכם להפעיל שוב את ה-API באמצעות cURL. שימו לב שאתם עדיין מבצעים קריאות לאותו משאב /xml. שירות היעד עדיין מחזיר את קטע ה-XML שלו, אבל עכשיו המדיניות בשרת ה-API של ה-API תמיר את התגובה ל-JSON. ביצוע השיחה:

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

שימו לב שתגובת ה-XML מומרת ל-JSON:

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

כל הכבוד! בדקת בהצלחה את הביצוע של מדיניות שנוספה לתהליך מותנה.