פרסום ממשקי ה-API (הגרסה המקורית)

כרגע מוצג התיעוד של Apigee Edge.
כניסה למסמכי התיעוד של Apigee X.
מידע

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

סקירה כללית על פרסום באמצעות API

התהליך של פרסום ממשקי API בפורטל הוא תהליך דו-שלבי:

  1. בוחרים את מוצר ה-API שרוצים לפרסם בפורטל.
  2. יצירה אוטומטית של מסמכי תיעוד של הפניות API מתמונת מצב של מפרט OpenAPI כדי לאפשר למפתחי אפליקציות ללמוד על ממשקי ה-API שלך. (מידע נוסף על תמונות מצב זמין במאמר מהי תמונת מצב של מפרט OpenAPI?

כשמפרסמים ממשק API בפורטל, העדכונים הבאים מתבצעים בפורטל באופן אוטומטי:

  • דף הפניה של API נוסף לפורטל
    בדף ההפניה ל-API מוצג תיעוד של חומרי העזר ל-API שנוצר באופן אוטומטי מתוך תמונת מצב של מפרט OpenAPI. המפתחים יכולים לעיין בתיעוד ה-API וללחוץ על Try It כדי לשלוח בקשת API ולצפות בפלט.

    הערה: לא ניתן לערוך את התוכן בדף הזה באופן ישיר, הוא לא מופיע ברשימת הדפים בפורטל שלך.

  • לדף ממשקי ה-API יתווסף קישור לדף המידע על ממשקי API
    בדף ממשקי ה-API (שכלול בפורטל לדוגמה) יש רשימה של כל ממשקי ה-API שפורסמו בפורטל שלכם, עם קישורים למאמרי העזרה בנושא ממשקי ה-API הרלוונטיים.

    הערה: לא ניתן לערוך את התוכן בדף הזה באופן ישיר, הוא לא מופיע ברשימת הדפים בפורטל שלך.

מהי תמונת מצב של מפרט OpenAPI?

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

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

הוספה של תמיכה ב-CORS לשרתי proxy של API

לפני פרסום ממשקי ה-API, עליך להוסיף תמיכת CORS לשרתי ה-proxy של ה-API כדי לתמוך בבקשות ממקורות שונים בצד הלקוח.

CORS (שיתוף משאבים בין מקורות) הוא מנגנון סטנדרטי שמאפשר לקריאות XMLHttpRequest (XHR) של JavaScript המבוצעות בדף אינטרנט לבצע אינטראקציה עם משאבים מדומיינים שאינם מקור. CORS היא פתרון שמוטמע בדרך כלל למדיניות מקור זהה שנאכפת על ידי כל הדפדפנים. לדוגמה, אם תבצע קריאת XHR ל-API של Twitter מקוד JavaScript שהופעל בדפדפן, הקריאה תיכשל. הסיבה לכך היא שהדומיין שמציג את הדף בדפדפן שלך אינו זהה לדומיין שמציג את ממשק ה-API של Twitter. CORS היא פתרון לבעיה הזו: היא מאפשרת לשרתים "להביע הסכמה" אם הם רוצים לשתף משאבים בין מקורות.

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

הערה: רוב הדפדפנים המודרניים אוכפים את CORS. מעיינים ברשימה המקיפה של הדפדפנים הנתמכים. לתיאור מפורט של CORS, כדאי לעיין בהמלצה של ארגון W3C לשיתוף משאבים בין מקורות.

היכרות עם דף ממשקי ה-API

כדי לגשת לדף ממשקי ה-API:

  1. בוחרים פרסום > פורטלים ובוחרים את הפורטל שלכם.
  2. לוחצים על ממשקי API בדף הבית של הפורטל.

לחלופין, אפשר לבחור באפשרות ממשקי API בתפריט הנפתח של הפורטל בסרגל הניווט העליון.

תוצג רשימה של ממשקי ה-API.

הפניית API

כפי שמודגש באיור הקודם, דף ממשקי ה-API מאפשר:

הוספת API לפורטל

הערה: אתם יכולים להוסיף לפורטל עד 100 ממשקי API.

כדי להוסיף API לפורטל:

  1. בוחרים פרסום > פורטלים ובוחרים את הפורטל שלכם.
  2. לוחצים על ממשקי API בדף הבית של הפורטל.
    לחלופין, אפשר לבחור ממשקי API בתפריט הנפתח של הפורטל בסרגל הניווט העליון.
  3. לוחצים על + API.
    תיבת הדו-שיח 'הוספת מוצר של ממשק API לפורטל' מוצגת.
  4. בכרטיסייה 'מוצר API' בתיבת הדו-שיח, בוחרים את מוצר ה-API שרוצים להוסיף לפורטל.

  5. לוחצים על הבא.

  6. בוחרים את המקור שממנו רוצים ליצור את תמונת המצב.
    אם יצרתם את שרת ה-API של ה-API שכלול במוצר ה-API באמצעות מפרט OpenAPI, בוחרים את המפרט מהרשימה הנפתחת.
    הוספת תמונת מצב

    לחלופין, אפשר לבחור באפשרויות הבאות:

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

  8. בקטע 'קהל', בוחרים באחת מהאפשרויות הבאות כדי לנהל את הקהל עבור ה-API על ידי מתן הרשאת גישה אל:

    • משתמשים אנונימיים כדי לאפשר לכל המשתמשים להציג את הדף.
    • משתמשים רשומים כדי לאפשר רק למשתמשים רשומים לצפות בדף.

    תוכלו לשנות את ההגדרה מאוחר יותר, כפי שמתואר במאמר ניהול הקהל עבור API בפורטל.

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

צילום תמונת מצב של המפרט

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

כדי ליצור תמונת מצב של מפרט OpenAPI:

  1. בוחרים פרסום > פורטלים ובוחרים את הפורטל שלכם.
  2. לוחצים על ממשקי API בדף הבית של הפורטל.
    לחלופין, אפשר לבחור ממשקי API בתפריט הנפתח של הפורטל בסרגל הניווט העליון.
  3. מציבים את הסמן מעל ממשק ה-API שעבורו רוצים לצלם תמונת מצב כדי להציג את הפעולות.
  4. לוחצים על סמל תמונת המצב.

    הערה: תוצג הודעה אם תמונת המצב עדכנית לפי מפרט המקור שנבחר.

  5. בוחרים מפרט קיים מהתפריט הנפתח 'מקור תמונת מצב', או בוחרים באפשרות בחירת מפרטים אחרים כדי לבחור או להעלות מפרט חדש שישמש ליצירת תיעוד עבור ה-API. לחלופין, ניתן לבחור באפשרות ללא מפרט כדי להסיר את המפרט הנוכחי.

  6. לוחצים על עדכון תמונת מצב (או על הסרת תמונת מצב, אם בחרתם באפשרות 'ללא מפרט').

תיעוד ההפניה ל-API נוצר מהמפרט ומתווסף לדף הסימוכין של ה-API.

פרסום או ביטול פרסום של API בפורטל

כדי לפרסם או לבטל פרסום של API בפורטל:

  1. בוחרים פרסום > פורטלים ובוחרים את הפורטל שלכם.
  2. לוחצים על ממשקי API בדף הבית של הפורטל.
    לחלופין, אפשר לבחור ממשקי API בתפריט הנפתח של הפורטל בסרגל הניווט העליון.
  3. ממקמים את הסמן מעל ה-API שרוצים לפרסם או לבטל את הפרסום שלו.
  4. לוחצים על סמל ההגדרות.
  5. מסמנים את התיבה מופעל כדי לפרסם את ה-API בפורטל. כדי לבטל את הפרסום של ה-API, מבטלים את הבחירה באפשרות Enabled.
  6. לוחצים על שמירה.

ניהול הקהל עבור ממשק API בפורטל שלך

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

  • כל המשתמשים
  • משתמשים רשומים בלבד

כדי לנהל את הקהל עבור ממשק API בפורטל שלך:

  1. בוחרים פרסום > פורטלים ובוחרים את הפורטל שלכם.
  2. לוחצים על ממשקי API בדף הבית של הפורטל.
    לחלופין, אפשר לבחור ממשקי API בתפריט הנפתח של הפורטל בסרגל הניווט העליון.
  3. מציבים את הסמן מעל ממשק ה-API שעבורו רוצים לנהל את הקהל לצורך הצגת הפעולות.
  4. לוחצים על סמל ההגדרות.
  5. בקטע 'קהל', בוחרים באחת מהאפשרויות הבאות:
    • משתמשים אנונימיים כדי לאפשר לכל המשתמשים להציג את מוצר ה-API.
    • משתמשים רשומים כדי לאפשר רק למשתמשים רשומים לצפות במוצר ה-API.
  6. לוחצים על שמירה.

הסרת ממשק API מהפורטל

כדי להסיר ממשק API מהפורטל שלך:

  1. בוחרים פרסום > פורטלים ובוחרים את הפורטל שלכם.
  2. לוחצים על ממשקי API בדף הבית של הפורטל.
    לחלופין, אפשר לבחור ממשקי API בתפריט הנפתח של הפורטל בסרגל הניווט העליון.
  3. מציבים את הסמן מעל ממשק ה-API ברשימה כדי להציג את תפריט הפעולות.
  4. לוחצים על מחיקה.

פתרון בעיות בממשקי ה-API שפרסמת

כשמשתמשים ב-Try It, אם מוחזרת השגיאה TypeError: Failed to fetch, יש להביא בחשבון את הסיבות האפשריות והפתרונות הבאים:

  • אם מדובר בשגיאות של תוכן מעורב, ייתכן שהסיבה לשגיאה היא בעיה ידועה בממשק המשתמש (swagger-ui). אחת מהדרכים לעקוף את הבעיה היא לציין HTTPS לפני HTTP בהגדרה של schemes במפרט OpenAPI. לדוגמה:

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