כרגע מוצג התיעוד של 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 Initiative (OAI) מתמקדת
ביצירה, בפיתוח ובקידום של פורמט תיאור API נייטרלי של הספק, על סמך מפרט Swagger". מידע נוסף על יוזמת ה-Open API זמין בכתובת https://openapis.org.
במפרט OpenAPI נעשה שימוש בפורמט סטנדרטי לתיאור API ל-RESTful. מפרט OpenAPI נכתב בפורמט JSON או YAML. הוא גם קריא למחשבים אבל קל לקריאה ולהבנה. במפרט מתוארים הרכיבים האלה ב-API, כמו הנתיב הבסיסי, הנתיבים והפעלים, הכותרות, הפרמטרים של השאילתה, הפעולות, סוגי התוכן, תיאורי התגובות ועוד. בנוסף, בדרך כלל משתמשים במפרט OpenAPI כדי ליצור תיעוד API.
מידע על שירות יעד מדומה של Apigee
שירות היעד לדוגמה של Apigee שבו נעשה שימוש במדריך זה מתארח ב-Apigee ומחזיר נתונים פשוטים. אין צורך במפתח API או באסימון גישה. למעשה, אפשר לגשת אליו בדפדפן אינטרנט. כדי לנסות זאת:
שירות היעד מחזיר את הודעת הפתיחה Hello, guest!
כדי לקבל מידע על המערך המלא של ממשקי ה-API שנתמכים על ידי שירות היעד המדמה, אפשר ללחוץ על:
מה הדרישות כדי להצטרף לתוכנית?
- חשבון 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 של 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
- Spec name: השם למפרט OpenAPI, למשל Mock Target (יעד מדומה).
השם הזה משמש לאחסון המפרט של OpenAPI בחנות המפרטים. למידע נוסף, אפשר לעיין בניהול המפרטים שלך.
- OpenAPI Spec URL: נתיב לתוכן הגולמי ב-GitHub עבור מפרט OpenAPI בשדה כתובת URL:
- לוחצים על 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 ...
- עורכים את השדה תיאור באופן הבא:
API proxy for the Apigee mock target service endpoint.
- לוחצים על הבא.
- בדף כללי מדיניות נפוצים, בקטע 'אבטחה: הרשאה', מוודאים שהאפשרות מעבר (ללא הרשאה) מסומנת, ולוחצים על הבא:
- בדף 'זרימות', ודא שכל הפעולות מסומנות.
- לוחצים על הבא.
- בדף מארחים וירטואליים, בוחרים באפשרות ברירת מחדל ומאובטחת, ולוחצים על Next.
- בדף Summary (סיכום), מוודאים שסביבת בדיקה מסומנת בקטע Optional Deployment (פריסה אופציונלית) ולוחצים על Create and פריסה (יצירה ופריסה):
Apigee יוצרת את שרת ה-API החדש ופורסת אותו בסביבת הבדיקה שלך:
- לוחצים על Edit proxy כדי להציג את דף הסקירה הכללית של ה-API.
Classic Edge (ענן פרטי)
כדי ליצור שרת proxy של API ממפרט של OpenAPI באמצעות ממשק המשתמש הקלאסי של Edge:
- נכנסים לחשבון בכתובת https://apigee.com/edge.
- לוחצים על ממשקי API של API בחלון הראשי.
לחלופין, אפשר לבחור באפשרות פיתוח > שרתי proxy של API בסרגל הניווט הימני.
- לוחצים על + שרת Proxy.
- באשף יצירת שרת Proxy, בוחרים באפשרות הפוך שרת Proxy (הנפוץ ביותר) ולוחצים על שימוש ב-OpenAPI.
- לוחצים על Import from a URL (ייבוא מכתובת 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 השם של שרת ה-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 ...
- עורכים את השדה תיאור באופן הבא:
API proxy for the Apigee mock target service endpoint.
- לוחצים על הבא.
- בדף 'זרימות', ודא שכל הפעולות מסומנות.
- לוחצים על הבא.
- בדף Security, בוחרים באפשרות Passthrough (none) בתור אפשרות האבטחה ולוחצים על Next.
- בדף 'מארחים וירטואליים', מוודאים שכל המארחים הווירטואליים נבחרו ולוחצים על Next (הבא).
- בדף Build, מוודאים שסביבת ה-test נבחרה ולוחצים על Build and Deploy (יצירה ופריסה).
- בדף הסיכום תופיע אישור על כך ששרת ה-proxy החדש של ה-API נוצר בהצלחה ונפרס בסביבת הבדיקה.
- לוחצים על Mock-Target-API כדי להציג את הדף 'סקירה כללית' של שרת ה-API של שרת ה-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.
- לוחצים על הכרטיסייה פיתוח בפינה השמאלית העליונה של הדף 'סקירה כללית של Mock-Target-API' בממשק המשתמש של Edge.
- בחלונית הניווט הימנית, בקטע Proxy Endpoints > default, לוחצים על התהליך המותנה View XML Response.
- לוחצים על הלחצן +שלב התחתון, המתאים לתגובה של התהליך.
תיבת הדו-שיח 'הוספת שלב' תיפתח ובה תוצג רשימה מסווגת של כל כללי המדיניות שניתן להוסיף.
- גלול לקטגוריה 'גישור' ובחר XML ל-JSON.
- משאירים את ערכי ברירת המחדל בשדות Display Name ו-Name.
- לוחצים על הוספה. המדיניות מסוג XML ל-JSON חלה על התגובה.
- לוחצים על שמירה.
אחרי שהוספתם את המדיניות, עליכם להפעיל שוב את ה-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"}}
כל הכבוד! בדקת בהצלחה את הביצוע של מדיניות שנוספה לתהליך מותנה.