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

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

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

מה תלמדו

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

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

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

מידע על Open API Initiative

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

מפרט 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:

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

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

עוברים לכתובת ה-URL הבאה בדפדפן האינטרנט:

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

לוחצים לחיצה ימנית על הקוד שמוצג ובוחרים באפשרות שמירה בשם.
לוחצים על שמירה כדי לשמור את mocktarget3.0.yaml במיקום הרצוי.
בשדה OpenAPI specs, לוחצים על הלחצן Browse.
מנווטים לקובץ mocktarget3.0.yaml ולוחצים על פתיחה.
לוחצים על הבא.
בשלב פרטי ה-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 של היעד שהופעלה בשם ה-proxy ל-API הזה. אפשר להשתמש בכל כתובת 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
      ...

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

בדיקת ה-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!

הוספת מדיניות 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.

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

בוחרים באפשרות View XML Response (הצגת תגובת ה-XML).

בחלונית הימנית, בקטע Proxy Endpoints > default, לוחצים על הזרימה המותנית View XML Response.
בחלונית הימנית, לוחצים על הלחצן + בשורה Policies (מדיניות).
בתיבת הדו-שיח Create policy (יצירת מדיניות), לוחצים על השדה Select policy type (בחירת סוג המדיניות), גוללים למטה אל Mediation (גישור) ובוחרים באפשרות XMLToJSON. משאירים את ערכי ברירת המחדל בשדות שם לתצוגה ושם.
לוחצים על יצירה כדי ליצור את המדיניות.
לוחצים על הלחצן + לצד הרכיב View XML response (הצגת תגובת XML) ברכיב Response (תגובה).
בתיבת הדו-שיח Add Policy Step (הוספת שלב מדיניות), לוחצים על השדה Select existing policy (בחירת מדיניות קיימת) ובוחרים באפשרות XML to JSON-1 (מ-XML ל-JSON-1).
לוחצים על הוספה. מדיניות ה-XML ל-JSON מוחלת על התגובה.

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

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

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