בקרת גישה ל-Conversational Analytics API באמצעות IAM

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

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

כדי לקבל את ההרשאות שנדרשות להקצאת תפקידי IAM ל-Conversational Analytics API, צריך לבקש מהאדמין להקצות לכם ב-IAM את התפקיד Project IAM Admin (roles/resourcemanager.projectIamAdmin) בפרויקט שבו מופעל Conversational Analytics API. להסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.

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

סקירה כללית של תפקידים ב-IAM של Conversational Analytics API

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

אתם יכולים להקצות תפקידים ברמת הפרויקט כדי לספק הרשאות לכל הסוכנים בפרויקט. כדי לשלוט בגישה לסוכן ספציפי, בעלי הסוכן (גורם ראשי עם התפקיד בעלים של סוכן נתונים של Gemini Data Analytics) יכולים לשנות את מדיניות ה-IAM של הסוכן הזה באופן פרוגרמטי.

חשוב: תפקידי IAM ב-Conversational Analytics API שולטים בגישה לסוכנים ולהגדרות שלהם, ולא למקורות הנתונים הבסיסיים. כשמשתמש מקיים אינטראקציה עם סוכן, ה-API מריץ שאילתות במקור הנתונים המקושר (כמו Looker או BigQuery) באמצעות פרטי הכניסה של המשתמש. לכן, כדי שהמשתמש יוכל לשוחח בצ'אט עם נציג, הוא צריך לקבל את ההרשאות הבאות:

תפקיד IAM מתאים ב-API של ניתוח נתוני השיחות כדי לגשת לסוכן
הרשאות מספיקות במקור הנתונים (למשל, ב-Looker או ב-BigQuery) כדי לגשת לנתונים שעליהם מתבצעת השאילתה

הדיאגרמה הבאה מציגה כיצד בעלים של Agent יכול לנהל גישה ל-Agent ספציפי:

הבעלים של הסוכן מעניק למשתמשים אחרים את התפקידים 'עורך סוכן נתונים' ו'משתמש בסוכן נתונים'.

בתרחיש הזה, מנתח נתונים בכיר עם התפקיד יוצר סוכני נתונים של Gemini לניתוח נתונים יוצר סוכן. כשמשתמש יוצר סוכן, הוא מקבל אוטומטית את התפקיד בעלים של סוכן נתונים של Gemini Data Analytics עבור הסוכן הזה. האנליסט הראשי של הנתונים הוא הבעלים של הסוכן, והוא מנהל את הגישה לסוכן על ידי הגדרת מדיניות IAM שלו. הוא מקצה לחברי הצוות את התפקידים הבאים:

עורך של סוכן הנתונים של Gemini Data Analytics: הבעלים של הסוכן מעניק את התפקיד הזה למנתחי נתונים מתחילים. התפקיד הזה מאפשר לאנליסטים מתחילים לערוך את ההגדרות של הסוכן ולנהל איתו שיחה.
משתמש סוכן נתונים של Gemini Data Analytics: הבעלים של הסוכן מעניק את התפקיד הזה לחברי צוות שלא צריכים להיות בעלי הרשאה לערוך את ההגדרות של הסוכן. התפקיד הזה מאפשר לחברי הצוות לשוחח עם הסוכן.

התפקידים הנדרשים למשימות משתמש נפוצות

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

יצירת סוכני נתונים חדשים: מקצים את התפקיד Gemini Data Analytics Data Agent Creator למשתמשים שאחראים ליצירת סוכני נתונים חדשים בפרויקט.
שיתוף סוכנים: מקצים את התפקיד בעלים של סוכן נתונים של Gemini Data Analytics למשתמשים שצריכים לשתף סוכנים עם גורמים אחרים על ידי ניהול הרשאות הסוכנים.
ניהול הרשאות של סוכנים: מקצים את התפקיד בעלים של סוכן Gemini לניתוח נתונים למשתמשים שצריכים לשתף סוכנים עם משתמשים אחרים באמצעות ניהול הרשאות גישה לסוכנים, או שצריכים את רמת השליטה הגבוהה ביותר בסוכן, כולל היכולת למחוק סוכנים. כשמשתמש יוצר סוכן, המערכת מקצה לו באופן אוטומטי את התפקיד הזה עבור הסוכן הספציפי.
עריכת הגדרות הסוכן: מקצים את התפקיד עורך של סוכן נתונים של Gemini Data Analytics למשתמשים שמשנים את ההגדרות של סוכן, כמו ההקשר או מיפוי מקורות הנתונים. למשתמשים האלה אין הרשאות לשתף או למחוק את הסוכן.
צ'אט עם נציגים: מקצים את התפקיד משתמש בסוכן נתונים של Gemini Data Analytics למשתמשים או לאפליקציות שמבצעים אינטראקציה עם סוכנים בעיקר על ידי הצגת שאלות וקבלת תשובות.
צפייה בהגדרות של סוכנים: מקצים את התפקיד Gemini Data Analytics Data Agent Viewer למשתמשים שצריכים גישה לקריאה בלבד כדי להציג את הגדרות הסוכן.
שיחה באמצעות הקשר מוטבע: מקצים את התפקיד Gemini Data Analytics Stateless Chat User למשתמשים או לאפליקציות שמבצעים אינטראקציה עם ה-API במצב חסר מצב (stateless), שבו המשתמש מספק את כל ההקשר של השיחה בכל בקשה.
שאילתות על נתונים באמצעות שפה טבעית: מקצים את התפקיד משתמש בשאילתות של ניתוח נתונים ב-Gemini למשתמשים או לאפליקציות שצריכים להשתמש בשפה טבעית כדי לשלוח שאילתות לנתונים ולבנות אפליקציות לנתונים. התפקיד הזה רלוונטי רק למסדי נתונים בענן, כלומר ל-AlloyDB, ל-GoogleSQL ל-Spanner, ל-Cloud SQL ול-Cloud SQL ל-PostgreSQL.

