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

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

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

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

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

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

מה מתפרסם בפורטל?

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

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

• SmartDocs (OpenAPI)
• GraphQL Explorer

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

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

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

SmartDocs (OpenAPI)

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

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

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

סייר GraphQL

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

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

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

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

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

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

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

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

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

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

הגדרת שרת ה-API של ה-API כך שיתמוך באפשרות "Try this API"

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

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

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

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

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

גישת אימות	דרישות להגדרת המדיניות
ללא או מפתח API	הוספה של תמיכת CORS ל-API מסוג proxy. לנוחותך, אפשר להשתמש בפתרון CORS לדוגמה שמסופק ב-GitHub או לבצע את השלבים שמתוארים במאמר הוספת תמיכה ב-CORS לשרת proxy ל-API.
אימות בסיסי	מבצעים את הפעולות הבאות: הוספה של תמיכת CORS ל-API מסוג proxy. לנוחותך, אפשר להשתמש בפתרון CORS לדוגמה שמסופק ב-GitHub או לבצע את השלבים שמתוארים במאמר הוספת תמיכה ב-CORS לשרת proxy ל-API. במדיניות Add CORS assignMessage, יש לוודא שהכותרת 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. במדיניות Add CORS assignMessage, יש לוודא שהכותרת 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 לפורטל:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

כדי לתייג API לקטגוריות כשעורכים את ה-API:

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

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

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

1. נכנסים לקטלוג ה-API.
2. לוחצים על הכרטיסייה APIs (ממשקי API), אם היא עדיין לא נבחרה.
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. לוחצים על Create.

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

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

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

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

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

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

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

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

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

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

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

• אם מדובר בשגיאות של תוכן מעורב, ייתכן שהסיבה לשגיאה היא בעיה ידועה בממשק המשתמש (swagger-ui). אחת מהדרכים לעקוף את הבעיה היא לציין 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 במדיניות assignMessage ב-CORS, כפי שמתואר במאמר איך מחברים מדיניות הוספה של CORS לשרת API חדש.

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

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

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