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

המסמך הזה עוסק ב-Apigee Edge.
למעבר אל מסמכי התיעוד של Apigee X.
info

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

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

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

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

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

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

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

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

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

    דף ממשקי ה-API בפורטל פעיל שבו מוצגות שתי קטגוריות ושימוש בתמונות

‫SmartDocs ‏(OpenAPI)

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

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

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

לוחצים על Fullscreen כדי להרחיב את החלונית Try this API. בחלונית המורחבת אפשר לראות את הקריאה ל-curl ואת דוגמאות הקוד בפורמטים שונים, כמו HTTP,‏ Python,‏ Node.js ועוד, כמו שמוצג באיור הבא.

חלונית מורחבת של "התנסות עם ה-API"

GraphQL Explorer

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

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

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

‫GraphQL Explorer בפורטל

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

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

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

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

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

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

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

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

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

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

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

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

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

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

ניהול ממשקי API

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

חיפוש ממשקי API

כדי לראות את ממשקי ה-API שבפורטל, משתמשים בממשק המשתמש או בפקודה curl.

ממשק משתמש

כדי להציג את קטלוג ה-API:

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

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

הכרטיסייה &quot;ממשקי API&quot; שבה מוצג מידע על ממשקי ה-API, כולל שם, תיאור, הרשאות גישה, קטגוריות, מפרט משויך וזמן השינוי

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

curl

כדי להציג רשימה של ממשקי API:

curl -X GET "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs" \
    -H "Authorization: Bearer ACCESS_TOKEN"

מחליפים את מה שכתוב בשדות הבאים:

  • ‫ORG_NAME בשם הארגון. לדוגמה, my-org.
  • ‫SITE_ID בשם הפורטל, בפורמט ORG_NAME-PORTAL_NAME, כאשר ORG_NAME הוא שם הארגון ו-PORTAL_NAME הוא שם הפורטל באותיות קטנות בלבד, ללא רווחים ומקפים. לדוגמה, my-org-myportal.
  • ‫ACCESS_TOKEN עם אסימון האימות שמשמש לגישה ל-Apigee Edge API. מידע נוסף על אימות ואסימונים זמין במאמר אימות הגישה ל-Edge API.

בקטע הערות לגבי עימוד מוסבר איך להשתמש בעימוד במטען הייעודי (payload) של התגובה.

המטען הייעודי (payload) של התגובה:

{
  "status": "success",
  "message": "one page of apidocs returned",
  "data": [
    {
      "id": 622759,
      "siteId": "my-org-myportal",
      "title": "Test",
      "description": "",
      "published": false,
      "visibility": false,
      "apiId": "apiproducttest18",
      "apiProductName": "apiproduct_test18",
      "edgeAPIProductName": "apiproduct_test18",
      "specId": null,
      "specContent": null,
      "specTitle": null,
      "snapshotExists": false,
      "snapshotModified": null,
      "modified": 1724144471000,
      "anonAllowed": false,
      "imageUrl": null,
      "snapshotState": null,
      "requireCallbackUrl": false,
      "categoryIds": [],
      "specFormat": null,
      "specModified": null,
      "snapshotOutdated": false,
      "snapshotSourceMissing": false,
      "graphqlSchema": null,
      "graphqlEndpointUrl": null,
      "graphqlSchemaDisplayName": null,
      "grpcFileName": null,
      "grpcZipContent": null
    }
  ],
  "code": null,
  "request_id": "1452867334",
  "error_code": null,
  "next_page_token": ""
}

כאשר:

  • ‫modified: הזמן שבו הפריט בקטלוג השתנה לאחרונה, באלפיות השנייה מאז ראשית זמן יוניקס (Unix epoch). לדוגמה, 1698165480000.
  • ‫id: המזהה של הפריט בקטלוג. לדוגמה, 399668.

הערות לגבי חלוקה לדפים:

  • גודל הדף: משתמשים ב-pageSize כדי לציין את מספר הפריטים שיוחזרו בדף אחד. ברירת המחדל היא 25 והערך המקסימלי הוא 100. אם יש דפים נוספים, השדה nextPageToken יאוכלס באסימון:

    curl -X GET "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs?pageSize=PAGE_SIZE" \
       -H "Authorization: Bearer ACCESS_TOKEN"
    

    מחליפים את:

    • ‫PAGE_SIZE עם מספר הפריטים ברשימה שיוחזרו בדף אחד. לדוגמה, 10.

    המטען הייעודי (payload) של התגובה:

    {
      "status": "success",
      "message": "one page of apidocs returned",
      "data": [
        {
          "id": 638007,
          "siteId": "tsnow-mint-liztest",
          "title": "Testing",
          "description": "",
          "published": false,
          "visibility": false,
          "apiId": "testcatalog",
          "apiProductName": "testcatalog",
          "edgeAPIProductName": "testcatalog",
          "specId": "Petstore",
          "specContent": null,
          "specTitle": null,
          "snapshotExists": true,
          "snapshotModified": 1726508367000,
          "modified": 1728582504000,
          "anonAllowed": false,
          "imageUrl": null,
          "snapshotState": "OK_SUBMITTED",
          "requireCallbackUrl": false,
          "categoryIds": [],
          "specFormat": "YAML",
          "specModified": null,
          "snapshotOutdated": false,
          "snapshotSourceMissing": false,
          "graphqlSchema": null,
          "graphqlEndpointUrl": null,
          "graphqlSchemaDisplayName": null,
          "grpcFileName": null,
          "grpcZipContent": null
        }
      ],
      "code": null,
      "request_id": "1068810934",
      "error_code": null,
      "next_page_token": ""
    }
    

  • אסימון דף: משתמשים ב-pageToken כדי לאחזר את הדפים הבאים כשיש יותר מדף אחד:

    curl -X GET "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs?pageSize=PAGE_SIZE&pageToken=PAGE_TOKEN" \
          -H "Authorization: Bearer ACCESS_TOKEN"
    

    מחליפים את:

    • ‫PAGE_SIZE עם מספר הפריטים ברשימה שיוחזרו בדף אחד. לדוגמה, 10.
    • PAGE_TOKEN עם הערך nextPageToken. לדוגמה, 7zcqrin9l6xhi4nbrb9.

