כלים של OpenAPI

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

מגבלות:

  • כל כלי OpenAPI יכול להכיל רק פעולה או פונקציה אחת.

סכימה לדוגמה:

openapi: 3.0.0
info:
  title: Simple Pets API
  version: 1.0.0
servers:
  - url: 'https://api.pet-service-example.com/v1'
paths:
  /pets/{petId}:
    get:
      summary: Return a pet by ID.
      operationId: getPet
      parameters:
        - in: path
          name: petId
          required: true
          description: Pet id
          schema:
            type: integer
      responses:
        200:
          description: OK
  /pets:
    get:
      summary: List all pets
      operationId: listPets
      parameters:
        - name: petName
          in: query
          required: false
          description: Pet name
          schema:
            type: string
        - name: label
          in: query
          description: Pet label
          style: form
          explode: true
          required: false
          schema:
            type: array
            items:
              type: string
        - name: X-OWNER
          in: header
          description: Optional pet owner provided in the HTTP header
          required: false
          schema:
            type: string
        - name: X-SESSION
          in: header
          description: session id
          required: true
          schema:
            type: string
          x-ces-session-context: $context.session_id
      responses:
        '200':
          description: An array of pets
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pet'
    post:
      summary: Create a new pet
      operationId: createPet
      requestBody:
        description: Pet to add to the store
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Pet'
      responses:
        '201':
          description: Pet created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
components:
  schemas:
    Pet:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        owner:
          type: string
        label:
          type: array
          items:
            type: string

הוספת משתני הקשר של הסשן

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

לדוגמה:

      parameters:
        - name: X-SESSION
          in: header
          description: session id
          required: true
          schema:
            type: string
          # This extension injects the session ID
          x-ces-session-context: $context.session_id

שיקולי אבטחה

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

  • זהות ההפעלה של הכלי: פעולות שמבוצעות על ידי כלי OpenAPI מופעלות באמצעות ההרשאות שניתנו לחשבון השירות של CX Agent Studio, ולא באמצעות ההרשאות הישירות של משתמש הקצה שמקיים אינטראקציה עם הסוכן.
  • סיכון גישה טרנזיטיבית: המשמעות היא שאם לחשבון השירות של CX Agent Studio יש הרשאות להפעלת פונקציות של Cloud Run, הכלי יכול להפעיל כל פונקציה שחשבון השירות יכול לגשת אליה, גם אם למשתמש הקצה אין גישה ישירה.

כדי לצמצם את הסיכונים הפוטנציאליים שקשורים להתנהגות הזו:

  1. שימוש בפרויקטים ייעודיים: מומלץ מאוד לפרוס אפליקציות של סוכנים בפרויקט ייעודי, בנפרד ממשאבים קריטיים אחרים או מפונקציות רגישות. הבידוד הזה מגביל את היקף ההרשאות שזמינות לחשבון השירות של CX Agent Studio.
  2. הטמעה של VPC Service Controls: שימוש ב-VPC Service Controls כדי להגדיר גבולות גזרה לשירותים רגישים. כך תוכלו לשלוט בגישה לשירותים כמו פונקציות Cloud Run ולמנוע קריאות לא רצויות מחשבון השירות של CX Agent Studio.
  3. הקפידו על הרשאות מינימליות: חשוב לוודא שלחשבון השירות של CX Agent Studio מוקצות רק ההרשאות והתפקידים המינימליים בניהול זהויות והרשאות גישה (IAM) שנדרשים לפונקציונליות המיועדת שלו.

אימות של API

אלה אפשרויות האימות שנתמכות כשמתקשרים עם API חיצוני:

אסימון מזהה של סוכן שירות

‫CX Agent Studio יכול ליצור אסימון מזהה באמצעות סוכן השירות של Customer Engagement Suite (בפורמט: service-{PROJECT_NUMBER}@gcp-sa-ces.iam.gserviceaccount.com). האסימון מתווסף לכותרת ההרשאה של HTTP כש-CX Agent Studio קורא ל-API חיצוני.

אם פונקציות Cloud Run ושירותי Cloud Run נמצאים באותו פרויקט כמו הסוכן, לא צריך הרשאות IAM נוספות כדי להפעיל אותם. אם הם נמצאים בפרויקטים שונים, אפשר להשתמש באסימון מזהה כדי לגשת לפונקציות של Cloud Run ולשירותים של Cloud Run אחרי שמקצים את התפקידים roles/cloudfunctions.invoker ו-roles/run.invoker לכתובת של סוכן השירות.

אימות באמצעות חשבון שירות

אפשר להשתמש בחשבונות שירות כדי לאמת בקשות של כלי לכל Google API שתומך בכך. מזינים את כתובת האימייל בחשבון השירות.

אם עדיין לא עשיתם זאת, צרו חשבון שירות.

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

למשתמש שמגדיר את הכלי לשימוש בחשבונות שירות צריכות להיות ההרשאות הבאות:

  • roles/iam.serviceAccountUser

כדי ש-Dialogflow CX יוכל ליצור אסימונים, לסוכן השירות של חבילת Customer Engagement Suite צריכות להיות ההרשאות הבאות:

  • roles/iam.serviceAccountTokenCreator

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

OAuth

מזינים את פרטי ה-OAuth של השירות שבו אתם משתמשים.

אם אתם משתמשים ב-OAuth בשביל שירות Google, אתם צריכים להגדיר את ה-OAuth בשביל השירות.

מפתח API

אתם יכולים להגדיר אימות של מפתח API על ידי ציון שם המפתח, מיקום הבקשה (כותרת או מחרוזת שאילתה) ומפתח ה-API, כך ש-CX Agent Studio יעביר את מפתח ה-API בבקשה. מספקים את מפתח ה-API באמצעות גרסת הסוד של Secret Manager.

אימות ב-Secret Manager

אתם יכולים לאחסן פרטי כניסה כסודות באמצעות Secret Manager. כדי לאמת את הכלי באמצעות סודות, צריך לבצע את השלבים הבאים:

  1. אם עדיין אין לכם סוד, צריך ליצור אותו.
  2. מעניקים לסוכן השירות Customer Engagement Suite Service Agent את התפקיד Secret Manager Secret Accessor (roles/secretmanager.secretAccessor) בסוד החדש.
  3. מעתיקים את פרטי הכניסה ללוח.
  4. מוסיפים גרסה חדשה של הסוד לסוד. מדביקים את פרטי הכניסה בתור ערך הסוד.
    • אין להוסיף תו מעבר לשורה בסוף.
  5. מעתיקים את השם של גרסת הסוד שהוספתם. פורמט השם הוא projects/{project_id}/secrets/{secret_id}/versions/{version_id}. משתמשים בגרסה הסודית הזו להגדרת הכלי.