Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

הקצאת התפקידים dataAgentOwner, ‏dataAgentEditor, ‏dataAgentUser ו-dataAgentViewer ברמת משאב הסוכן. כדי להימנע מהענקת הרשאות רחבות מדי, כדאי להגביל את ההרשאות של התפקידים האלה ברמת הפרויקט לאדמינים בלבד, כי הרשאות גישה ברמת הפרויקט מעניקות הרשאות לכל הסוכנים בפרויקט.

תפקיד	רמת ההרשאה הטיפוסית	הרשאות
סוכן ליצירת נתונים של Gemini לניתוח נתונים (`roles/geminidataanalytics.dataAgentCreator`) ההרשאה מאפשרת לחשבון משתמש ליצור משאבים חדשים של סוכני נתונים בפרויקט מסוים. כשחשבון משתמש יוצר סוכן, המערכת מקצה לו באופן אוטומטי את התפקיד `dataAgentOwner` עבור הסוכן הספציפי.	פרויקט	`geminidataanalytics.dataAgents.create` `geminidataanalytics.locations.chat`
הבעלים של סוכן הנתונים של Gemini Data Analytics (`roles/geminidataanalytics.dataAgentOwner`) התפקיד הזה נותן לישות שליטה מלאה במחזור החיים של כל סוכן בפרויקט, כולל שיתוף ומחיקה של סוכנים. התפקיד הזה מיועד לחשבונות משתמשים מהימנים שיכולים לנהל את שיתוף הסוכן. התפקיד הזה מקבל בירושה את כל ההרשאות מהתפקידים `dataAgentEditor`, `dataAgentUser` ו-`dataAgentViewer`. חשבון ראשי עם התפקיד הזה יכול לשתף ולמחוק סוכנים.	Agent או Project	`geminidataanalytics.dataAgents.list` `geminidataanalytics.dataAgents.get` `geminidataanalytics.dataAgents.chat` `geminidataanalytics.dataAgents.update` `geminidataanalytics.dataAgents.delete` `geminidataanalytics.dataAgents.getIamPolicy` `geminidataanalytics.dataAgents.setIamPolicy`
עריכה ב-Gemini Data Analytics (`roles/geminidataanalytics.dataAgentEditor`) נותן הרשאה לשנות ולנהל הגדרות קיימות של סוכנים. התפקיד הזה מקבל בירושה את כל ההרשאות מהתפקידים `dataAgentUser` ו-`dataAgentViewer`.	Agent או Project	`geminidataanalytics.dataAgents.list` `geminidataanalytics.dataAgents.get` `geminidataanalytics.dataAgents.chat` `geminidataanalytics.dataAgents.update`
משתמש בסוכן נתונים של Gemini Data Analytics (`roles/geminidataanalytics.dataAgentUser`) ההרשאה מאפשרת להתכתב בצ'אט עם הסוכנים הספציפיים שלחשבון המשתמש ניתנה גישה אליהם. התפקיד הזה מקבל בירושה את כל ההרשאות מהתפקיד `dataAgentViewer`.	Agent או Project	`geminidataanalytics.dataAgents.list` `geminidataanalytics.dataAgents.get` `geminidataanalytics.dataAgents.chat`
צפייה בנתונים של סוכן ניתוח הנתונים של Gemini (`roles/geminidataanalytics.dataAgentViewer`) התפקיד הזה מעניק לחשבון משתמש הרשאת קריאה בלבד להצגת רשימה של תצורות סוכנים ולצפייה בהן. התפקיד הזה לא מאפשר צ'אט עם נציגים.	Agent או Project	`geminidataanalytics.dataAgents.list` `geminidataanalytics.dataAgents.get`
משתמש ב-Gemini Data Analytics ללא שמירת מצב (`roles/geminidataanalytics.dataAgentStatelessUser`) ההרשאה מאפשרת לישות (principal) לקרוא ל-Chat API במצב חסר מצב (stateless). בצ'אט בלי שמירת מצב, ההקשר מסופק ישירות בבקשה במקום להישמר באופן מפורש בהגדרת הסוכן במהלך היצירה.	פרויקט	`geminidataanalytics.locations.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@example.com.
service_account_email: כתובת האימייל של חשבון השירות, למשל test-sa@example.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@example.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
)