הוספת API

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

ממשק משתמש

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

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

    תיבת הדו-שיח Add an API product to the catalog מופיעה.

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

  5. לוחצים על הבא. הדף API details נפתח.

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

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

    כדי להשתמש במסמך OpenAPI:

    1. בוחרים באפשרות מסמך OpenAPI.
    2. לוחצים על בחירת מסמך.
    3. מבצעים את אחד מהשלבים הבאים:
      • לוחצים על הכרטיסייה המפרטים שלי ובוחרים מפרט מחנות המפרטים.
      • לוחצים על הכרטיסייה העלאת קובץ ומעלים קובץ.
      • לוחצים על הכרטיסייה ייבוא מכתובת URL ומייבאים מפרט מכתובת URL.
    4. לוחצים על בחירה.

    כדי להשתמש בסכימת GraphQL:

    1. בוחרים באפשרות GraphQL Schema.
    2. לוחצים על בחירת מסמך.
    3. עוברים לסכימת GraphQL ובוחרים אותה.
    4. לוחצים על בחירה.

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

    הרשאות הגישה ל-API

    אם לא נרשמתם לגרסת הבטא של התכונה "ניהול קהלים", בחרו באחת מהאפשרויות הבאות:

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

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

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

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

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

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

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

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

curl

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

curl -X POST "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs" \
    -H "Authorization: Bearer ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
       "title": "TITLE",
       "description": "DESCRIPTION",
       "anonAllowed": ANON_TRUE_OR_FALSE,
       "imageUrl": "IMAGE_URL",
       "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
       "categoryIds": [
         "CATEGORY_ID1",
         "CATEGORY_ID2"
       ],
       "published": PUBLISHED_TRUE_OR_FALSE,
        "apiProductName": "API_PRODUCT"
    }'

מחליפים את מה שכתוב בשדות הבאים:

  • ‫ORG_NAME בשם הארגון. לדוגמה, my-org.
  • ‫SITE_ID בשם הפורטל, בפורמט ORG_NAME-PORTAL_NAME, כאשר ORG_NAME הוא שם הארגון ו-PORTAL_NAME הוא שם הפורטל באותיות קטנות בלבד, ללא רווחים ומקפים. לדוגמה, my-org-myportal.
  • ‫ACCESS_TOKEN באסימון האימות שמשמש לגישה ל-Apigee Edge API. מידע נוסף על אימות ואסימונים זמין במאמר אימות הגישה ל-Edge API.
  • TITLE עם הכותרת לתצוגה. לדוגמה, Hello World 2.
  • DESCRIPTION עם תיאור התצוגה. לדוגמה, Simple hello world example.
  • ‫ANON_TRUE_OR_FALSE עם true או false (ברירת המחדל), כאשר true פירושו שה-API הזה גלוי לכולם וניתן לצפות בו באופן אנונימי; אחרת, רק משתמשים רשומים יכולים לצפות בו.
  • IMAGE_URL בכתובת ה-URL של תמונה חיצונית שמשמשת לפריט בקטלוג, או בנתיב של קובצי תמונות שמאוחסנים בפורטל, לדוגמה, /files/book-tree.jpg. כשמציינים כתובת URL של תמונה חיצונית, התמונה לא תועלה לנכסים שלכם. בנוסף, טעינת התמונה בפורטל המשולב תהיה כפופה לזמינות שלה, שעלולה להיות חסומה או מוגבלת על ידי מדיניות אבטחת תוכן.
  • CALLBACK_TRUE_OR_FALSE עם true או false (ברירת המחדל), כאשר true דורש ממשתמש בפורטל להזין כתובת URL בזמן ניהול האפליקציה.
  • ‫CATEGORY_ID במזהה הקטגוריה. לדוגמה: bf6505eb-2a0f-47af-a00a-ded40ac72960. אם יש כמה מזהי קטגוריות, צריך להפריד ביניהם באמצעות פסיק. משיגים את מזהה הקטגוריה באמצעות הפקודה list API categories.
  • ‫PUBLISHED_TRUE_OR_FALSE עם true או false (ברירת המחדל), כאשר true מציין שה-API זמין לכולם. אחרי הפרסום, אפשר לתת גישה לכל המשתמשים, למשתמשים מאומתים או למשתמשים ספציפיים.
  • ‫API_PRODUCT בשם של מוצר ה-API. לדוגמה: Hello World 2.

