פרסום ממשקי ה-API

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

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

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

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

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

אילו נתונים מתפרסמים בפורטל?

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

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

• SmartDocs (OpenAPI)
• תרשים QL

יתווסף קישור לדף הפניית ה-API לדף של ממשקי ה-API

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

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

SmartDocs (OpenAPI)

כשמפרסמים API באמצעות מסמך OpenAPI, מסמכי העזר של SmartDocs API מתווספים לפורטל שלכם.

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

לוחצים על הסמל כדי להרחיב את החלונית 'אני רוצה לנסות את ה-API הזה'. בחלונית המורחבת אפשר לראות את דוגמאות הקוד וקריאת ה-Curl בפורמטים שונים, כמו HTTP, Python, Node.js ועוד, כפי שמתואר בהמשך.

סייר GraphQL

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

מפתחים יכולים להשתמש ב- GraphQL Explorer כדי לחקור את התיעוד האינטראקטיבי המבוסס על סכימה, לבנות ולהריץ שאילתות, להציג תוצאות שאילתות ולהוריד את הסכימה. כדי לאבטח את הגישה ל-API, מפתחים יכולים להעביר כותרות הרשאות בחלונית Request Headers.

מידע נוסף על GraphQL זמין באתר graphql.org.

מהי תמונת מצב?

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

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

מידע על כתובות URL לקריאה חוזרת (callback)

אם האפליקציות שלך דורשות כתובת URL לקריאה חוזרת (callback), למשל כשמשתמשים בקוד הרשאה מסוג OAuth 2.0 (שנקרא לעיתים קרובות 'OAuth תלת-רגלי'), אפשר לדרוש ממפתחים לציין כתובת URL לקריאה חוזרת (callback) כשהם רושמים את האפליקציות שלהם. כתובת ה-URL לקריאה חוזרת (callback) מציינת בדרך כלל את כתובת ה-URL של אפליקציה שמיועדת לקבל קוד הרשאה מטעם אפליקציית הלקוח. מידע נוסף זמין במאמר הטמעת סוג ההרשאה של קוד ההרשאה.

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

במהלך רישום האפליקציה, המפתחים חייבים להזין כתובת URL לקריאה חוזרת (callback) לכל ממשקי ה-API שדורשים אותה, כפי שמתואר ברישום אפליקציות.

צריך להגדיר את שרת ה-API של ה-API לתמיכה באפשרות 'אני רוצה לנסות את ה-API הזה'

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

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

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

• עדכון ההגדרה של שרת proxy ל-API אם משתמשים באימות בסיסי או ב-OAuth2

הטבלה הבאה מסכמת את דרישות התצורה של שרת ה-proxy ל-API כדי לתמוך בחלונית 'אני רוצה לנסות את ה-API הזה' במסמכי התיעוד של SmartDocs API, על סמך הגישה לאימות.

גישה לאימות	דרישות להגדרת המדיניות
ללא או מפתח API	הוספת תמיכה ב-CORS לשרת ה-API של שרת ה-proxy. לנוחיותכם, תוכלו להשתמש בפתרון CORS לדוגמה שמסופק ב-GitHub, או לפעול לפי השלבים המתוארים בהוספת תמיכה ב-CORS לשרת proxy של API.
אימות בסיסי	מבצעים את הפעולות הבאות: הוספת תמיכה ב-CORS לשרת ה-API של שרת ה-proxy. לנוחיותכם, תוכלו להשתמש בפתרון CORS לדוגמה שמסופק ב-GitHub, או לפעול לפי השלבים המתוארים בהוספת תמיכה ב-CORS לשרת proxy של API. במדיניות בנושא הוספת הודעה מסוג CORS, יש לוודא שהכותרת Access-Control-Allow-Headers כוללת את המאפיין authorization. לדוגמה: <Header name="Access-Control-Allow-Headers"> origin, x-requested-with, accept, content-type, authorization </Header>
OAuth2	הוספת תמיכה ב-CORS לשרת ה-API של שרת ה-proxy. לנוחיותכם, תוכלו להשתמש בפתרון CORS לדוגמה שמסופק ב-GitHub, או לפעול לפי השלבים המתוארים בהוספת תמיכה ב-CORS לשרת proxy של API. במדיניות בנושא הוספת הודעה מסוג CORS, יש לוודא שהכותרת Access-Control-Allow-Headers כוללת את המאפיין authorization. לדוגמה: <Header name="Access-Control-Allow-Headers"> origin, x-requested-with, accept, content-type, authorization </Header> צריך לתקן התנהגות שלא תואמת ל-RFC במדיניות OAuth2. לנוחיותכם, תוכלו להשתמש בפתרון OAuth2 לדוגמה שמסופק ב-GitHub, או לבצע את הפעולות הבאות: מוודאים שהרכיב <GrantType> במדיניות OAuth2 מוגדר לערך request.formparam.grant_type (פרמטר של טופס). מידע נוסף זמין במאמר <GrantType>. מוודאים שהשדה token_type במדיניות OAuth2 מוגדר לערך Bearer, ולא ערך ברירת המחדל BearerToken.

