כרגע מוצג התיעוד של Apigee Edge.
כניסה למסמכי התיעוד של
Apigee X. מידע
כספקי שירות, אתם מפתחים ממשקי API לצריכה על ידי אפליקציות לקוח. כדי ליצור, להגדיר ולתחזק שרתי proxy של API ומוצרי API, אפשר להשתמש בממשק המשתמש או לשלוח בקשות HTTP לממשקי ה-API כדי לגשת לשירותי RESTful, כפי שמתואר בקטעים הבאים.
שימוש בממשק המשתמש של Edge
ממשק המשתמש של Apigee Edge הוא כלי מבוסס-דפדפן שאפשר להשתמש בו כדי ליצור, להגדיר ולנהל שרתי proxy של API ומוצרי API. אפשר לבצע קבוצת משנה של משימות רק באמצעות ה-API.
בטבלה הבאה מוסבר איך נכנסים לממשק המשתמש של Edge:
מוצר | שם ממשק המשתמש | כתובת URL לגישה |
---|---|---|
Edge | ממשק המשתמש של Edge | כדי להיכנס לממשק המשתמש של Edge צריך להשתמש בכתובת ה-URL הבאה: https://apigee.com/edge תוכלו לקרוא מדריך על השימוש בממשק המשתמש של Edge במאמר יצירת שרת proxy ראשון ל-API. |
Edge לענן פרטי | ממשק המשתמש הקלאסי של Edge | כדי להיכנס לממשק המשתמש של Edge בענן פרטי צריך להשתמש בכתובת ה-URL הבאה: http://ms-ip:9000 כאשר ms-ip הוא כתובת ה-IP או שם ה-DNS של הצומת של שרת הניהול. |
אפשר לבצע את הפעולות הבאות בממשק המשתמש של Edge:
- אפשר ליצור שרתי proxy ל-API על ידי עריכת הקוד ומעקב אחר זרימות הבקשות דרך שרתי ה-proxy.
- יצירת מוצרי API שמשלבים שרתי proxy כדי לחשוף את המשתמשים לבקשות של לקוחות.
- לנהל מפתחים ואפליקציות למפתחים.
- מגדירים את סביבות הבדיקה והייצור.
- מטמיעים אפליקציות JavaScript ו-Node.js.
בתמונה הבאה מוצג עורך ה-API של שרת ה-proxy בממשק המשתמש, שבו אפשר להשתמש כדי ליצור ולהגדיר שרת proxy של API:
שימוש ב-Edge API
כדי לנהל את משאבי ה-API אפשר להשתמש ב-Edge API. ממשקי ה-API מספקים גם גישה ליכולות ברמה נמוכה, שלא חשופות בממשק המשתמש.
נקודות הקצה של ה-API בדרך כלל משתמשות בנתונים שמכילים פרטי הגדרה ודורשות מכם
להזין פרטי אימות כמו שם משתמש וסיסמה, כדי לגשת אליהן. לפי העקרונות של RESTful, אפשר לקרוא ל-methods GET
, POST
, PUT
וגם DELETE
בכל אחד ממשאבי ה-API.
בחומר העזר בנושא API של Apigee Edge יש רשימה מלאה של ממשקי ה-API של Apigee Edge.
הסבר על הנתיב הבסיסי של Edge API
הנתיב שבו תשתמשו בבקשות API משורשר:
- נתיב בסיסי שכולל את שם הארגון. לדוגמה:
https://api.enterprise.apigee.com/v1/organizations/org_name
- נקודת קצה שמפנה למשאב Edge שאליו אתם ניגשים.
לדוגמה, אם שם הארגון הוא apibuilders
, בכל קריאה ל-API ייעשה שימוש בנתיב הבסיס הבא:
https://api.enterprise.apigee.com/v1/organizations/apibuilders
כדי לאחזר רשימה של שרתי proxy של API בארגון, צריך להפעיל את GET ב:
https://api.enterprise.apigee.com/v1/organizations/apibuilders/apis
משאבים רבים מוגבלים על ידי הסביבה. כברירת מחדל, קיימות שתי סביבות: test ו-prod. לדוגמה, מטמונים נשמרים לפי סביבה. מטמון משותף שנקרא 'mycache' נכלל כברירת מחדל בכל סביבה.
ניתן להציג רשימה של קובצי מטמון על ידי קריאה ל-GET במשאב של המטמון באופן הבא:
https://api.enterprise.apigee.com/v1/organizations/apibuilders/environments/test/caches https://api.enterprise.apigee.com/v1/organizations/apibuilders/environments/prod/caches
אימות הגישה
אתם צריכים לאמת את עצמכם מול שרת ה-API כשאתם קוראים לממשקי ה-API. ניתן לעשות זאת באחת מהדרכים הבאות:
- OAuth2
- SAML
- אימות בסיסי (לא מומלץ)
בנוסף, ההמלצה של Apigee היא להשתמש באימות דו-שלבי, כפי שמתואר במאמר הפעלת אימות דו-שלבי בחשבון Apigee.
מגבלות של Edge API
כל ארגון מוגבל לתעריפי השיחות הבאים של Edge API:
- 10,000 שיחות בדקה לארגונים בתוכניות בתשלום
- 600 קריאות לדקה לארגונים לתקופת ניסיון
קודי מצב HTTP 401
ו-403
לא נספרים כחלק מהמגבלה הזו. שיחות שחורגות מהמגבלות האלה מחזירות קוד סטטוס 429 Too Many Requests
.
טיפים לעבודה עם ממשקי Edge של Edge
בקטע הזה מתוארות כמה טכניקות שמקלות על העבודה עם ממשקי API של Edge.
קיצור כתובות URL של בקשות
כשיוצרים את כתובת ה-URL של הבקשה לממשקי API של Edge, אפשר להשתמש בקיצורים הבאים:
/e = /environments
/o = /organizations
/r = /revisions
אם אתם משתמשים בקיצורים, צריך להשתמש בהם באופן עקבי. כלומר, לקצר את כל הרכיבים בנתיב, כפי שצוין למעלה ומודגם בדוגמה הבאה, או ללא קשר. שימוש ברכיבים מלאים וברכיבי מקוצרים באותו נתיב יוביל לשגיאה.
לדוגמה:
THIS: https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval/environments/prod/apis/helloworld/revisions/1/deployments CAN BE MUCH SHORTER: https://api.enterprise.apigee.com/v1/o/ahamilton-eval/e/prod/apis/helloworld/r/1/deployments
הרצה של פקודות curl
שימוש בלקוח HTTP כדי לשלוח בקשות ל-API. במסמכים רבים מופיעות בקשות API לדוגמה באמצעות curl
, לקוח HTTP שנמצא בשימוש נרחב. אם צריך
להתקין את curl
, אפשר להוריד אותו מהכתובת
http://curl.haxx.se.
קריאות ל-API תומכות בדחיסת gzip בתגובות. אם מגדירים את 'Accept-Encoding: gzip, deflate'
בקריאות ל-API, כל תגובה שגדולה מ-1,024 בייטים תוחזר בפורמט gzip.
עיצוב בקשות ותגובות מסוג XML ו-JSON
כברירת מחדל, ממשק Edge API מחזיר נתונים כ-JSON. במקרים רבים, אפשר לקבל במקום זאת את התגובה שנשלחה בחזרה בפורמט XML. כדי לעשות זאת, צריך להגדיר את כותרת הבקשה Accept
לערך
application/xml
, כמו בדוגמה הבאה:
curl -H "Authorization: Bearer `get_token`" \ -H "Accept: application/xml" \ https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval/apis/helloworld/revisions/1/policies/ \ | xmllint --format -
התגובה אמורה להיראות כך:
<List> <Item>SOAP-Message-Validation-1</Item> <Item>Spike-Arrest-1</Item> <Item>XML-to-JSON-1</Item> </List>
חשוב לשים לב שבדוגמה הזו נעשה שימוש ב-prettyprint
כדי להציג את התוצאות על ידי העברת התשובה דרך xmllint
.
הכלי acurl
לא תומך בכותרת Accept
. כתוצאה מכך, אפשר
לקבל רק תשובות בפורמט JSON באמצעות acurl
.
כדי להשתמש ב-prettyprint
לתגובת JSON, אפשר להשתמש בספריית Python json.tool
:
curl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval/apis/helloworld/revisions/1/policies/ \ -H "Accept: application/json" \ -H "Authorization: Bearer `get_token`" \ | python -m json.tool
למטה מוצגת דוגמה לתשובה:
[ "SOAP-Message-Validation-1", "Spike-Arrest-1", "XML-to-JSON-1" ]
בפורמט XML, אפשר להשתמש ב-xmllint
:
curl https://ahamilton-eval-test.apigee.net/getstarted -u email_address | xmllint --format -
כשמבצעים פרסום או העברה של מטענים ייעודיים (payloads) ב-XML, צריך להשתמש בכותרת ה-HTTP Content-type
:
acurl -H "Content-type:text/xml" -X POST -d \ '<XMLPayload> </XMLPayload> ' \ https://api.enterprise.apigee.com/v1/organizations/apifactory/apis -u email_address
סביבות פריסה
לכל ארגון שמשתמש ב-Apigee Edge כברירת מחדל יש לפחות שתי סביבות שיוכלו להשתמש בהן כדי לפתח, לבדוק ולפרוס ממשקי API: 'test' ו-'prod'. סביבת 'בדיקה' מאפשרת לפתח ולבדוק את ממשקי ה-API לפני שהם זמינים לציבור הרחב. רק המפתחים הפנימיים שלכם יכולים לגשת לממשקי API שנפרסו בסביבת הבדיקה. פורסים את ממשקי ה-API בסביבת ה "ייצור" כדי שיהיו זמינים למפתחי אפליקציות באופן ציבורי.
ניפוי באגים ובדיקה
ב-Apigee יש כלי מעקב שמאפשר לנפות באגים לתהליכי תגובה ובקשות מקצה לקצה. בתוצאות המעקב מוצגים כותרות ומטענים ייעודיים (payload) של בקשות ותגובות, ביצוע מדיניות, ערכי משתנים וכל שגיאה שאירעו במהלך הזרימה.
נקודות נתונים עיקריות לשימוש בפתרון בעיות:
- חותמות זמן: אפשר להשתמש בחותמות זמן כדי לראות כמה זמן נדרש לביצוע כל שלב. בעזרת השוואה בין חותמות הזמן אפשר לבודד את כללי המדיניות שמשך הביצוע שלהם הוא הארוך ביותר, שמאטים את הקריאות ל-API.
- הנתיב הבסיסי: אימות הנתיב הבסיסי מאפשר לוודא שמדיניות מנתבת את ההודעה לשרת הנכון.
- תוצאות הביצוע של המדיניות: התוצאות האלה מאפשרות לכם לראות אם ההודעה עוברת שינוי כצפוי, למשל אם ההודעה עוברת המרה מ-XML ל-JSON, או אם ההודעה נשמרת במטמון.
האיור הבא מציג תוצאות מעקב:
כל פעילות מעקב מתחלקת לשלבים העיקריים הבאים:
- בקשה מקורית התקבלה מהלקוח: מציגה את פועל ונתיב ה-URI של הבקשה מאפליקציית הלקוח, בכותרות, נתוני גוף ופרמטרים של שאילתה.
- בקשה שנשלחה לשירות לקצה העורפי: מציגה את הודעת הבקשה שנשלחה לשירות לקצה העורפי על ידי שרת ה-API של שרת ה-API.
- תגובה שהוחזרה על ידי השירות לקצה העורפי: מציג את כותרות התגובות ואת המטען הייעודי (payload) שהוחזר על ידי השירות לקצה העורפי.
- תשובה סופית נשלחה ללקוח: הודעת התגובה שהוחזרה לאפליקציית הלקוח ששלחה את הבקשה, אחרי שתהליך התגובה הסתיים.