המטען הייעודי (payload) של התגובה:

{
  "status": "success",
  "message": "API created",
  "data": {
    "id": 662423,
    "siteId": "my-org-myportal",
    "title": "My Test Catalog 4",
    "description": "",
    "published": false,
    "visibility": false,
    "apiId": "uxb9wjua",
    "apiProductName": "uXB9wJUa",
    "edgeAPIProductName": "uXB9wJUa",
    "specId": null,
    "specContent": null,
    "specTitle": null,
    "snapshotExists": false,
    "snapshotModified": null,
    "modified": 1729635493000,
    "anonAllowed": false,
    "imageUrl": null,
    "snapshotState": null,
    "requireCallbackUrl": false,
    "categoryIds": [],
    "specFormat": null,
    "specModified": null,
    "snapshotOutdated": null,
    "snapshotSourceMissing": false,
    "graphqlSchema": null,
    "graphqlEndpointUrl": null,
    "graphqlSchemaDisplayName": null,
    "grpcFileName": null,
    "grpcZipContent": null
  },
  "code": null,
  "request_id": "893346193",
  "error_code": null
}

כאשר:

  • ‫modified: הזמן שבו הפריט בקטלוג השתנה לאחרונה, באלפיות השנייה מאז ראשית זמן יוניקס (Unix epoch). לדוגמה, 1698165480000.
  • ‫id: המזהה של הפריט בקטלוג. לדוגמה, 399668.

עריכת API

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

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

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

ממשק משתמש

כדי לערוך API:

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

curl

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

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

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

    curl -X GET "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
    -H "Authorization: Bearer ACCESS_TOKEN"
    

    מחליפים את מה שכתוב בשדות הבאים:

    • ‫ORG_NAME בשם הארגון. לדוגמה, my-org.
    • ‫SITE_ID בשם הפורטל, בפורמט ORG_NAME-PORTAL_NAME, כאשר ORG_NAME הוא שם הארגון ו-PORTAL_NAME הוא שם הפורטל באותיות קטנות בלבד, ללא רווחים ומקפים. לדוגמה, my-org-myportal.
    • ‫API_DOC עם הערך של id שנוצר במסמך. לדוגמה, 399668. כדי למצוא את הערך הזה, משתמשים בפקודה list API docs.
    • ‫ACCESS_TOKEN באסימון האימות שמשמש לגישה ל-Apigee Edge API. מידע נוסף על אימות ואסימונים זמין במאמר אימות הגישה ל-Edge API.

    המטען הייעודי (payload) של התגובה:

    {
      "status": "success",
      "message": "apidoc returned",
      "data": {
        "id": 662423,
        "siteId": "my-org-myportal",
        "title": "My Test Catalog 4",
        "description": "",
        "published": false,
        "visibility": false,
        "apiId": "uxb9wjua",
        "apiProductName": "uXB9wJUa",
        "edgeAPIProductName": "uXB9wJUa",
        "specId": null,
        "specContent": null,
        "specTitle": null,
        "snapshotExists": false,
        "snapshotModified": null,
        "modified": 1729635493000,
        "anonAllowed": false,
        "imageUrl": null,
        "snapshotState": null,
        "requireCallbackUrl": false,
        "categoryIds": [],
        "specFormat": null,
        "specModified": null,
        "snapshotOutdated": false,
        "snapshotSourceMissing": false,
        "graphqlSchema": null,
        "graphqlEndpointUrl": null,
        "graphqlSchemaDisplayName": null,
        "grpcFileName": null,
        "grpcZipContent": null
      },
      "code": null,
      "request_id": "601210268",
      "error_code": null
    }
    

  1. בקריאה ל-update, כוללים את הערכים שניתנים לשינוי שרוצים לשמור, ומשנים את הערכים שרוצים לשנות. אם משמיטים שורה, המערכת משתמשת בהגדרת ברירת המחדל. בדוגמה הזו, משנים את ההגדרה שפורסמה מ-false ל-true:

    curl -X PUT "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
        "title": "TITLE",
        "anonAllowed": true,
        "published": true
     }'
    

    מחליפים את מה שכתוב בשדות הבאים:

    • TITLE עם הכותרת לתצוגה. לדוגמה, Hello World 2.

    המטען הייעודי (payload) של התגובה:

    {
      "status": "success",
      "message": "ApiDoc updated",
      "data": {
        "id": 662423,
        "siteId": "my-org-myportal",
        "title": "My Test Catalog 4",
        "description": "",
        "published": true,
        "visibility": true,
        "apiId": "uxb9wjua",
        "apiProductName": "uXB9wJUa",
        "edgeAPIProductName": "uXB9wJUa",
        "specId": null,
        "specContent": null,
        "specTitle": null,
        "snapshotExists": false,
        "snapshotModified": null,
        "modified": 1729989250000,
        "anonAllowed": true,
        "imageUrl": null,
        "snapshotState": null,
        "requireCallbackUrl": false,
        "categoryIds": [],
        "specFormat": null,
        "specModified": null,
        "snapshotOutdated": null,
        "snapshotSourceMissing": false,
        "graphqlSchema": null,
        "graphqlEndpointUrl": null,
        "graphqlSchemaDisplayName": null,
        "grpcFileName": null,
        "grpcZipContent": null
      },
      "code": null,
      "request_id": "738172002",
      "error_code": null
    }
    

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

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

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

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

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