סיור בקטלוג ממשקי ה-API

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

בכרטיסייה 'ממשקי API' בקטלוג של ממשקי ה-API, מוצגת רשימה של ממשקי ה-API שנוספו לפורטל שלכם.

כפי שמודגש באיור הקודם, הכרטיסייה 'ממשקי API' מאפשרת לך:

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

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

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

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

3. לוחצים על הסימן +.

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

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

5. לוחצים על הבא. יופיע דף הפרטים של ה-API.

6. הגדרת התוכן של מסמכי התיעוד של ה-API ואת הרשאות הגישה שלו בפורטל:

   שדה	תיאור
   פורסם	בוחרים באפשרות Publish (פורסם) כדי לפרסם את ה-API בפורטל שלכם. אם לא רוצים לפרסם את ה-API, צריך לבטל את הסימון של התיבה. אתם יכולים לשנות את ההגדרה הזו מאוחר יותר, כפי שמתואר במאמר פרסום או ביטול פרסום של API בפורטל.
   כותרת לתצוגה	צריך לעדכן את שם ה-API שמוצג בקטלוג. כברירת מחדל, נעשה שימוש בשם המוצר של ה-API. תוכלו לשנות את שם התצוגה מאוחר יותר, כפי שמתואר במאמר עריכת השם והתיאור.
   תיאור לתצוגה	צריך לעדכן את תיאור ה-API שמוצג בקטלוג. כברירת מחדל, נעשה שימוש בתיאור המוצר ב-API. תוכלו לשנות את תיאור התצוגה מאוחר יותר, כפי שמתואר במאמר עריכת השם והתיאור של התצוגה.
   דרישה ממפתחים לציין כתובת URL לקריאה חוזרת (callback)	מפעילים את ההגדרה הזו אם רוצים לדרוש ממפתחי אפליקציות לציין כתובת URL לקריאה חוזרת (callback). ניתן להוסיף או לעדכן את כתובת ה-URL לקריאה חוזרת (callback) בשלב מאוחר יותר, כפי שמתואר במאמר ניהול כתובת ה-URL לקריאה חוזרת (callback) עבור API.
   תיעוד ממשק API	כדי להשתמש במסמך OpenAPI: בוחרים באפשרות מסמך OpenAPI. לוחצים על בחירת מסמך. מבצעים אחת מהפעולות הבאות: לוחצים על הכרטיסייה My Specs (המפרטים שלי) ובוחרים מפרט מחנות המפרטים. לוחצים על הכרטיסייה העלאת קובץ ומעלים קובץ. לוחצים על הכרטיסייה ייבוא מכתובת URL ומייבאים מפרט מכתובת URL. לוחצים על בחירה. כדי להשתמש בסכימת GraphQL: בוחרים באפשרות סכימת GraphQL. לוחצים על בחירת מסמך. עוברים אל סכימת GraphQL ובוחרים בה. לוחצים על בחירה. לחלופין, אתם יכולים לבחור באפשרות אין תיעוד ולהוסיף מסמך במועד מאוחר יותר אחרי הוספת ה-API, כפי שמתואר בניהול תמונת המצב של המסמך.
   הרשאות גישה ל-API	אם לא נרשמתם לגרסת הבטא של תכונת ניהול הקהלים, עליכם לבחור באחת מהאפשרויות הבאות: משתמשים אנונימיים כדי לאפשר לכל המשתמשים לצפות ב-API. משתמשים רשומים כדי לאפשר רק למשתמשים רשומים להציג את ה-API. אם נרשמתם לגרסת הבטא של התכונה 'ניהול קהלים', עליכם לבחור באחת מהאפשרויות הבאות: ציבורי (גלוי לכולם) כדי לאפשר לכל המשתמשים להציג את ה-API. משתמשים מאומתים כדי לאפשר רק למשתמשים רשומים להציג את ה-API. קהלים שנבחרו כדי לבחור את הקהלים הספציפיים שרוצים לאפשר להם להציג את ה-API. אפשר לנהל את החשיפה של הקהל מאוחר יותר, כפי שמתואר במאמר ניהול הרשאות הגישה של ממשק API בפורטל.
   תמונה לתצוגה	כדי להציג תמונה בכרטיס ה-API בדף ממשקי ה-API, לוחצים על בחירת תמונה. בתיבת הדו-שיח בחירת תמונה, בוחרים תמונה קיימת, מעלים תמונה חדשה או מציינים כתובת URL של תמונה חיצונית ולוחצים על בחירה. צופים בתצוגה המקדימה של התמונה הממוזערת של ה-API ולוחצים על בחירה. תוכלו להוסיף תמונה מאוחר יותר, כפי שמתואר במאמר ניהול התמונה של כרטיס API. כשמציינים תמונה עם כתובת URL חיצונית, התמונה לא תועלה לנכסים שלכם. בנוסף, טעינת התמונה בפורטל המשולב תהיה כפופה לזמינות שלה, וייתכן שהיא תיחסם או תוגבל בהתאם למדיניות בנושא אבטחת תוכן.
   קטגוריות	יש להוסיף את הקטגוריות שאליהן ממשק ה-API יתויג כדי לאפשר למפתחי אפליקציות לגלות ממשקי API קשורים בדף ממשקי ה-API. כדי לזהות קטגוריה: בוחרים קטגוריה מהרשימה הנפתחת. מוסיפים קטגוריה חדשה על ידי הקלדת השם שלה והקשה על Enter. הקטגוריה החדשה תתווסף לדף 'קטגוריות' ותהיה זמינה כשמוסיפים ממשקי API אחרים או עורכים אותם.

