‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

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

הדף הזה רלוונטי ל-Apigee ול-Apigee Hybrid.

לעיון במסמכי התיעוד של Apigee Edge

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

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

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

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

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

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

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

SmartDocs (OpenAPI)

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

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

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

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

GraphQL Explorer

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

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

GraphQL Explorer בפורטל

‫GraphQL Explorer בפורטל

AsyncAPI

כשמפרסמים API באמצעות מסמך AsyncAPI, התיעוד של AsyncAPI מתווסף לפורטל. ‫AsyncAPI הוא תקן פתוח להגדרת ממשקי API אסינכרוניים, כמו אלה שמשמשים בארכיטקטורות מבוססות-אירועים עם פרוטוקולי העברת הודעות כמו Kafka או Solace. פרסום של מסמך AsyncAPI יוצר תיעוד שמאפשר למפתחים לעיין בתיעוד של ממשקי API אסינכרוניים כדי להבין את הערוצים ואת נתוני התשלום שלהם. בניגוד לתכונה 'Try this API' של OpenAPI, בדיקה אינטראקטיבית לא נתמכת במסמכי AsyncAPI בפורטל.

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

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

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

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

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

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

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

הגדרת proxy ל-API לתמיכה בחלונית Try this API

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

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

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

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

ניהול ממשקי API

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

חיפוש ממשקי API

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

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

ממשק המשתמש של Apigee

במסוף Apigee ב-Cloud, עוברים לדף Distribution > Portals.

מעבר אל Portals
לוחצים על הפורטל.
לוחצים על API Catalog (קטלוג API).
לוחצים על הכרטיסייה APIs. מוצגת רשימה של ממשקי ה-API שנוספו לפורטל.

בכרטיסייה APIs אפשר:

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

curl

כדי להציג רשימה של ממשקי API באמצעות organizations.sites.apidocs/list:

curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"

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

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

הוראות לשימוש בהחלפה בין דפים במטען הייעודי לתגובה מפורטות בהערות לגבי החלפה בין דפים.

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

{
  "status": "success",
  "message": "one page of apidocs returned",
  "requestId": "1167960478",
  "data": [
    {
      "siteId": "my-org-myportal",
      "title": "Hello New World",
      "description": "Simple hello new world example",
      "specId": "hellowworld",
      "modified": "1695841621000",
      "anonAllowed": true,
      "imageUrl": "/files/camper1.jpg?v=1695841491415",
      "id": "381054",
      "categoryIds": [
        "e0518597-ece2-4d7d-ba7c-d1793df0f8db",
        "61c1014c-89c9-40e6-be3c-69cca3505620"
      ],
      "published": true,
      "apiProductName": "Hello New World"
    },
    {
      "siteId": "my-org-myportal",
      "title": "mock-product",
      "description": "Mock product",
      "specId": "apigee spec",
      "modified": "1698956849000",
      "anonAllowed": true,
      "id": "399638",
      "categoryIds": [
        "e0518597-ece2-4d7d-ba7c-d1793df0f8db"
      ],
      "published": true,
      "apiProductName": "mock-product"
    },
    {
      "siteId": "my-org-myportal",
      "title": "Hello World 2",
      "description": "Simple hello world example",
      "specId": "hello-new-world",
      "modified": "1698950207000",
      "anonAllowed": true,
      "imageUrl": "/files/book-tree.jpg?v=1698165437881",
      "id": "399668",
      "categoryIds": [
        "e0518597-ece2-4d7d-ba7c-d1793df0f8db",
        "61c1014c-89c9-40e6-be3c-69cca3505620"
      ],
      "published": true,
      "apiProductName": "Hello World 2"
    }
  ],
  "nextPageToken": ""
}

כאשר:

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

הערות לגבי עימוד:

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

curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs?pageSize=PAGE_SIZE" \
   -H "Authorization: Bearer $(gcloud auth print-access-token)"

מחליפים את:

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

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

{
  "status": "success",
  "message": "one page of apidocs returned",
  "requestId": "918815495",
  "data": [
    {
      "siteId": "my-org-myportal",
      "title": "Hello New World",
      "description": "Simple hello new world example",
      "specId": "apigee",
      "modified": "1699146887000",
      "anonAllowed": true,
      "imageUrl": "/files/camper1.jpg?v=1695841491415",
      "id": "381054",
      "categoryIds": [
        "e0518597-ece2-4d7d-ba7c-d1793df0f8db",
        "61c1014c-89c9-40e6-be3c-69cca3505620"
      ],
      "published": true,
      "apiProductName": "Hello New World"
    }
  ],
  "nextPageToken": "7zcqrin9l6xhi4nbrb9"
}