פרסום הוא התהליך שבו ממשקי ה-API שלכם הופכים לזמינים לשימוש של מפתחי אפליקציות.

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

ממשק משתמש

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

  1. גישה לקטלוג ה-API.
  2. לוחצים על הכרטיסייה ממשקי API, אם היא לא נבחרה כבר.
  3. לוחצים על השורה של ה-API שרוצים לערוך.
  4. לוחצים על סמל העריכה עריכה.
  5. בקטע API details, בוחרים או מבטלים את הבחירה באפשרות Published (listed in the catalog) כדי לפרסם או לבטל את הפרסום של ה-API בפורטל, בהתאמה.
  6. לוחצים על שמירה.

curl

צריך לכלול את אחד מהפרטים הבאים בקריאת העדכון:

"published": true,    # API is published to your portal
"published": false,   # API is not published in your portal

כדי לערוך את ה-API:

  1. החזרת הערכים הנוכחיים:

    curl -X GET "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs" \
    -H "Authorization: Bearer ACCESS_TOKEN"
  2. משתמשים בקריאה update כדי לערוך את ה-API. כוללים את הערכים שניתנים לשינוי שרוצים לשמור, ומשנים את הערכים שרוצים לשנות. אם משמיטים הגדרה שניתנת לשינוי, היא מוחלפת בערך ברירת המחדל.

    curl -X PUT "https://api.enterprise.apigee.com/v1/organizations/  ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
        "title": "TITLE",
        "description": "DESCRIPTION",
        "anonAllowed": ANON_TRUE_OR_FALSE,
        "imageUrl": IMAGE_URL,
        "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
        "categoryIds": [
          "CATEGORY_ID1",
         "CATEGORY_ID2"
        ],
        "published": PUBLISHED_TRUE_OR_FALSE
    }

במאמר ניהול גרסת המסמך מופיעה דוגמה מפורטת של השלבים, המשתנים והמטען הייעודי (payload) שמוחזר.

ניהול הרשאות הגישה ל-API בפורטל

כדי לנהל את החשיפה של API בפורטל, אתם יכולים לתת גישה:

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

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

ממשק משתמש

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

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

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

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

curl

אם נרשמתם לגרסת הבטא של התכונה "ניהול קהלים", אתם יכולים להשתמש בממשק המשתמש כדי לנהל קהלים.

אם לא נרשמתם לתכונה "ניהול קהלים", אתם יכולים לנהל את הרשאות הגישה באמצעות anonAllowed.

כוללים את אחת מהאפשרויות הבאות בקריאה ל-update:

  # When not enrolled in the beta release of the audience management feature:

  "anonAllowed": true,      # Anonymous users can see the API
  "anonAllowed": false,     # Only registered users can see the API

כדי לערוך את ה-API:

  1. החזרת הערכים הנוכחיים:

    curl -X GET "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
         -H "Authorization: Bearer ACCESS_TOKEN"
    
  2. משתמשים בקריאה update כדי לערוך את ה-API. כוללים את הערכים הניתנים לשינוי שרוצים לשמור, ומשנים את הערכים שרוצים לשנות. אם משמיטים הגדרה שניתנת לשינוי, המערכת משתמשת בערך ברירת המחדל.

    curl -X PUT "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
         -H "Authorization: Bearer ACCESS_TOKEN" \
         -H "Content-Type: application/json" \
         -d '{
            "title": "TITLE",
            "description": "DESCRIPTION",
            "anonAllowed": ANON_TRUE_OR_FALSE,
            "imageUrl": IMAGE_URL,
            "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
            "categoryIds": [
              "CATEGORY_ID1",
              "CATEGORY_ID2"
            ],
            "published": PUBLISHED_TRUE_OR_FALSE
         }'

במאמר עריכת API מופיעה דוגמה מפורטת של השלבים, המשתנים והמטען הייעודי (payload) שמוחזר.

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

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

כדי לנהל את כתובת ה-URL לקריאה חוזרת של API, אפשר להשתמש בממשק המשתמש או בפקודה curl:

ממשק משתמש

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

  1. גישה לקטלוג ה-API.
  2. לוחצים על הכרטיסייה APIs, אם היא לא נבחרה כבר.
  3. לוחצים על השורה של ה-API שרוצים לערוך.
  4. לוחצים על סמל העריכה עריכה.
  5. בקטע API details, מסמנים את התיבה Require developers to specify a callback URL או מבטלים את הסימון שלה.
  6. לוחצים על שמירה.

curl

כוללים את אחת מהאפשרויות הבאות בקריאה ל-update:

  "requireCallbackUrl": true,    # Portal user is required to input a URL
  "requireCallbackUrl": false,   # Portal user is not required to input a URL