תפקידים מוגדרים מראש ל-Conversational Analytics API

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

תפקיד	הרשאות
Gemini Data Analytics Data Agent Creator (`roles/geminidataanalytics.dataAgentCreator`) מעניקה לחשבון משתמש הרשאה ליצור משאבים חדשים של סוכני נתונים בפרויקט ספציפי. כשחשבון משתמש יוצר סוכן, המערכת מקצה לו באופן אוטומטי את התפקיד `dataAgentOwner` עבור הסוכן הספציפי.	`geminidataanalytics.dataAgents.create`
הבעלים של סוכן הנתונים של Gemini Data Analytics (`roles/geminidataanalytics.dataAgentOwner`) התפקיד הזה נותן לישות שליטה מלאה במחזור החיים של כל סוכן בפרויקט, כולל שיתוף ומחיקה של סוכנים. התפקיד הזה מיועד לחשבונות משתמשים מהימנים שיכולים לנהל את השיתוף של הסוכנים. התפקיד הזה מקבל בירושה את כל ההרשאות מהתפקידים `dataAgentEditor`, `dataAgentUser` ו-`dataAgentViewer`. חשבון ראשי עם התפקיד הזה יכול לשתף ולמחוק סוכנים.	`geminidataanalytics.dataAgents.list` `geminidataanalytics.dataAgents.get` `geminidataanalytics.dataAgents.chat` `geminidataanalytics.dataAgents.update` `geminidataanalytics.dataAgents.delete` `geminidataanalytics.dataAgents.getIamPolicy` `geminidataanalytics.dataAgents.setIamPolicy`
עריכה ב-Gemini Data Analytics Data Agent (`roles/geminidataanalytics.dataAgentEditor`) נותן הרשאה לשנות ולנהל הגדרות קיימות של סוכנים. התפקיד הזה מקבל בירושה את כל ההרשאות מהתפקידים `dataAgentUser` ו-`dataAgentViewer`.	`geminidataanalytics.dataAgents.list` `geminidataanalytics.dataAgents.get` `geminidataanalytics.dataAgents.chat` `geminidataanalytics.dataAgents.update`
משתמש ב-Gemini Data Analytics Data Agent (`roles/geminidataanalytics.dataAgentUser`) ההרשאה מאפשרת להתכתב בצ'אט עם הסוכנים הספציפיים שלחשבון המשתמש ניתנה גישה אליהם. התפקיד הזה מקבל בירושה את כל ההרשאות מהתפקיד `dataAgentViewer`.	`geminidataanalytics.dataAgents.list` `geminidataanalytics.dataAgents.get` `geminidataanalytics.dataAgents.chat`
צפייה בנתונים של Gemini Data Analytics Data Agent (`roles/geminidataanalytics.dataAgentViewer`) התפקיד הזה מעניק לחשבון משתמש הרשאת קריאה בלבד להצגת רשימה של הגדרות הסוכן ולצפייה בהן. התפקיד הזה לא מאפשר צ'אט עם נציגים.	`geminidataanalytics.dataAgents.list` `geminidataanalytics.dataAgents.get`
משתמש ב-Gemini Data Analytics ללא שמירת מצב (`roles/geminidataanalytics.dataAgentStatelessUser`) ההרשאה מאפשרת לגורם ראשי לקרוא ל-Chat API במצב חסר מצב (stateless). בצ'אט בלי שמירת מצב, ההקשר מסופק ישירות בבקשה במקום להישמר באופן מפורש בהגדרת הסוכן במהלך היצירה.	`geminidataanalytics.chat`
משתמש עם הרשאה לשאילתת נתונים ב-Gemini Data Analytics (`roles/geminidataanalytics.queryDataUser`) נותנת למשתמש הרשאה להשתמש בשפה טבעית כדי להריץ שאילתות על נתונים ולבנות אפליקציות נתונים באמצעות QueryData API. התפקידים האלה חלים רק על מסדי נתונים בענן, כלומר על AlloyDB,‏ GoogleSQL ל-Spanner,‏ Cloud SQL ו-Cloud SQL ל-PostgreSQL.	`geminidataanalytics.locations.queryData`