טוקן דף:

אם יש יותר מדף אחד, אפשר להשתמש ב-pageToken כדי לאחזר את הדפים הבאים:
```
curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs?pageSize=PAGE_SIZE&pageToken=PAGE_TOKEN" \
      -H "Authorization: Bearer $(gcloud auth print-access-token)"
```
מחליפים את:
- ‫PAGE_SIZE עם מספר הפריטים ברשימה שיוחזרו בדף אחד. לדוגמה, 10.
- ‫PAGE_TOKEN עם הערך nextPageToken. לדוגמה, 7zcqrin9l6xhi4nbrb9.

הוספת API

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

ממשק המשתמש של Apigee

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

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

שדה	תיאור
פורסם	לוחצים על Published (פורסם) כדי לפרסם את ה-API בפורטל. אם אתם לא מוכנים לפרסם את ה-API, מבטלים את הסימון בתיבת הסימון. אפשר לשנות את ההגדרה הזו מאוחר יותר, כמו שמתואר במאמר בנושא פרסום API או ביטול הפרסום שלו.
כותרת לתצוגה	מעדכנים את השם של ה-API שמוצג בקטלוג. כברירת מחדל, נעשה שימוש בשם מוצר ה-API. אפשר לשנות את השם המוצג מאוחר יותר, כמו שמתואר במאמר עריכת השם המוצג והתיאור.
תיאור התצוגה	מעדכנים את התיאור של ה-API שמוצג בקטלוג. כברירת מחדל, המערכת משתמשת בתיאור המוצר ב-API. אפשר לשנות את התיאור המוצג מאוחר יותר, כמו שמתואר במאמר בנושא עריכת השם והתיאור המוצגים.
דרישה ממפתחים לציין כתובת URL לקריאה חוזרת (callback)	מפעילים את האפשרות הזו אם רוצים לדרוש ממפתחי אפליקציות לציין כתובת URL של קריאה חוזרת (callback). אפשר להוסיף או לעדכן את כתובת ה-URL לקריאה חוזרת (callback) בהמשך, כמו שמתואר במאמר ניהול כתובת ה-URL לקריאה חוזרת (callback) עבור API.
מאמרי העזרה של ה-API	כדי להשתמש במסמך OpenAPI: בוחרים באפשרות מסמך OpenAPI. לוחצים על בחירה. מבצעים אחת מהפעולות הבאות: לוחצים על הכרטיסייה העלאה ומעלים קובץ. לוחצים על הכרטיסייה URL ומייבאים מפרט על ידי הזנת שם וכתובת URL שממנה יתבצע הייבוא. לוחצים על בחירה. כדי להשתמש בסכימת GraphQL: בוחרים באפשרות GraphQL Schema. לוחצים על בחירה. עוברים אל סכימת GraphQL ובוחרים בה. מציינים את כתובת ה-URL של נקודת הקצה, שהיא מזהה ה-URI של נקודת הקצה של GraphQL שאליה צרכני ה-API שולחים שאילתות. לוחצים על בחירה. כדי להשתמש במסמך AsyncAPI: בוחרים באפשרות מסמך AsyncAPI. לוחצים על בחירה. מנווטים אל מסמך AsyncAPI ובוחרים בו. לוחצים על בחירה. לחלופין, אפשר לבחור באפשרות No documentation ולהוסיף מסמך מאוחר יותר אחרי הוספת ה-API, כמו שמתואר במאמר ניהול מסמכי ה-API. הערה: כשמייבאים מסמך OpenAPI באמצעות כתובת URL, המערכת לא עוקבת אחרי הפניות אוטומטיות.
הרשאות גישה	אם לא נרשמתם לגרסת הטרום-השקה של התכונה לניהול קהלים, אתם צריכים לבחור באחת מהאפשרויות הבאות: משתמשים אנונימיים כדי לאפשר לכל המשתמשים לצפות ב-API. משתמשים רשומים כדי לאפשר רק למשתמשים רשומים לצפות ב-API. אם נרשמתם לגרסת הטרום-השקה של התכונה לניהול קהלים, אתם יכולים לבחור באחת מהאפשרויות הבאות: גלוי לכולם כדי לאפשר לכל המשתמשים לצפות ב-API. משתמשים מאומתים כדי לאפשר רק למשתמשים רשומים לראות את ה-API. קהלים נבחרים כדי לבחור את הקהלים הספציפיים שרוצים לאפשר להם לצפות ב-API. אפשר לנהל את הרשאות הגישה לקהל מאוחר יותר, כמו שמתואר במאמר בנושא ניהול הרשאות הגישה ל-API.
תמונה לתצוגה	כדי להציג תמונה בכרטיס ה-API בדף APIs, לוחצים על Select image (בחירת תמונה). בתיבת הדו-שיח בחירת תמונה, בוחרים תמונה קיימת, מעלים תמונה חדשה או מציינים את כתובת ה-URL של תמונה חיצונית, ואז לוחצים על בחירה. בודקים את התמונה הממוזערת של ה-API ולוחצים על בחירה. אפשר להוסיף תמונה מאוחר יותר, כמו שמתואר במאמר ניהול התמונה של כרטיס API. כשמציינים את כתובת ה-URL של תמונה חיצונית, התמונה לא מועלית לנכסים שלכם. בנוסף, טעינת התמונה בפורטל המשולב תהיה תלויה בזמינות שלה, שיכולה להיות חסומה או מוגבלת על ידי מדיניות אבטחת תוכן.
קטגוריות	מוסיפים את הקטגוריות שבהן יתויג ה-API כדי שמפתחי אפליקציות יוכלו למצוא ממשקי API קשורים בדף APIs. כדי לזהות קטגוריה: בוחרים קטגוריה מהרשימה הנפתחת. מוסיפים קטגוריה חדשה כמו שמתואר במאמר בנושא הוספת קטגוריה. הקטגוריה החדשה מתווספת לדף Categories (קטגוריות) וזמינה כשמוסיפים או עורכים ממשקי API אחרים.