7. לוחצים על שמירה.

ניהול תמונת המצב של המסמך

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

כדי לנהל את תמונת המצב של המסמך:

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

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

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

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

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

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

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

• ציבורי (גלוי לכולם)
• משתמשים מאומתים
• הקהלים שנבחרו (אם נרשמתם לגרסת הבטא של תכונת ניהול הקהלים)

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

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

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

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

7. לוחצים על שליחה.

ניהול של כתובת ה-URL לקריאה חוזרת (callback) ב-API

ניהול של כתובת ה-URL לקריאה חוזרת (callback) ב-API. מידע על כתובות URL לקריאה חוזרת (callback)

כדי לנהל את כתובת ה-URL לקריאה חוזרת (callback) ב-API:

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

ניהול התמונה של כרטיס API

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

כדי לנהל את התמונה של כרטיס API:

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

5. בקטע 'פרטי ה-API':

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

   כשאתם מציינים תמונה, צריך לציין תמונה עם כתובת URL חיצונית שמשמשת לפריט בקטלוג, או נתיב לקובץ קובצי תמונה שמאוחסנים בפורטל, לדוגמה, /files/book-tree.jpg. כשמציינים כתובת URL של תמונה חיצונית, התמונה לא תועלה לנכסים שלכם. בנוסף, הטעינה של התמונה בפורטל המשולב תהיה כפופה לזמינות שלה, וייתכן שהיא תיחסם או תוגבל על ידי מדיניות אבטחת התוכן.

6. לוחצים על שמירה.

תיוג API באמצעות קטגוריות

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

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

