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

הדף הזה רלוונטי ל-Apigee ול-Apigee Hybrid.

לעיון במסמכי התיעוד של Apigee Edge

מה תלמדו

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

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

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

מידע על Open API Initiative

"ה-Open API Initiative‏ (OAI) מתמקד ביצירה, בפיתוח ובקידום של פורמט תיאור API ניטרלי לספקים שמבוסס על מפרט Swagger". מידע נוסף על Open API Initiative זמין במאמר מפרט OpenAPI.

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

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

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

http://mocktarget.apigee.net

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

מידע על כל ממשקי ה-API ששירות היעד המדומה תומך בהם זמין במאמר Apigee Sample APIs.

הדרישות

• לפני שמתחילים, צריך לבצע את השלבים שמפורטים במאמר סקירה כללית ודרישות מוקדמות.
• מפרט OpenAPI. במדריך הזה תשתמשו במפרט mocktarget.yaml OpenAPI שמתאר את שירות היעד המדומה של Apigee,‏ http://mocktarget.apigee.net. מידע נוסף זמין במאמר apigee/api-platform-samples.
• ‫cURL מותקן במחשב כדי לבצע קריאות ל-API משורת הפקודה, או דפדפן אינטרנט.

יצירת proxy ל-API

כדי ליצור את ה-proxy ל-API ממפרט OpenAPI:

1. במסוף Google Cloud , נכנסים לדף Apigee > Proxy development > API proxies.

   מעבר לשרתי proxy ל-API

2. בחלונית API Proxies (שרתי proxy של API), לוחצים על + Create (יצירה).
3. בחלונית Create a proxy (יצירת שרת proxy), בקטע Proxy template (תבנית שרת proxy) > OpenAPI spec template (תבנית מפרט OpenAPI), בוחרים באפשרות Reverse proxy (Most common) (שרת proxy הפוך (הנפוץ ביותר)).
4. עוברים לכתובת ה-URL הבאה בדפדפן האינטרנט:

   https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget3.0.yaml

5. לוחצים לחיצה ימנית על הקוד שמוצג ובוחרים באפשרות שמירה בשם.
6. לוחצים על שמירה כדי לשמור את mocktarget3.0.yaml במיקום הרצוי.
7. בשדה OpenAPI specs, לוחצים על הלחצן Browse.
8. מנווטים לקובץ mocktarget3.0.yaml ולוחצים על פתיחה.
9. לוחצים על הבא.
10. בשלב פרטי ה-Proxy באשף יצירת Proxy, השדות מאוכלסים באופן אוטומטי בערכים שנלקחים ישירות ממפרט OpenAPI.

בטבלה הבאה מפורטים ערכי ברירת המחדל שמולאו מראש באמצעות מפרט OpenAPI:

שדה	תיאור	ברירת מחדל
שם ה-proxy	השם של ה-proxy ל-API. לדוגמה: Mock-Target-API.	המאפיין title ממפרט OpenAPI עם רווחים שהוחלפו במקפים
נתיב בסיסי	רכיב נתיב שמזהה באופן ייחודי את ה-proxy ל-API הזה בארגון. כתובת ה-URL שפונה לציבור של ה-proxy ל-API הזה מורכבת משם הדומיין החיצוני או הפנימי שלכם ומנתיב הבסיס הזה. לדוגמה: http://apitest.acme.com/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
      ...
      

11. בשלב פרטי ה-Proxy, עורכים את השדה תיאור באופן הבא:

    API proxy for the Apigee mock target service endpoint.

12. לוחצים על הבא.
13. בשלב Flows, מוודאים שכל הפעולות נבחרו.
    כדאי לדעת: תהליכים מותנים נוצרים באופן אוטומטי מהפעולות שמוגדרות באובייקט paths במפרט OpenAPI. תנאים ב-Flows אומרים ל-Apigee: "כשאתה רואה את זה, תבצע את הלוגיקה הזו". לדוגמה, כשקריאה ל-API היא GET במשאב /xml (התנאי), המערכת משנה את התגובה ל-JSON (באמצעות מדיניות שמצורפת לזרימה מותנית). רק תהליך אחד מופעל לכל עסקה – התהליך הראשון שהתנאי שלו מוערך כ-true.
14. לוחצים על הבא.
15. בשלב פריסה, בוחרים סביבה אחת או יותר ולוחצים על אישור.
16. לוחצים על יצירה.

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

בדיקת ה-proxy ל-API

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

curl -v YOUR_ENV_GROUP_HOSTNAME/myproxy

כאשר YOUR_ENV_GROUP_HOSTNAME הוא שם המארח של קבוצת הסביבות. אפשר לעיין במאמר בנושא חיפוש שם המארח של קבוצת הסביבות.

לדוגמה:

curl -v -k https://apitest.acme.com/myproxy

תשובה

אמורה להתקבל התגובה הבאה:

Hello, Guest!

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

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

בשלב הבא, מוסיפים את מדיניות ה-XML ל-JSON לזרימת התנאים View XML Response שנוצרה אוטומטית כשיוצרים את proxy ל-API ממפרט OpenAPI. המדיניות תמיר את תגובת ה-XML של היעד לתגובת JSON.

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

curl -v https://YOUR_ENV_GROUP_HOSTNAME/mock-target-api/xml

כאשר YOUR ENV_GROUP_HOSTNAME הוא שם המארח של קבוצת הסביבות. אפשר לעיין במאמר בנושא איתור שם המארח של קבוצת הסביבות.

תשובה

אמורה להתקבל התגובה הבאה:

<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.

1. בממשק המשתמש של Apigee, בדף Mock-Target-API Overview, לוחצים על הכרטיסייה Develop.



2. בחלונית הימנית, בקטע Proxy Endpoints > default, לוחצים על הזרימה המותנית View XML Response.
3. בחלונית הימנית, לוחצים על הלחצן + בשורה Policies (מדיניות).

4. בתיבת הדו-שיח Create policy (יצירת מדיניות), לוחצים על השדה Select policy type (בחירת סוג מדיניות), גוללים למטה אל Mediation (גישור) ובוחרים באפשרות XMLToJSON. משאירים את ערכי ברירת המחדל של השם לתצוגה והשם.

5. לוחצים על יצירה כדי ליצור את המדיניות.

6. לוחצים על הלחצן + לצד הרכיב View XML response (הצגת תגובת XML) ברכיב Response (תגובה).

   

7. בתיבת הדו-שיח Add Policy Step (הוספת שלב למדיניות), לוחצים על השדה Select existing policy (בחירת מדיניות קיימת) ובוחרים באפשרות XML to JSON-1 (מ-XML ל-JSON-1).

8. לוחצים על הוספה. מדיניות ה-XML ל-JSON מוחלת על התגובה.

   

   כדי לראות את הקוד של הזרימה המותנית View XML Response, לוחצים על Switch To Code Editor.

9. לוחצים על Save.

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

curl -v https://YOUR_ENV_GROUP_HOSTNAME/mock-target-api/xml

כאשר YOUR ENV_GROUP_HOSTNAME הוא שם המארח של קבוצת הסביבות. אפשר לעיין במאמר בנושא איתור שם המארח של קבוצת הסביבות.

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

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

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