לוחצים על Save.

curl

כדי להוסיף API לפורטל באמצעות organizations.sites.apidocs.create:

curl -X POST "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs" \
         -H "Authorization: Bearer $(gcloud auth print-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.
‫TITLE עם הכותרת המוצגת. לדוגמה, Hello World 2.
DESCRIPTION עם תיאור המסך. לדוגמה, Simple hello world example.
‫ANON_TRUE_OR_FALSE עם true או false (ברירת מחדל), כאשר true מאפשר גישה למשתמשים לא רשומים. המערכת מתעלמת מההגדרה הזו אם נרשמתם לגרסת טרום-השקה של התכונה לניהול קהלים.
‫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",
  "requestId": "1662161889",
  "data": {
    "siteId": "my-org-myportal",
    "title": "Hello World 2",
    "description": "Simple hello world example",
    "modified": "1698948807000",
    "anonAllowed": true,
    "imageUrl": "/files/book-tree.jpg",
    "id": "409405",
    "requireCallbackUrl": true,
    "categoryIds": [
      "88fbfd1d-9300-49f7-bfc2-531ade4c63d4",
      "630c4cf9-109a-48b0-98cc-ef4c12ae4474"
    ],
    "published": true,
    "apiProductName": "Hello World 2"
  }
}

כאשר:

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

עריכת API

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

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

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

ממשק המשתמש של Apigee

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

curl

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

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

כדי לאתר את id שנוצר ומזהה באופן ייחודי כל API, אפשר להשתמש ב-organizations.sites.apidocs/list כדי לקבל רשימה של ממשקי ה-API בפורטל:

curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"

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

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

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

