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

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

מידע על יוזמת ה-API הפתוחה

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

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

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

שירות היעד mock של 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:

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

לוחצים על ייבוא.

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

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

שדה	תיאור	ברירת מחדל
שם	השם של ה-Proxy ל-API. לדוגמה: `Mock-Target-API`.	מאפיין אחד (`title`) ממפרט OpenAPI עם רווחים הוחלפו לפי מקפים
הנתיב הבסיסי	רכיב נתיב שמזהה באופן ייחודי את שרת ה-proxy הזה ל-API בתוך הארגון. כתובת ה-URL הציבורית של שרת ה-proxy הזה ל-API מורכבת משם הארגון שלך, שבה שרת ה-proxy ל-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
...

עורכים את השדה תיאור באופן הבא: API proxy for the Apigee mock target service endpoint.
לוחצים על הבא.
בדף Common policy, בקטע 'אבטחה': הרשאה מוודאים שהאפשרות Pass through (no authorization) מסומנת ולוחצים על Next:
בדף Flows, מוודאים שכל הפעולות מסומנות.
טיפ: תהליכי העבודה המותנים נוצרים באופן אוטומטי מהמקורות הפעולות שמוגדרות באובייקט paths ב-OpenAPI מפרט. תהליכים מותנים מורים ל-Edge, "כאשר רואים את זה, מבצעים את הלוגיקה הזו". לדוגמה, כשהקריאה ל-API היא GET במשאב /xml (התנאי), הופכים את התשובה ל-JSON (באמצעות מדיניות שמצורפת לתהליך המותנה). רק תהליך אחד מסתיים לכל עסקה – התהליך הראשון שהתנאי שלו מחושב נכון.
לוחצים על הבא.
בדף מארחים וירטואליים, בוחרים באפשרות ברירת מחדל ומאובטחים ולוחצים על הבא.
בדף Summary, מוודאים שסביבת Test שנבחרת בקטע Optional Deployment (פריסה אופציונלית) ולוחצים על Create and (יצירה) deploy:

Apigee יוצר שרת proxy חדש ל-API ופורס אותו בסביבת הבדיקה:
לוחצים על עריכת שרת proxy כדי להציג את דף הסקירה הכללית של ה-API. שרת proxy.

Classic Edge (ענן פרטי)

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

נכנסים לחשבון בכתובת https://apigee.com/edge.
לוחצים על שרתי proxy ל-API בחלון הראשי.
לחלופין, אפשר לבחור באפשרות פיתוח > שרתי proxy ל-API בסרגל הניווט הימני.
לוחצים על + Proxy.
באשף 'יצירת שרת Proxy', בוחרים באפשרות שרת Proxy הפוך (הנפוץ ביותר) ואז לוחצים על שימוש ב-OpenAPI.
לוחצים על ייבוא מכתובת URL, מזינים שם למפרט OpenAPI ומזינים את הנתיב לתוכן הגולמי ב-GitHub בשביל OpenAPI. מפרט בשדה כתובת URL:

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

לוחצים על הבא.

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

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

שדה	תיאור	ברירת מחדל
שם שרת ה-proxy	השם של ה-Proxy ל-API. לדוגמה: `Mock-Target-API`.	מאפיין אחד (`title`) ממפרט OpenAPI עם רווחים הוחלפו לפי מקפים
נתיב הבסיס של שרת ה-proxy	רכיב נתיב שמזהה באופן ייחודי את שרת ה-proxy הזה ל-API בתוך הארגון. כתובת ה-URL הציבורית של שרת ה-proxy הזה ל-API מורכבת משם הארגון שלך, שבה שרת ה-proxy ל-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
...

עורכים את השדה תיאור באופן הבא: API proxy for the Apigee mock target service endpoint.
לוחצים על הבא.
בדף Flows, מוודאים שכל הפעולות מסומנות.
טיפ: תהליכי העבודה המותנים נוצרים באופן אוטומטי מהמקורות הפעולות שמוגדרות באובייקט paths ב-OpenAPI מפרט. תהליכים מותנים מורים ל-Edge, "כאשר רואים את זה, מבצעים את הלוגיקה הזו". לדוגמה, כשהקריאה ל-API היא GET במשאב /xml (התנאי), הופכים את התשובה ל-JSON (באמצעות מדיניות שמצורפת לתהליך המותנה). רק תהליך אחד מסתיים לכל עסקה – התהליך הראשון שהתנאי שלו מחושב נכון.
לוחצים על הבא.
בדף 'אבטחה', בוחרים באפשרות עבר (ללא) בתור רמת האבטחה ולוחצים על הבא.
בדף 'מארחים וירטואליים', מוודאים שכל המארחים הווירטואליים נבחרו ולוחצים על הבא.
בדף Build, מוודאים שסביבת הבדיקה מסומנת. לוחצים על Build and Deploy (יצירה ופריסה).
בדף 'סיכום', מופיע אישור על כך ששרת ה-Proxy החדש ל-API נוצר. ופרוסות בהצלחה בסביבת הבדיקה.
לוחצים על Mock-Target-API כדי להציג את הדף 'סקירה כללית' של ה-API. שרת proxy.

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

בדיקת ה-Proxy ל-API

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

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

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

תגובה

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

Hello, Guest!

כל הכבוד! בניתם שרת proxy פשוט ל-API ממפרט OpenAPI ובדקתם את זה.

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

בשלב הבא צריך להוסיף את המדיניות בפורמט XML ל-JSON אל הצגת תגובת ה-XML תהליך מותנה שנוצר באופן אוטומטי כשיצרתם את ה-Proxy ל-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.

לוחצים על הכרטיסייה פיתוח בפינה השמאלית העליונה של Mock-Target-API דף הסקירה הכללית בממשק המשתמש של Edge.
בחלונית Navigator השמאלית, בקטע Proxy Endpoints > כברירת מחדל, לוחצים על הלחצן תצוגה תהליך מותנה של תגובת XML.
לוחצים על הלחצן +שלב התחתון, שתואם תגובה לתהליך.

בתיבת הדו-שיח 'הוספת שלב' תיפתח רשימה של כל כללי המדיניות שניתן לחלק לקטגוריות הוספה
גוללים לקטגוריה 'תהליך בחירת הרשת (Mediation)' ובוחרים מ-XML ל-JSON.
שמור את ערכי ברירת המחדל עבור שם התצוגה וכן שם.
לוחצים על הוספה. מדיניות XML ל-JSON מוחלת על התשובה.
לוחצים על שמירה.

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

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

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

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

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