כדי לערוך את ה-API:

  1. החזרת הערכים הנוכחיים:

    curl -X GET "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
         -H "Authorization: Bearer ACCESS_TOKEN"
    
  2. משתמשים בקריאה update כדי לערוך את ה-API. כוללים את הערכים שניתנים לשינוי שרוצים לשמור, ומשנים את הערכים שרוצים לשנות. אם משמיטים הגדרה שניתנת לשינוי, המערכת משתמשת בערך ברירת המחדל.

    curl -X PUT "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
         -H "Authorization: Bearer ACCESS_TOKEN" \
         -H "Content-Type: application/json" \
         -d '{
            "title": "TITLE",
            "description": "DESCRIPTION",
            "anonAllowed": ANON_TRUE_OR_FALSE,
            "imageUrl": IMAGE_URL,
            "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
            "categoryIds": [
              "CATEGORY_ID1",
              "CATEGORY_ID2"
            ],
            "published": PUBLISHED_TRUE_OR_FALSE
         }'

במאמר עריכת API מופיעה דוגמה מפורטת של השלבים, המשתנים והמטען הייעודי (payload) שמוחזר.

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

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

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

ממשק משתמש

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

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

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

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

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

curl

כוללים את הפרטים הבאים בקריאה ל-update:

  # Omit line for no image file

  "imageUrl": "IMAGE_URL"    # URL of the external image or name of the image file

כדי לערוך את ה-API:

  1. החזרת הערכים הנוכחיים:

    curl -X GET "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
         -H "Authorization: Bearer ACCESS_TOKEN"
    
  2. משתמשים בקריאה update כדי לערוך את ה-API. כוללים את הערכים שניתנים לשינוי שרוצים לשמור, ומשנים את הערכים שרוצים לשנות. אם משמיטים הגדרה שניתנת לשינוי, המערכת משתמשת בערך ברירת המחדל.

    curl -X PUT "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
         -H "Authorization: Bearer ACCESS_TOKEN" \
         -H "Content-Type: application/json" \
         -d '{
            "title": "TITLE",
            "description": "DESCRIPTION",
            "anonAllowed": ANON_TRUE_OR_FALSE,
            "imageUrl": IMAGE_URL,
            "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
            "categoryIds": [
              "CATEGORY_ID1",
              "CATEGORY_ID2"
            ],
            "published": PUBLISHED_TRUE_OR_FALSE
         }'

במאמר עריכת API מופיעה דוגמה מפורטת של השלבים, המשתנים והמטען הייעודי (payload) שמוחזר.

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

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

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

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

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

ממשק משתמש

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

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

curl

כוללים את הפרטים הבאים בקריאה ל-update:

  # Omit line for no categories

  "categoryIds": [
      "CATEGORY_ID1",      # A category ID number
      "CATEGORY_ID2"       # A category ID number
    ],

כדי לקבל את מספרי הזיהוי של הקטגוריות, משתמשים בפקודה list categories.

כדי לערוך את ה-API:

  1. החזרת הערכים הנוכחיים:

    curl -X GET "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
         -H "Authorization: Bearer ACCESS_TOKEN"
    
  2. משתמשים בקריאה update כדי לערוך את ה-API. כוללים את הערכים שניתנים לשינוי שרוצים לשמור, ומשנים את הערכים שרוצים לשנות. אם משמיטים הגדרה שניתנת לשינוי, המערכת משתמשת בערך ברירת המחדל.

    curl -X PUT "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
         -H "Authorization: Bearer ACCESS_TOKEN" \
         -H "Content-Type: application/json" \
         -d '{
            "title": "TITLE",
            "description": "DESCRIPTION",
            "anonAllowed": ANON_TRUE_OR_FALSE,
            "imageUrl": IMAGE_URL,
            "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
            "categoryIds": [
              "CATEGORY_ID1",
              "CATEGORY_ID2"
            ],
            "published": PUBLISHED_TRUE_OR_FALSE
         }'

במאמר עריכת API מופיעה דוגמה מפורטת של השלבים, המשתנים והמטען הייעודי (payload) שמוחזר.

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

משתמשים בממשק המשתמש או בפקודה curl כדי לערוך את השם והתיאור שמוצגים:

ממשק משתמש

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

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

curl

כוללים את הפרטים הבאים בקריאה ל-update:

  "title": "TITLE",    # Display title
  "description": "DESCRIPTION",  # Display description

כדי לערוך את ה-API:

  1. החזרת הערכים הנוכחיים:

    curl -X GET "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
         -H "Authorization: Bearer ACCESS_TOKEN"
    
  2. משתמשים בקריאה update כדי לערוך את ה-API. כוללים את הערכים הניתנים לשינוי שרוצים לשמור, ומשנים את הערכים שרוצים לשנות. אם משמיטים הגדרה שניתנת לשינוי, המערכת משתמשת בערך ברירת המחדל.

    curl -X PUT "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
         -H "Authorization: Bearer ACCESS_TOKEN" \
         -H "Content-Type: application/json" \
         -d '{
            "title": "TITLE",
            "description": "DESCRIPTION",
            "anonAllowed": ANON_TRUE_OR_FALSE,
            "imageUrl": IMAGE_URL,
            "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
            "categoryIds": [
              "CATEGORY_ID1",
              "CATEGORY_ID2"
            ],
            "published": PUBLISHED_TRUE_OR_FALSE
         }'

במאמר עריכת API מופיעה דוגמה מפורטת של השלבים, המשתנים והמטען הייעודי (payload) שמוחזר.

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

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

ממשק משתמש

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

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

curl

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

curl -X DELETE "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
    -H "Authorization: Bearer ACCESS_TOKEN"