{
  "status": "success",
  "message": "one page of apidocs returned",
  "requestId": "1167960478",
  "data": [
    {
      "siteId": "my-org-myportal",
      "title": "Hello New World",
      "description": "Simple hello new world example",
      "specId": "hellowworld",
      "modified": "1695841621000",
      "anonAllowed": true,
      "imageUrl": "/files/camper1.jpg?v=1695841491415",
      "id": "381054",
      "categoryIds": [
        "e0518597-ece2-4d7d-ba7c-d1793df0f8db",
        "61c1014c-89c9-40e6-be3c-69cca3505620"
      ],
      "published": true,
      "apiProductName": "Hello New World"
    },
    {
      "siteId": "my-org-myportal",
      "title": "mock-product",
      "description": "Mock product",
      "specId": "apigee spec",
      "modified": "1698956849000",
      "anonAllowed": true,
      "id": "399638",
      "categoryIds": [
        "e0518597-ece2-4d7d-ba7c-d1793df0f8db"
      ],
      "published": true,
      "apiProductName": "mock-product"
    },
    {
      "siteId": "my-org-myportal",
      "title": "Hello World 2",
      "description": "Simple hello world example",
      "specId": "hello-new-world",
      "modified": "1698950207000",
      "anonAllowed": true,
      "imageUrl": "/files/book-tree.jpg?v=1698165437881",
      "id": "399668",
      "categoryIds": [
        "e0518597-ece2-4d7d-ba7c-d1793df0f8db",
        "61c1014c-89c9-40e6-be3c-69cca3505620"
      ],
      "published": true,
      "apiProductName": "Hello World 2"
    }
  ]
}

כאשר:

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

משתמשים בקריאה organizations.sites.apidocs.get כדי להחזיר את הערכים הנוכחיים של API ספציפי:

curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
    -H "Authorization: Bearer $(gcloud auth print-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": "apidoc returned",
  "requestId": "2072952505",
  "data": {
    "siteId": "my-org-myportal",
    "title": "Hello World 2",
    "description": "Simple hello world example",
    "specId": "hello-new-world",
    "modified": "1698950207000",
    "anonAllowed": true,
    "imageUrl": "/files/book-tree.jpg?v=1698165437881",
    "id": "399668",
    "categoryIds": [
      "e0518597-ece2-4d7d-ba7c-d1793df0f8db",
      "61c1014c-89c9-40e6-be3c-69cca3505620"
    ],
    "published": true,
    "apiProductName": "Hello World 2"
  }
}

כוללים את הערכים הניתנים לשינוי שרוצים לשמור בקריאה organizations.sites.apidocs.update, ומשנים את הערכים שרוצים לשנות. אם משמיטים שורה, המערכת משתמשת בהגדרת ברירת המחדל. בדוגמה הזו, משנים את ההגדרה published מ-true ל-false:
```
curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-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": false,
        "apiProductName": "API_PRODUCT",
     }'
```
מחליפים את מה שכתוב בשדות הבאים:
- ‫TITLE עם הכותרת המוצגת. לדוגמה, Hello World 2.
- DESCRIPTION עם תיאור המסך. לדוגמה, Simple hello world example.
- ‫ANON_TRUE_OR_FALSE עם true או false (ברירת מחדל), כאשר true מאפשר גישה למשתמשים לא רשומים. המערכת מתעלמת מההגדרה הזו אם נרשמתם לגרסת טרום-השקה של התכונה לניהול קהלים.
- ‫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.
- ‫API_PRODUCT עם שם מוצר ה-API. לדוגמה, Hello World 2.
המטען הייעודי (payload) של התשובה:
```
{
  "status": "success",
  "message": "ApiDoc updated",
  "requestId": "197181831",
  "data": {
    "siteId": "my-org-myportal",
    "title": "Hello World 2",
    "description": "Simple hello world example.",
    "modified": "1698884328000",
    "anonAllowed": true,
    "imageUrl": "/files/book-tree.jpg",
    "id": "408567",
    "requireCallbackUrl": true,
    "categoryIds": [
      "88fbfd1d-9300-49f7-bfc2-531ade4c63d4",
      "630c4cf9-109a-48b0-98cc-ef4c12ae4474"
    ],
    "published": PUBLISHED_TRUE_OR_FALSE,
    "apiProductName": "Hello World 2"
  }
}
```

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

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

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

ממשק המשתמש של Apigee

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

curl

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

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

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

משתמשים בקריאה organizations.sites.apidocs.get כדי להחזיר את הערכים הנוכחיים:

curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)"

משתמשים בקריאה organizations.sites.apidocs.update כדי לערוך את ה-API. כוללים את הערכים שניתנים לשינוי שרוצים לשמור, ומשנים את הערכים שרוצים לשנות. אם לא מציינים הגדרה שניתנת לשינוי, המערכת משתמשת בערך ברירת המחדל.

curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-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",
     }'

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

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

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

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

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

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

ממשק המשתמש של Apigee

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

curl

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

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

צריך לכלול את אחת מהאפשרויות הבאות בשיחה עם update:

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

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

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

משתמשים בקריאה organizations.sites.apidocs.get כדי להחזיר את הערכים הנוכחיים:

curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)"

curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-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",
     }'

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

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

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

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

ממשק המשתמש של Apigee

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

curl

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

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

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

משתמשים בקריאה organizations.sites.apidocs.get כדי להחזיר את הערכים הנוכחיים:

curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)"

curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-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",
     }'

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

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

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

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

ממשק המשתמש של Apigee

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

curl

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

  # Omit line for no image file

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

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

משתמשים בקריאה organizations.sites.apidocs.get כדי להחזיר את הערכים הנוכחיים:

curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)"

curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-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",
     }'

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

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

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

כדי לתייג API עם קטגוריות:

ממשק המשתמש של Apigee

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

curl

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

  # Omit line for no categories

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

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

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

משתמשים בקריאה organizations.sites.apidocs.get כדי להחזיר את הערכים הנוכחיים:

curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)"

curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-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",
     }'

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

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

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

ממשק המשתמש של Apigee

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

curl

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

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

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

משתמשים בקריאה organizations.sites.apidocs.get כדי להחזיר את הערכים הנוכחיים:

curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)"

curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-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",
     }'

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

הסרת API

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

ממשק המשתמש של Apigee

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

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

curl

כדי להסיר API מהפורטל באמצעות organizations.sites.apidocs.delete:

curl -X DELETE "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
    -H "Authorization: Bearer $(gcloud auth print-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":"Apidoc deleted",
  "requestId":"645138256"
}

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

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

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

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

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

ממשק המשתמש של Apigee

גישה לקטלוג ה-API
לוחצים על הכרטיסייה APIs (ממשקי API), אם היא לא מסומנת.
לוחצים על השורה של ה-API שרוצים לערוך.
לוחצים על עריכה.
לקבלת API documentation (מאמרי העזרה של ה-API), בוחרים באחת מהאפשרויות הבאות:
- מסמך OpenAPI
- מסמך AsyncAPI
- סכימת GraphQL
מאתרים את הקובץ.
1. לוחצים על בחירה.
2. מאתרים את הקובץ ובוחרים אותו.
ב-GraphQL, מציינים את כתובת ה-URL של נקודת הקצה.
לוחצים על בחירה.
לוחצים על Save.

curl

כדי לעדכן את תוכן התיעוד של OpenAPI,‏ AsyncAPI או GraphQL באמצעות organizations.sites.apidocs.updateDocumentation:

OpenAPI

curl -X PATCH "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC/documentation" \
    -H "Authorization: Bearer $(gcloud auth print-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://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC/documentation" \
    -H "Authorization: Bearer $(gcloud auth print-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":"Api documentation updated",
 "requestId":"645138278",
  "data": {
    "graphqlDocumentation": {
      "schema": {
        "displayName": "Hello World 2"
      },
     "endpointUri": "https://demo.google.com/graphql"
    }
  }
}

AsyncAPI

curl -X PATCH "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC/documentation" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{"asyncApiDocumentation": {
           "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": {
   "asyncApiDocumentation": {
     "spec": {
        "displayName": "Hello World 2"
      },
     "Format": "YAML"
   }
 }
}

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

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

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

כדי להוריד תיעוד של API באמצעות organizations.sites.apidocs.getDocumentation:

curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC/documentation" \
    -H "Authorization: Bearer $(gcloud auth print-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":"Api documentation downloaded",
  "requestId":"645138256",
  "data": {
      "oasDocumentation":{
          "spec":{
            "displayName":"Hello World 2",
            "contents":"c3dhZ2dlcjogJzIuMCcKaW5mbzoKICBkZXNlI ..."
          },
          "Format": YAML
      }
  }
}

כאשר:

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

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

כדי להסיר תיעוד של API:

ממשק המשתמש של Apigee

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

curl

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

כדי לשלוח גוף בקשה ריק ולנקות תוכן קיים באמצעות organizations.sites.apidocs.updateDocumentation:

curl -X PATCH "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC/documentation" \
    -H "Authorization: Bearer $(gcloud auth print-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":"Api documentation updated",
   "requestId":"645138279"
}

