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

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

מידע על Open API Initiative

"The Open API Initiative (OAI) is focused on creating, evolving and promoting a vendor neutral API Description Format based on the Swagger Specification." מידע נוסף על Open API Initiative זמין בכתובת https://openapis.org.

מפרט OpenAPI משתמש בפורמט סטנדרטי כדי לתאר API ל-REST. מפרט 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:

נכנסים לכתובת https://apigee.com/edge.
לוחצים על API Proxies (שרתי proxy ל-API) בחלון הראשי.
אפשרות אחרת היא ללחוץ על פיתוח > שרתי proxy של API בסרגל הניווט הימני.
לוחצים על + שרת proxy.
באשף ליצירת שרת proxy, לוחצים על Use OpenAPI Spec (שימוש במפרט OpenAPI) בתבנית Reverse proxy (most common) (שרת proxy הפוך (הנפוץ ביותר)).
לוחצים על ייבוא מכתובת 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 בחנות המפרטים. מידע נוסף זמין במאמר בנושא ניהול המפרטים.

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

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

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

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

עורכים את השדה תיאור באופן הבא: API proxy for the Apigee mock target service endpoint.
לוחצים על הבא.
בדף Common policies (מדיניות נפוצה), בקטע Security: Authorization (אבטחה: הרשאה), מוודאים שהאפשרות Pass through (no authorization) (העברה (ללא הרשאה)) מסומנת ולוחצים על Next (הבא):
בדף 'זרימות', מוודאים שכל הפעולות נבחרו.
טיפ: תהליכים מותנים נוצרים באופן אוטומטי מהפעולות שמוגדרות באובייקט paths במפרט OpenAPI. זרימות מותנות אומרות ל-Edge: "כשאתה רואה את זה, תבצע את הלוגיקה הזו". לדוגמה, כשקריאה ל-API היא GET במשאב /xml (התנאי), התגובה מומרת ל-JSON (באמצעות מדיניות שמצורפת לזרימה מותנית). רק תהליך אחד מופעל לכל עסקה – התהליך הראשון שהתנאי שלו מוערך כ-true.
לוחצים על הבא.
בדף Virtual hosts (מארחים וירטואליים), בוחרים באפשרויות default (ברירת מחדל) ו-secure (מאובטח) ולוחצים על Next (הבא).
בדף סיכום, מוודאים שסביבת הבדיקה מסומנת בקטע פריסה אופציונלית ולוחצים על יצירה ופריסה:

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

‫Classic Edge (ענן פרטי)

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

נכנסים לכתובת https://apigee.com/edge.
לוחצים על API Proxies (שרתי proxy ל-API) בחלון הראשי.
אפשרות אחרת היא ללחוץ על פיתוח > שרתי proxy של API בסרגל הניווט הימני.
לוחצים על + שרת proxy.
באשף ליצירת שרת proxy, בוחרים באפשרות Reverse proxy (most common) (שרת proxy הפוך (הנפוץ ביותר)) ולוחצים על Use OpenAPI (שימוש ב-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 שפונה לציבור של פרוקסי ה-API הזה מורכבת משם הארגון, מסביבה שבה פרוקסי ה-API הזה נפרס ומנתיב הבסיס הזה. לדוגמה: `http://myorg-test.apigee.net/mock-target-api`	התוכן בשדה שם הומר לאותיות קטנות
API קיים	כתובת ה-URL של היעד שהופעלה בשם ה-API proxy הזה. אפשר להשתמש בכל כתובת URL שאפשר לגשת אליה דרך האינטרנט הפתוח. לדוגמה: `http://mocktarget.apigee.net`	`servers` property מתוך מפרט OpenAPI
תיאור	תיאור של שרת ה-proxy ל-API.	`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
...

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

מעולה! יצרתם 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 לזרימת התנאים View XML Response שנוצרה אוטומטית כשיוצרים את ה-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 to JSON לזרימה המותנית View XML Response ב-API Proxy.

לוחצים על הכרטיסייה Develop (פיתוח) בפינה השמאלית העליונה של הדף Mock-Target-API (ממשק API של יעד מדומה) בממשק המשתמש של Edge.
בחלונית הניווט הימנית, בקטע Proxy Endpoints > default, לוחצים על הזרימה המותנית View XML Response.
לוחצים על הלחצן +Step בתחתית, שמתאים לתשובה של התהליך.

נפתחת תיבת הדו-שיח 'הוספת שלב' ומוצגת רשימה של כל סעיפי המדיניות שאפשר להוסיף, מחולקת לקטגוריות.
גוללים לקטגוריה 'גישור' ובוחרים באפשרות XML to JSON.
משאירים את ערכי ברירת המחדל של השם לתצוגה והשם.
לוחצים על הוספה. מדיניות ה-XML ל-JSON מוחלת על התגובה.
לוחצים על שמירה.

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

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

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

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

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