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

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

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

סקירה כללית על פרסום API

תהליך פרסום ממשקי API בפורטל כולל שני שלבים:

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

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

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

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

  

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

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

  

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

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

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

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

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

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

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

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

הדף 'ממשקי API'

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

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

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

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

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

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

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

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

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

1. בוחרים באפשרות פרסום > פורטלים ובוחרים את הפורטל.
2. לוחצים על APIs בדף הבית של הפורטל.
   לחלופין, אפשר ללחוץ על APIs (ממשקי API) בתפריט הנפתח של הפורטל בסרגל הניווט העליון.
3. לוחצים על + API.
   מוצגת תיבת הדו-שיח Add API Product to Portal (הוספת מוצר API לפורטל).

4. בכרטיסייה API Product (מוצר API) בתיבת הדו-שיח, בוחרים את מוצר ה-API שרוצים להוסיף לפורטל.
   

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

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

   אפשר גם לבחור באחת מהאפשרויות הבאות:

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

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

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

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

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

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

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

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

כדי ליצור snapshot של מפרט OpenAPI:

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

4. לוחצים על .

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

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

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

מאמרי העזרה של ה-API נוצרים מהמפרט ונוספים לדף API Reference.

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

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

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

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

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

• כל המשתמשים
• רק משתמשים רשומים

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

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

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

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

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

פתרון בעיות ב-APIs שפורסמו

אם מופיעה השגיאה TypeError: Failed to fetch כשמשתמשים באפשרות 'ניסיון', כדאי לבדוק את הסיבות האפשריות הבאות ואת הפתרונות שלהן:

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

   schemes:
     - https
     - http
  

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