ניהול קטגוריות

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

עוד קטגוריות

אפשר להשתמש במסוף או בפקודה curl כדי להציג קטגוריות.

ממשק המשתמש של Apigee

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

curl

כדי להציג רשימה של קטגוריות באמצעות organizations.sites.apicategories.list:

curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apicategories" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"

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

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

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

{
  "data": [
    {
      "siteId": "my-org-myportal",
      "name": "Get Started",
      "id": "e0518597-ece2-4d7d-ba7c-d1793df0f8db"
    },
    {
      "siteId": "my-org-myportal",
      "name": "Test",
      "id": "61c1014c-89c9-40e6-be3c-69cca3505620"
    }
  ],
  "status": "success",
  "message": "all ApiCategory items returned",
  "requestId": "602661435"
}

כאשר:

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

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

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

ממשק המשתמש של Apigee

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

curl

כדי להוסיף קטגוריה באמצעות organizations.sites.apicategories.create:

curl  -X POST "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apicategories" \
    -H "Authorization: Bearer $(gcloud auth print-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_NAME בשם הקטגוריה. לדוגמה, demo-backend.

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

{
  "data": {
    "siteId": "my-org-myportal",
    "name": "demo-backend",
    "id": "ed0b6c1d-eb49-419f-8475-9a428ed5b8d1"
  },
  "status": "success",
  "message": "API category created",
  "requestId": "295617049"
}

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

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

ממשק המשתמש של Apigee

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

curl

כדי לערוך קטגוריה באמצעות organizations.sites.apicategories.patch:

curl -X PATCH "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apicategories/CATEGORY_ID"  \
    -H "Authorization: Bearer $(gcloud auth print-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.
‫CATEGORY_NAME בשם הקטגוריה. לדוגמה, demo-backend.

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

{
  "data": {
    "siteId": "my-org-myportal",
    "name": "demo-backend-test",
    "id": "ed0b6c1d-eb49-419f-8475-9a428ed5b8d1"
  },
  "status": "success",
  "message": "ApiCategory updated",
  "requestId": "192211979"
}

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

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

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

ממשק המשתמש של Apigee

נכנסים לדף Categories.
למחוק קטגוריה. בשורה של הקטגוריה שרוצים לערוך, לוחצים על עוד > מחיקה.
לוחצים על מחיקה כדי לאשר.

curl

כדי למחוק קטגוריה באמצעות organizations.sites.apicategories.delete:

curl -X DELETE "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apicategories/CATEGORY_ID" \
    -H "Authorization: Bearer $(gcloud auth print-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.

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

{
  "status": "success",
  "message": "ApiCategory deleted",
  "requestId": "1610396471"
}

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

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

שגיאה: השגיאה 'הפעולה נכשלה' מוחזרת כשמשתמשים באפשרות 'ניסיון של ה-API הזה'

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

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

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

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

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 באמצעות OAuth 2.0

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

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

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

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

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

SmartDocs (OpenAPI)

GraphQL Explorer

AsyncAPI

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

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

הגדרת proxy ל-API לתמיכה בחלונית Try this API

ניהול ממשקי API

חיפוש ממשקי API

ממשק המשתמש של Apigee

curl

הוספת API

ממשק המשתמש של Apigee

curl

עריכת API

ממשק המשתמש של Apigee

curl

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

ממשק המשתמש של Apigee

curl

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

ממשק המשתמש של Apigee

curl

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

ממשק המשתמש של Apigee

curl

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

ממשק המשתמש של Apigee

curl

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

ממשק המשתמש של Apigee

curl

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

ממשק המשתמש של Apigee

curl

הסרת API

ממשק המשתמש של Apigee

curl

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

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

ממשק המשתמש של Apigee

curl

OpenAPI

GraphQL

AsyncAPI

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

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

ממשק המשתמש של Apigee

curl

ניהול קטגוריות

עוד קטגוריות

ממשק המשתמש של Apigee

curl

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

ממשק המשתמש של Apigee

curl

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

ממשק המשתמש של Apigee

curl

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

ממשק המשתמש של Apigee

curl

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

שגיאה: השגיאה 'הפעולה נכשלה' מוחזרת כשמשתמשים באפשרות 'ניסיון של ה-API הזה'

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

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

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