מתן תפקידים ב-IAM

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

תפקידי ה-IAM המוגדרים מראש עבור Conversational Analytics API הם חלק מהשירות geminidataanalytics. השמות הטכניים של התפקידים האלה פועלים לפי התבנית roles/geminidataanalytics.ROLE_NAME. במסוף Google Cloud , אפשר לסנן לפי השירות Gemini Data Analytics כדי למצוא את התפקידים האלה.

הקצאת תפקידים לכל הסוכנים בפרויקט

משתמשים במסוף Google Cloud או ב-Google Cloud CLI כדי להקצות תפקידים לפרויקט שלם.

console

כדי להקצות תפקיד לישות מורשית במסוף Google Cloud :

נכנסים לדף IAM במסוף Google Cloud .

כניסה לדף IAM
לוחצים על הענקת גישה.
בשדה New principals, מזינים את כתובת האימייל של המשתמש, הקבוצה או חשבון השירות.
בתפריט בחירת תפקיד, מסננים לפי Gemini Data Analytics כדי לראות את התפקידים הזמינים ב-IAM עבור Conversational Analytics API.
בוחרים את התפקיד המתאים, כמו Gemini Data Analytics Data Agent User.
לוחצים על Save.

gcloud

כדי להעניק תפקידים באמצעות ה-CLI של gcloud, מבצעים את השלבים הבאים:

נכנסים לחשבון Google Cloud ומגדירים את הפרויקט:

gcloud auth login
gcloud config set project project_id

אופציונלי: כדי לפרט את תפקידי ה-IAM של Conversational Analytics API שאפשר להקצות לפרויקט, משתמשים בפקודה gcloud iam list-grantable-roles באופן הבא:

gcloud iam list-grantable-roles //cloudresourcemanager.googleapis.com/projects/project_id --filter "geminidataanalytics"

כדי להקצות תפקיד לישות מורשית, משתמשים בפקודה gcloud projects add-iam-policy-binding.

כדי להקצות תפקיד למשתמש, משתמשים בפקודה הבאה:

gcloud projects add-iam-policy-binding project_id --member='user:user_email' --role='roles/gda_grantable_role'

כדי להקצות תפקיד לחשבון שירות, משתמשים בפקודה הבאה:

gcloud projects add-iam-policy-binding project_id --member='serviceAccount:service_account_email' --role='roles/gda_grantable_role'

בהוראות הקודמות, מחליפים את הערכים לדוגמה באופן הבא:

‫project_id: מזהה הפרויקט ב- Google Cloud .
‫user_email: כתובת האימייל של המשתמש, למשל test-user@gmail.com.
service_account_email: כתובת האימייל של חשבון השירות, למשל test-proj@example.domain.com.
‫gda_grantable_role: תפקיד ה-IAM הספציפי של Conversational Analytics API שרוצים להעניק, כמו geminidataanalytics.dataAgentCreator.

איך נותנים תפקידים לסוכן ספציפי

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

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

HTTP

כדי לקבל את המדיניות הקיימת של סוכן, שולחים בקשת POST לנקודת הקצה :getIamPolicy עם גוף הבקשה הבא:

{
  "resource": "projects/PROJECT_ID/locations/global/dataAgents/AGENT_ID"
}

כדי להגדיר את המדיניות של סוכן, שולחים בקשת POST לנקודת הקצה :setIamPolicy עם גוף הבקשה הבא:

{
  "policy": {
    "bindings": [
      {
        "role": "ROLE",
        "members": [
          "user:EMAIL"
        ]
      }
    ]
  }
}

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

‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
‫AGENT_ID: המזהה של סוכן הנתונים שעבורו רוצים לקבל או להגדיר את המדיניות.
‫ROLE: התפקיד שרוצים להקצות, למשל roles/geminidataanalytics.dataAgentUser.
‫EMAIL: כתובת האימייל של המשתמש, למשל test-user@gmail.com.

דוגמאות מלאות מופיעות במאמרים קבלת מדיניות IAM לסוכן נתונים והגדרת מדיניות IAM לסוכן נתונים.

Python SDK

כדי לקבל את המדיניות הקיימת של סוכן, משתמשים ב-method ‏get_iam_policy, כמו בדוגמה הבאה של בקשה:

resource = "projects/PROJECT_ID/locations/global/dataAgents/AGENT_ID"
request = iam_policy_pb2.GetIamPolicyRequest(
            resource=resource,
        )

כדי להגדיר את המדיניות של סוכן, משתמשים ב-method ‏set_iam_policy, כמו בדוגמה הבאה של בקשה:

resource = "projects/PROJECT_ID/locations/global/dataAgents/AGENT_ID"
policy = policy_pb2.Policy(
    bindings=[
        policy_pb2.Binding(
            role="ROLE",
            members=["user:EMAIL"]
        )
    ]
)
request = iam_policy_pb2.SetIamPolicyRequest(
    resource=resource,
    policy=policy
)