כדי לתייג API לקטגוריות בעת עריכת ה-API:

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

עריכת השם והתיאור של התצוגה

כדי לערוך את השם והתיאור של התצוגה:

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

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

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

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

ניהול הקטגוריות שמשמשות לגילוי ממשקי API קשורים

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

סקירת הדף 'קטגוריות'

כדי להציג את הדף 'קטגוריות':

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

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

3. לוחצים על הכרטיסייה קטגוריות.

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

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

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

הוספת קטגוריה

מוסיפים קטגוריה באחת מהדרכים הבאות:

• מזינים שם של קטגוריה כשמוסיפים API לפורטל.
• הוספת קטגוריה באופן ידני כפי שמתואר בהמשך

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

כדי להוסיף קטגוריה באופן ידני:

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

עריכת קטגוריה

כדי לערוך קטגוריה:

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

מחיקת קטגוריה

כשמוחקים קטגוריה, כל תגי ה-API בקטגוריה הזו נמחקים גם הם.

כדי למחוק קטגוריה:

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

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

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

שגיאה: לא הצלחנו לאחזר את השגיאה שהוחזרה במהלך השימוש ב-API הזה

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

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

  schemes:
     - https
     - http
  

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

שגיאה: הכותרת Access-Control-Allow-Origin מכילה כמה ערכים: '*', '*', אבל מותר להשתמש רק באחד מהם

כשמשתמשים ב-API הזה, יכול להיות שתקבלו את הודעת השגיאה הבאה אם הכותרת Access-Control-Allow-Origin כבר קיימת:

The 'Access-Control-Allow-Origin' header contains multiple values '*, *', but only one is allowed.

כדי לתקן את השגיאה הזו, צריך לשנות את המדיניות assignMessage כך שתשתמש ב-<Set> כדי להגדיר את כותרות CORS במקום את <Add>, כפי שמוצג בקטע שבהמשך. למידע נוסף, כדאי לעיין במאמר הקהילה הרלוונטי.

<AssignMessage async="false" continueOnError="false" enabled="true" name="add-cors">
    <DisplayName>Add CORS</DisplayName>
    <FaultRules/>
    <Properties/>
    <Set>
        <Headers>
            <Header name="Access-Control-Allow-Origin">{request.header.origin}</Header>
            <Header name="Access-Control-Allow-Headers">origin, x-requested-with, accept, content-type, authorization</Header>
            <Header name="Access-Control-Max-Age">3628800</Header>
            <Header name="Access-Control-Allow-Methods">GET, PUT, POST, DELETE</Header>
        </Headers>
    </Set>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

שגיאה: שדה כותרת הבקשה אסור

כשמשתמשים ב-API הזה, אם מופיעה הודעת השגיאה Request header field not allowed, בדומה לדוגמה שלמטה, יכול להיות שתצטרכו לעדכן את הכותרות שנתמכות במדיניות CORS. למשל:

Access to XMLHttpRequest ... has been blocked by CORS policy: Request header field
content-type is not allowed by Access-Control-Allow-Headers in preflight response

בדוגמה הזו, צריך להוסיף את הכותרת content-type לקטע Access-Control-Allow-Headers במדיניות CORS assignMessage, כפי שמתואר במאמר צירוף של מדיניות CORS לשרת proxy חדש ל-API.

שגיאה: הגישה נדחתה בעת קריאה ל-API מסוג proxy באמצעות OAuth2

מדיניות OAuthV2 של Apigee מחזירה תגובת אסימון שמכילה מאפיינים מסוימים שאינם תואמים ל-RFC. לדוגמה, המדיניות תחזיר אסימון עם הערך BearerToken במקום הערך הצפוי Bearer שתואם ל-RFC. תגובת token_type הלא חוקית הזו עלולה לגרום לשגיאה Access denied במהלך השימוש ב-API הזה.

כדי לתקן את הבעיה, אפשר ליצור מדיניות JavaScript או assignMessage כדי לשנות את פלט המדיניות לפורמט תואם. מידע נוסף זמין במאמר התנהגות שלא תואמת ל-RFC.