מחליפים את מה שכתוב בשדות הבאים:

  • ‫ORG_NAME בשם הארגון. לדוגמה, my-org.
  • ‫SITE_ID בשם הפורטל, בפורמט ORG_NAME-PORTAL_NAME, כאשר ORG_NAME הוא שם הארגון ו-PORTAL_NAME הוא שם הפורטל באותיות קטנות בלבד, ללא רווחים ומקפים. לדוגמה, my-org-myportal.
  • ‫API_DOC עם הערך שנוצר בשדה id של המסמך. לדוגמה, 399668. כדי למצוא את הערך הזה, משתמשים בפקודה list API docs.
  • ‫ACCESS_TOKEN באסימון האימות שמשמש לגישה ל-Apigee Edge API. מידע נוסף על אימות ואסימונים זמין במאמר אימות הגישה ל-Edge API.

המטען הייעודי (payload) של התגובה:

{
  "status": "success",
  "message": "Apidoc deleted",
  "data": {
  },
  "code": null,
  "request_id": "1790036484",
  "error_code": null
}

ניהול מאמרי העזרה של ה-API

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

עדכון מאמרי העזרה של ה-API

כדי להעלות גרסה אחרת של מאמרי העזרה של ה-API:

ממשק משתמש

  1. גישה לקטלוג ה-API.
  2. לוחצים על הכרטיסייה ממשקי API, אם היא לא נבחרה כבר.
  3. לוחצים על השורה של ה-API שרוצים לערוך.
  4. בודקים את סטטוס קובץ ה-Snapshot. אם היא לא עדכנית, תוצג ההודעה הבאה: סמל והודעה שמציינים שתמונת המצב לא עדכנית
  5. לוחצים על עריכה.
  6. מבצעים אחת מהמשימות הבאות:
    • כדי לרענן תמונת מצב של מסמך OpenAPI לא עדכני, לוחצים על Refresh Snapshot.
    • כדי לשנות את המסמך שמשמש ליצירת מאמרי העזרה של ה-API, תחת מאמרי העזרה של ה-API לוחצים על Select Document ובוחרים את המסמך החדש.
  7. בחלונית מאמרי העזרה של ה-API, בוחרים אחת מהאפשרויות הבאות:
    • מסמך OpenAPI
    • סכימת GraphQL
  8. לוחצים על בחירת מסמך ובוחרים את הגרסה העדכנית של המסמך.
  9. ב-GraphQL, מציינים את כתובת ה-URL של נקודת הקצה.
  10. לוחצים על שמירה.

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

סמל והודעה שמציינים שתמונת המצב עדכנית

curl

כדי לעדכן את תוכן המסמכים של OpenAPI או GraphQL:

OpenAPI

curl -X PATCH "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC/documentation" \
    -H "Authorization: Bearer ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"oasDocumentation": {
           "spec":{ "displayName":"DISPLAY_NAME",
                    "contents":"CONTENTS"}
            }
        }'

מחליפים את מה שכתוב בשדות הבאים:

  • ‫ORG_NAME בשם הארגון. לדוגמה, my-org.
  • ‫SITE_ID בשם הפורטל, בפורמט ORG_NAME-PORTAL_NAME, כאשר ORG_NAME הוא שם הארגון ו-PORTAL_NAME הוא שם הפורטל באותיות קטנות בלבד, ללא רווחים ומקפים. לדוגמה, my-org-myportal.
  • ‫API_DOC עם הערך של id שנוצר במסמך. לדוגמה, 399668. כדי למצוא את הערך הזה, משתמשים בפקודה list API docs.
  • ‫DISPLAY_NAME בשם המוצג של מאמרי העזרה של ה-API. לדוגמה, Hello World 2.
  • ‫CONTENTS במחרוזת בקידוד base64 של תוכן מאמרי העזרה של ה-API. רוב סביבות הפיתוח מכילות כלי המרה של base64, ויש גם הרבה כלי המרה אונליין.

המטען הייעודי (payload) של התגובה:

{
 "status":"success",
 "message":"Api documentation updated",
 "requestId":"645138278"
 "data": {
   "oasDocumentation": {
     "spec": {
        "displayName": "Hello World 2"
      },
     "Format": "YAML"
   }
 }
}

GraphQL

curl -X PATCH "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC/documentation" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"graphqlDocumentation": {
         "schema":{"displayName":"DISPLAY_NAME",
         "contents":"CONTENTS"},
         "endpointUri": "ENDPOINT_URI"
          }
      }'

מחליפים את מה שכתוב בשדות הבאים:

  • ‫ORG_NAME בשם הארגון. לדוגמה, my-org.
  • ‫SITE_ID בשם הפורטל, בפורמט ORG_NAME-PORTAL_NAME, כאשר ORG_NAME הוא שם הארגון ו-PORTAL_NAME הוא שם הפורטל באותיות קטנות בלבד, ללא רווחים ומקפים. לדוגמה, my-org-myportal.
  • ‫API_DOC עם הערך של id שנוצר במסמך. לדוגמה, 399668. כדי למצוא את הערך הזה, משתמשים בפקודה list API docs.
  • ‫DISPLAY_NAME בשם המוצג של מאמרי העזרה של ה-API. לדוגמה, Hello World 2.
  • ENDPOINT_URI בשם הדומיין של ה-URI של נקודת הקצה. לדוגמה, https://demo.google.com/graphql.
  • ‫CONTENTS במחרוזת בקידוד base64 של תוכן מאמרי העזרה של ה-API. רוב סביבות הפיתוח מכילות כלי המרה של base64, ויש גם הרבה כלי המרה אונליין.

