הצגת מפרט OpenAPI לשילוב

תצוגה מקדימה – מפרט OpenAPI

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

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

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

מהו מפרט OpenAPI?

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

הערה: Application Integration תומך רק במפרט OpenAPI גרסה 3.0.1.

יצירה של מפרט OpenAPI וצפייה בו

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

לפני שמתחילים

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

הצגת מפרט OpenAPI

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

המסוף

כדי לראות את מפרט OpenAPI לשילוב ספציפי:

1. עוברים לדף Application Integration (שילוב אפליקציות).

   מעבר אל Application Integration

2. בתפריט הניווט, לוחצים על Integrations (שילובים).

   מוצג הדף Integrations (שילובים), שבו מפורטים כל השילובים שזמינים ב Google Cloud פרויקט.

3. לוחצים על השילוב שרוצים לראות את מפרט OpenAPI שלו. השילוב ייפתח בכלי לעריכת שילובים.
4. לוחצים על (תפריט הפעולות) בסרגל הכלים של כלי עריכת השילוב, ובוחרים באפשרות הצגת מפרט OpenAPI.

   מופיע החלונית View OpenAPI spec (הצגת מפרט OpenAPI) עם מפרט OpenAPI של השילוב. כברירת מחדל, מפרט ה-OpenAPI שנוצר מכיל את כל הטריגרים של ה-API שהוגדרו בשילוב.

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

הערה: אפשר לצפות במפרט OpenAPI ולהוריד אותו בפורמט YAML רק לשילוב אחד בכל פעם דרך כלי העריכה של השילוב. כדי לראות ולהוריד את מפרט OpenAPI בפורמט YAML או JSON, פועלים לפי ההוראות בקטע API.

API

השיטה generateOpenApiSpec של Application Integration API מאפשרת לכם להציג את מפרט OpenAPI של השילוב באמצעות קריאה ל-API.

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

טיפ: בדרך כלל curl מותקן מראש במערכות הפעלה Linux ו-macOS. אם אין לכם את curl, אתם יכולים להוריד אותו מcurl דף ההורדות והגרסאות.

curl -X POST \
    -H "authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{
    "apiTriggerResources": [{
    "integrationResource": "INTEGRATION_NAME",
    "triggerId": ["api_trigger/TRIGGER_NAME", "api_trigger/TRIGGER_NAME_2", "api_trigger/TRIGGER_NAME_n"]
    },
    {
    "integrationResource": "INTEGRATION_NAME",
      "triggerId": ["api_trigger/TRIGGER_NAME"]
    }],
    "fileFormat": "DOC_TYPE"
    }' \
    "https://LOCATION-integrations.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION:generateOpenApiSpec"
          

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

• ‫TRIGGER_NAME, TRIGGER_NAME_2, TRIGGER_NAME_n: השמות של טריגר ה-API באינטגרציה שרוצים לראות את מפרט ה-OpenAPI שלו.
• ‫INTEGRATION_NAME: השם של השילוב.
• ‫DOC_TYPE: סוג המסמך שרוצים ליצור. הערכים הנתמכים הם YAML או JSON.
• ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
• ‫LOCATION: המיקום של הפרויקט ב- Google Cloud .
  הערה: אפשר לראות את מפרט OpenAPI של כמה שילובים רק אם הם נמצאים באותו אזור.

הסבר על מפרט OpenAPI

שירות Application Integration יוצר את מפרט OpenAPI לשילובים שפורסמו בהתאם לתקן OpenAPI Specification 3.0. בטבלה הבאה מפורטים הרכיבים של מפרט OpenAPI שנוצר ב-Application Integration:

רכיב	תיאור
openapi	הגרסה של מפרט OpenAPI שבה נעשה שימוש.
info	מידע על השילוב, כמו השם (הכותרת), התיאור והגרסה שפורסמה.
servers	כתובות ה-URL של השרתים שמארחים את השילוב.
paths	נתיבים נוצרים לכל טריגר API שנבחר בשילוב. כתובת ה-URL של השרת בשילוב עם הנתיב מהווה את נקודת קצה ל-API לצורך ביצוע קריאות ל-API. השדות Request ו-Response מתמלאים על סמך משתני הקלט והפלט שהוגדרו לטריגר ה-API המתאים. הערה: נכון לעכשיו, Application Integration תומך רק בקבוצה מוגבלת של מילות מפתח של סכימת JSON. מידע על מילות המפתח הנתמכות זמין במאמר שיקולים.
components	השדה schemas מכיל את סכימת ה-JSON של משתני הקלט והפלט של טריגר ה-API. השדה securitySchemes מכיל את פרטי האימות של טריגרים של API.

לתשומת ליבכם

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

• מפרט OpenAPI נוצר רק לשילובים שפורסמו.
• מפרט OpenAPI נוצר רק לשילובים שהוגדרו עם טריגר API אחד או יותר.
• מפרט OpenAPI נוצר רק לשילובים באותו אזור.
• כברירת מחדל, מפרט ה-OpenAPI נוצר בפורמט YAML. כדי ליצור ולהציג את מפרט OpenAPI בפורמט JSON, צריך להגדיר את הפרמטר fileFormat לערך JSON בקריאה ל-API.
• בשלב הזה, Application Integration תומך רק בקבוצה המוגבלת הבאה של מילות מפתח בסכימת JSON:
  • type
  • items
  • properties
  • description
  • required
  • array
  • object
  • oneOf
  • allOf
  • anyOf
  • not
  • null
  • enum
  • additionalProperties
  • default
• כשמאמתים את מפרט OpenAPI באמצעות Swagger Editor, יכול להיות שיוצגו שגיאות סמנטיות שקשורות לנתיבי ה-API, כמו בתמונה הבאה:

  

  אפשר להתעלם מהשגיאות האלה. מפרט ה-OpenAPI עדיין תקף.

המאמרים הבאים

• פיתוח צ'אט בוטים באמצעות Application Integration
• מידע על טריגרים של API
• מידע נוסף על בדיקה ופרסום של שילובים