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

מוצג המסמך של Apigee Edge.
עוברים אל מסמכי תיעוד של Apigee X. מידע

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

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

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

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

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

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

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

  

• הקישור לדף ה-API Reference נוסף לדף ממשקי ה-API
  דף ממשקי ה-API (שכלול בפורטל לדוגמה) מספק רשימה של כל ממשקי ה-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 ל-API של Twitter מקוד JavaScript שרץ בדפדפן שלכם, הקריאה תיכשל. הסיבה לכך היא שהדומיין שמציג את הדף לדפדפן שלכם אינו זהה לדומיין שמפעיל את ה-API של Twitter. CORS מספק פתרון לבעיה באמצעות מתן אפשרות לשרתים 'להביע הסכמה' אם הוא רוצה לספק שיתוף משאבים בין מקורות.

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

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

לדף ממשקי ה-API

כדי להיכנס לדף ממשקי ה-API:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

4. לוחצים על .

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

   schemes:
     - https
     - http
  

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