המטען הייעודי (payload) של התגובה:

{
"status": "success",
"message": "ApiDocDocumentation updated",
"data": {
  "oasDocumentation": null,
  "graphqlDocumentation": {
    "schema": {
      "displayName": "schema.docs.graphql",
      "contents": ""
    },
    "endpointUri": "https://demo.google.com/graphql"
  }
},
"code": null,
"request_id": "640336173",
"error_code": null
}

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

הורדת מאמרי העזרה של ה-API

כדי להוריד את מאמרי העזרה של ה-API:

ממשק משתמש

curl

כדי להוריד את מאמרי העזרה של ה-API באמצעות get documentation:

curl -X GET "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC/documentation" \
    -H "Authorization: Bearer ACCESS_TOKEN"

מחליפים את מה שכתוב בשדות הבאים:

  • ‫ORG_NAME בשם הארגון. לדוגמה, my-org.
  • ‫SITE_ID בשם הפורטל, בפורמט ORG_NAME-PORTAL_NAME, כאשר ORG_NAME הוא שם הארגון ו-PORTAL_NAME הוא שם הפורטל באותיות קטנות בלבד, ללא רווחים ומקפים. לדוגמה, my-org-myportal.
  • ‫API_DOC עם הערך שנוצר בשדה id של המסמך. לדוגמה, 399668. כדי למצוא את הערך הזה, משתמשים בפקודה list API docs.

    המטען הייעודי (payload) של התגובה:

{
  "status": "success",
  "message": "ApiDocDocumentation returned",
  "data": {
    "oasDocumentation": {
      "spec": {
        "displayName": "mock",
        "contents": "b3BlbmFwaTogMy4wLjAKaW5mbzoKICBkZXNjcmlw ..."
      },
      "format": "YAML"
    },
    "graphqlDocumentation": null
  },
  "code": null,
  "request_id": "269996898",
  "error_code": null
}

כאשר:

‫contents: מחרוזת בקידוד base64 של תוכן מאמרי העזרה של ה-API.

הסרת מאמרי העזרה של ה-API

כדי להסיר את מאמרי העזרה של ה-API:

ממשק משתמש

  1. גישה לקטלוג ה-API.
  2. לוחצים על הכרטיסייה ממשקי API, אם היא לא נבחרה כבר.
  3. לוחצים על השורה של ה-API שרוצים לערוך.
  4. לוחצים על עריכה.
  5. בחלונית מאמרי העזרה של ה-API, בוחרים באפשרות No documentation.
  6. לוחצים על שמירה.

curl

כדי למחוק תוכן קיים, משתמשים ב-update API:

curl -X PATCH "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC/documentation" \
    -H "Authorization: Bearer ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{}'

מחליפים את מה שכתוב בשדות הבאים:

  • ‫ORG_NAME בשם הארגון. לדוגמה, my-org.
  • ‫SITE_ID בשם הפורטל, בפורמט ORG_NAME-PORTAL_NAME, כאשר ORG_NAME הוא שם הארגון ו-PORTAL_NAME הוא שם הפורטל באותיות קטנות בלבד, ללא רווחים ומקפים. לדוגמה, my-org-myportal.
  • ‫API_DOC עם הערך של id שנוצר במסמך. לדוגמה, 399668. כדי למצוא את הערך הזה, משתמשים בפקודה list API docs.

המטען הייעודי (payload) של התגובה:

{
  "status": "success",
  "message": "ApiDocDocumentation updated",
  "data": {
    "oasDocumentation": null,
    "graphqlDocumentation": null
  },
  "code": null,
  "request_id": "304329676",
  "error_code": null
}

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

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

עוד קטגוריות

כדי לראות את ממשקי ה-API שבפורטל, משתמשים בממשק המשתמש או בפקודה curl.

ממשק משתמש

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

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

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

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

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

הכרטיסייה Categories (קטגוריות) שבה מוצגים שם הקטגוריה, השמות והמספר הכולל של ממשקי ה-API שהוקצו

כפי שמודגש בתמונה הקודמת, בדף APIs אפשר:

curl

כדי להציג רשימה של קטגוריות:

curl -X GET "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apicategories" \
    -H "Authorization: Bearer ACCESS_TOKEN"

מחליפים את מה שכתוב בשדות הבאים:

  • ‫ORG_NAME בשם הארגון. לדוגמה, my-org.
  • ‫SITE_ID בשם הפורטל, בפורמט ORG_NAME-PORTAL_NAME, כאשר ORG_NAME הוא שם הארגון ו-PORTAL_NAME הוא שם הפורטל באותיות קטנות בלבד, ללא רווחים ומקפים. לדוגמה, my-org-myportal.
  • ‫ACCESS_TOKEN באסימון האימות שמשמש לגישה ל-Apigee Edge API. מידע נוסף על אימות ואסימונים זמין במאמר אימות הגישה ל-Edge API.

המטען הייעודי (payload) של התגובה:

{
  "status": "success",
  "message": "all ApiCategory items returned",
  "data": [
    {
      "id": "e0518597-ece2-4d7d-ba7c-d1793df0f8db",
      "siteId": "my-org-myportal",
      "name": "My Category"
    },
    {
      "id": "61c1014c-89c9-40e6-be3c-69cca3505620",
      "siteId": "my-org-myportal",
      "name": "test2"
    }
  ],
  "code": null,
  "request_id": "1263510680",
  "error_code": null
}

כאשר:

  • ‫id: המזהה של הפריט בקטגוריה. לדוגמה, 61c1014c-89c9-40e6-be3c-69cca3505620.

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

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

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

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

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

ממשק משתמש

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

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

curl

כדי להוסיף קטגוריה:

curl -X POST "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apicategories" \
    -H "Authorization: Bearer ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"name": "CATEGORY_NAME" }'

מחליפים את מה שכתוב בשדות הבאים:

  • ‫ORG_NAME בשם הארגון. לדוגמה, my-org.
  • ‫SITE_ID בשם הפורטל, בפורמט ORG_NAME-PORTAL_NAME, כאשר ORG_NAME הוא שם הארגון ו-PORTAL_NAME הוא שם הפורטל באותיות קטנות בלבד, ללא רווחים ומקפים. לדוגמה, my-org-myportal.
  • ‫ACCESS_TOKEN באסימון האימות שמשמש לגישה ל-Apigee Edge API. מידע נוסף על אימות ואסימונים זמין במאמר אימות הגישה ל-Edge API.
  • CATEGORY_NAME בשם הקטגוריה. לדוגמה, demo-backend.

המטען הייעודי (payload) של התגובה:

{
  "status": "success",
  "message": "API category created",
  "data": {
    "id": "61de810e-b48b-4cc1-8f22-959038aadcce",
    "siteId": "my-org-myportal",
    "name": "demo-backend"
  },
  "code": null,
  "request_id": "363146927",
  "error_code": null
}

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

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

ממשק משתמש

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

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

curl

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

curl -X PATCH "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apicategories/CATEGORY_ID"  \
    -H "Authorization: Bearer ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"name": "CATEGORY_NAME" }'

מחליפים את מה שכתוב בשדות הבאים:

  • ‫ORG_NAME בשם הארגון. לדוגמה, my-org.
  • ‫SITE_ID בשם הפורטל, בפורמט ORG_NAME-PORTAL_NAME, כאשר ORG_NAME הוא שם הארגון ו-PORTAL_NAME הוא שם הפורטל באותיות קטנות בלבד, ללא רווחים ומקפים. לדוגמה, my-org-myportal.
  • ‫CATEGORY_ID במזהה הקטגוריה. לדוגמה: bf6505eb-2a0f-47af-a00a-ded40ac72960. אם יש כמה מזהי קטגוריות, צריך להפריד ביניהם באמצעות פסיק. משיגים את מזהה הקטגוריה באמצעות הפקודה list API categories.
  • ‫ACCESS_TOKEN באסימון האימות שמשמש לגישה ל-Apigee Edge API. מידע נוסף על אימות ואסימונים זמין במאמר אימות הגישה ל-Edge API.
  • CATEGORY_NAME בשם הקטגוריה. לדוגמה, demo-backend.

המטען הייעודי (payload) של התגובה:

{
  "status": "success",
  "message": "ApiCategory updated",
  "data": {
    "id": "61de810e-b48b-4cc1-8f22-959038aadcce",
    "siteId": "my-org-myportal",
    "name": "demo-backend-test"
  },
  "code": null,
  "request_id": "1976875617",
  "error_code": null
}

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

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

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

ממשק משתמש

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

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

curl

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

curl -X DELETE "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apicategories/CATEGORY_ID" \
    -H "Authorization: Bearer ACCESS_TOKEN" \
    -H "Content-Type: application/json"

מחליפים את מה שכתוב בשדות הבאים:

  • ‫ORG_NAME בשם הארגון. לדוגמה, my-org.
  • ‫SITE_ID בשם הפורטל, בפורמט ORG_NAME-PORTAL_NAME, כאשר ORG_NAME הוא שם הארגון ו-PORTAL_NAME הוא שם הפורטל באותיות קטנות בלבד, ללא רווחים ומקפים. לדוגמה, my-org-myportal.
  • ‫CATEGORY_ID במזהה הקטגוריה. לדוגמה, bf6505eb-2a0f-47af-a00a-ded40ac72960. כדי לקבל את מזהה הקטגוריה, משתמשים בפקודה list API categories.
  • ‫ACCESS_TOKEN עם אסימון האימות שמשמש לגישה ל-Apigee Edge API. מידע נוסף על אימות ואסימונים זמין במאמר אימות הגישה ל-Edge API.

המטען הייעודי (payload) של התגובה:

{
  "status": "success",
  "message": "ApiCategory deleted",
  "data": {
  },
  "code": null,
  "request_id": "2032819627",
  "error_code": null
}

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

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

שגיאה: השגיאה "אחזור הנתונים נכשל" מופיעה כשמשתמשים ב-Try this API

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

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

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

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

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

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

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

<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>

שגיאה: אסור להשתמש בשדה request header

אם אתם משתמשים ב-Try this 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, כמו שמתואר במאמר צירוף מדיניות Add CORS ל-proxy חדש ל-API.

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

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

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