כלים למפתחים

אתם צופים במסמכי התיעוד של Apigee Edge.
כדאי לעיין במסמכי התיעוד של Apigee X. מידע

כספקי שירות, אתם מפתחים ממשקי API לשימוש באפליקציות לקוח. כדי ליצור, להגדיר ולתחזק שרתי proxy ל-API ומוצרי API, אפשר להשתמש בממשק המשתמש או לשלוח בקשות HTTP אל ממשקי ה-API כדי לגשת לשירותים מבוססי REST, כמו שמתואר בקטעים הבאים.

שימוש בממשק המשתמש של Edge

ממשק המשתמש של Apigee Edge הוא כלי מבוסס-דפדפן שבו אפשר ליצור, להגדיר ולנהל שרתי proxy ל-API ומוצרי API. יש גם קבוצת משנה של משימות שאפשר לבצע רק באמצעות ה-API.

בטבלה הבאה מוסבר איך לגשת לממשק המשתמש של Edge:

מוצר שם ממשק המשתמש כתובת URL לגישה
Edge ממשק משתמש של Edge

כדי לגשת לממשק המשתמש של Edge, משתמשים בכתובת ה-URL הבאה:

https://apigee.com/edge

מדריך לשימוש בממשק המשתמש של Edge זמין במאמר יצירת proxy ל-API ראשון.
‫Edge for Private Cloud  ממשק משתמש קלאסי של Edge

כדי לגשת לממשק המשתמש של Edge ב-Edge for Private Cloud, משתמשים בכתובת ה-URL הבאה:

http://ms-ip:9000

כאשר ms-ip היא כתובת ה-IP או שם ה-DNS של צומת שרת הניהול.

באמצעות ממשק המשתמש של Edge, אפשר:

  • יוצרים שרתי proxy של API על ידי עריכת קוד ומעקב אחרי זרימות בקשות דרך השרתים האלה.
  • יוצרים מוצרי API שכוללים חבילות של שרתי proxy כדי לחשוף אותם לבקשות של לקוחות.
  • ניהול מפתחים ואפליקציות למפתחים.
  • מגדירים את סביבות הבדיקה והייצור.
  • הטמעה של אפליקציות JavaScript ו-Node.js.

בתמונה הבאה מוצג עורך שרתי ה-proxy ל-API בממשק המשתמש, שבו אפשר ליצור ולהגדיר שרת proxy ל-API:

תמונה שבה רואים את הכרטיסייה Develop (פיתוח) שנבחרה בכלי לעריכת proxy ל-API בממשק המשתמש של Edge.

שימוש ב-Edge API

אתם יכולים להשתמש ב-Edge API כדי לנהל את משאבי ה-API. ממשקי ה-API גם מספקים גישה ליכולות ברמה נמוכה שלא מוצגות בממשק המשתמש.

נקודות הקצה של ה-API מקבלות לעיתים קרובות נתונים שמכילים פרטי הגדרה, ונדרש להעביר פרטי אימות כמו שם משתמש וסיסמה כדי לגשת אליהן. בהתאם לעקרונות של RESTful, אפשר לקרוא לשיטות HTTP‏ GET,‏ POST,‏ PUT ו-DELETE בכל אחד מהמשאבים של ה-API.

רשימה מלאה של ממשקי Apigee Edge API מופיעה בהפניית Apigee Edge API.

הסבר על נתיב הבסיס של Edge API

הנתיב שבו משתמשים בבקשות ל-API הוא שרשור של הרכיבים הבאים:

  • נתיב בסיס שכולל את שם הארגון. לדוגמה: https://api.enterprise.apigee.com/v1/organizations/org_name
  • נקודת קצה (endpoint) שמפנה למשאב 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. אפשר לעשות את זה באחת מהדרכים הבאות:

בנוסף, מומלץ להשתמש באימות דו-שלבי, כמו שמתואר במאמר הפעלת אימות דו-שלבי בחשבון Apigee.

מגבלות של Edge API

לכל ארגון יש מגבלות על קצב הקריאות ל-Edge API:

  • ‫10,000 שיחות לדקה לארגונים עם תוכניות בתשלום
  • ‫600 שיחות בדקה לארגונים בתקופת ניסיון

קודי מצב HTTP‏ 401 ו-403 לא נכללים במגבלה הזו. אם תחרגו מהמגבלות האלה, תקבלו קוד סטטוס 429 Too Many Requests.

טיפים לעבודה עם ממשקי Edge API

בקטע הזה מתוארות כמה טכניקות שיכולות להקל על העבודה עם ממשקי ה-API של Edge.

קיצור כתובות URL של בקשות

כשיוצרים את כתובת ה-URL של הבקשה לממשקי Edge API, אפשר להשתמש בקיצורים הבאים:

  • /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 -

כששולחים מטען ייעודי (payload) באמצעות POST או PUT ב-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 שלכם, צריך לפרוס אותם בסביבת הייצור (prod).

ניפוי באגים ובדיקות

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

נקודות נתונים חשובות לשימוש בפתרון בעיות:

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

באיור הבא מוצגות תוצאות של מעקב:

תמונה שבה רואים את הכרטיסייה Trace (מעקב) שנבחרה בכלי לעריכת proxy ל-API בממשק המשתמש של Edge.

כל סשן של Trace מחולק לשלבים העיקריים הבאים:

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