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

מפתחות הצפנה בניהול הלקוח (CMEK)

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

אם אתם רוצים לשלוט במפתחות ההצפנה, אתם יכולים להשתמש במפתחות הצפנה בניהול הלקוח (CMEK) ב-Cloud KMS עם שירותים שמשולבים ב-CMEK, כולל Gemini Data Analytics. כשמשתמשים במפתחות של Cloud KMS, אפשר לשלוט ברמת ההגנה, במיקום, בלוח הזמנים של הרוטציה, בהרשאות השימוש והגישה ובגבולות הקריפטוגרפיים שלהם. בנוסף, באמצעות Cloud KMS תוכלו לצפות ביומני ביקורת ולשלוט במחזורי החיים של המפתחות. במקום ש-Google תהיה הבעלים של מפתחות ההצפנה (KEK) הסימטריים שמגינים על הנתונים שלכם ותנהל אותם, אתם שולטים במפתחות האלה ומנהלים אותם ב-Cloud KMS.

אחרי שתגדירו את המשאבים עם מפתחות CMEK, חוויית הגישה למשאבים של Gemini Data Analytics תהיה דומה לשימוש בהצפנת ברירת המחדל של Google. מידע נוסף על אפשרויות ההצפנה מופיע במאמר מפתחות הצפנה בניהול הלקוח (CMEK).

בדף הזה מוסבר איך להשתמש במפתחות הצפנה בניהול הלקוח (CMEK) כדי להגן על הנתונים שמשמשים את Conversational Analytics API. ‫Conversational Analytics API הוא מוצר בשירות Gemini Data Analytics‏ (geminidataanalytics.googleapis.com).

מפתחות CMEK למשאבים של Conversational Analytics API

כשמגדירים CMEK למשאב של Conversational Analytics API, מפתח Cloud KMS שצוין מצפין את הנתונים הרגישים במנוחה. אפשר להגדיר CMEK למשאבים של DataAgent ו-Conversation בנפרד.

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

מה מוגן באמצעות CMEK

מפתחות הצפנה בניהול הלקוח (CMEK) ל-Conversational Analytics API מגינים על הנתונים הבאים באחסון:

במשאבי DataAgent, כל תוכן הליבה של הלקוח בשדה data_analytics_agent מוגן. התוכן הזה כולל את השדות staging_context,‏ published_context ו-last_published_context, וגם את השדות system_instruction ו-example_queries.
במשאבים של Conversation, כל נתוני ההיסטוריה של ההודעות והמצבים מוגנים.

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

במשאבי DataAgent, הצפנת ברירת המחדל של Google מגינה על שדות של מטא-נתונים כמו name,‏ display_name,‏ description,‏ labels,‏ create_time,‏ update_time,‏ delete_time,‏ purge_time ו-kms_key.
במשאבי Conversation, הצפנת ברירת המחדל של Google מגינה על שדות של מטא-נתונים כמו name,‏ agents,‏ labels,‏ create_time,‏ last_used_time ו-kms_key.

מגבלות

אלה המגבלות של CMEK ב-Conversational Analytics API:

צריך להגדיר את CMEK כשיוצרים את המשאב. אי אפשר להוסיף או לשנות אותו במשאב קיים.
אין תמיכה במדיניות ארגונית של CMEK.
המיקום הנדרש של מפתח Cloud KMS תלוי בסוג המשאב ובמיקום שלו. באזור יחיד, המפתח צריך להיות באותו אזור שבו נמצא המשאב. במספר האזורים us או eu, מיקום המפתח של המשאבים DataAgent ו-Conversation שונה. מידע נוסף זמין במאמר דרישות לגבי מיקום המפתח.
אין תמיכה באזור global.
אפשר להשתמש רק במפתח CMEK אחד לכל פרויקט בכל אזור, לכל משאבי Conversation באותו פרויקט ובאותו אזור.

דרישות עיקריות לגבי מיקום

המיקום הנדרש של מפתח Cloud KMS תלוי בסוג המשאב שאתם מגינים עליו ובמיקום של המשאב הזה:

מיקום המשאב	מיקום המפתח של `DataAgent` משאבים	מיקום המפתח של `Conversation` משאבים
מספר אזורים (`us`)	`us`	`us-central1`
מספר אזורים (`eu`)	`europe`	`europe-west1`
אזור יחיד, כמו `us-east4`	אותו אזור שבו נמצא המשאב	אותו אזור שבו נמצא המשאב

משאבי DataAgent במיקום שכולל מספר אזורים מאוחסנים במיקום שצוין בשם המשאב, ולכן המפתח צריך להיות במיקום התואם של Cloud KMS שכולל מספר אזורים. במיקום us שכולל מספר אזורים, המיקום ב-Cloud KMS הוא גם us. במיקום eu שכולל מספר אזורים, המיקום ב-Cloud KMS הוא europe כי ל-Cloud KMS אין מיקום eu. מידע נוסף מופיע במאמר מיקומים ב-Cloud KMS.

משאבי Conversation במספר אזורים מאוחסנים באזור ספציפי בתוך מספר האזורים: us-central1 ל-us ו-europe-west1 ל-eu. המפתח חייב להיות באזור הזה. לדוגמה, כדי להגן על משאב Conversation בשם projects/PROJECT_ID/locations/us/conversations/CONVERSATION_ID, צריך להשתמש במפתח במיקום us-central1.

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

כדי להשתמש ב-CMEK עם Conversational Analytics API, צריך לבצע את השלבים הבאים:

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

הפעלת Gemini Data Analytics API

הפעלת Gemini for Google Cloud API

הפעלת Cloud Key Management Service API

טיפ: כשמפעילים API, יכול להיות שצריך לרענן את הדף במסוף Google Cloud כדי לוודא שהוא הופעל.
gcloud
ב-Google Cloud CLI, מריצים את הפקודות הבאות של gcloud services enable כדי להפעיל את Gemini Data Analytics API, את Gemini for Google Cloud API ואת Cloud Key Management Service API, בהתאמה:
gcloud services enable geminidataanalytics.googleapis.com --project=project_id gcloud services enable cloudaicompanion.googleapis.com --project=project_id gcloud services enable cloudkms.googleapis.com --project=project_id
בפקודות לדוגמה של ה-CLI של gcloud, מחליפים את project_id במזהה הפרויקט ב- Google Cloud .
יוצרים אוסף מפתחות ומפתח של Cloud KMS במיקום שנדרש למשאבים של Conversational Analytics API, כמו שמתואר בקטע דרישות לגבי מיקום המפתחות. מידע נוסף זמין במאמר יצירת מפתח.
יוצרים את סוכני השירות בניהול Google, שנקראים גם חשבונות שירות לכל מוצר ולכל פרויקט (P4SA), אם הם עדיין לא קיימים. סוכני השירות האלה נדרשים כדי לאפשר לשירותים שמעורבים בהגנה על המשאבים של Conversational Analytics API באמצעות CMEK לגשת למפתח Cloud KMS שלכם.

מריצים את פקודות ה-gcloud הבאות כדי ליצור את סוכני השירות:
```
gcloud beta services identity create --service=geminidataanalytics.googleapis.com --project PROJECT_ID
gcloud beta services identity create --service=cloudaicompanion.googleapis.com --project PROJECT_ID
```
מחליפים את PROJECT_ID במזהה הפרויקט ב- Google Cloud .
כדי לאפשר לשירות Gemini Data Analytics להשתמש במפתח Cloud KMS להצפנה ולפענוח של נתוני Conversational Analytics API, נותנים את התפקיד Cloud KMS CryptoKey Encrypter/Decrypter (roles/cloudkms.cryptoKeyEncrypterDecrypter) ב-Identity and Access Management (IAM) לשני סוכני השירות שיצרתם בשלב הקודם. אם אתם משתמשים ביותר ממפתח אחד – לדוגמה, מפתחות נפרדים למשאבים של DataAgent ו-Conversation באזור הגיאוגרפי שכולל מספר אזורים us או eu – צריך להקצות את התפקיד לכל מפתח.

נותנים את ההרשאה לסוכן השירות של Gemini Data Analytics:
```
gcloud kms keys add-iam-policy-binding KEY_NAME \
  --location KEY_LOCATION \
  --keyring KEY_RING_NAME \
  --member
serviceAccount:service-PROJECT_NUMBER@gcp-sa-geminidataanalytics. \
  --role roles/cloudkms.cryptoKeyEncrypterDecrypter \
  --project KMS_PROJECT_ID
```
נותנים את ההרשאה לסוכן השירות של Gemini for Google Cloud API:
```
gcloud kms keys add-iam-policy-binding KEY_NAME \
  --location KEY_LOCATION \
  --keyring KEY_RING_NAME \
  --member
serviceAccount:service-PROJECT_NUMBER@gcp-sa-cloudaicompanion. \
  --role roles/cloudkms.cryptoKeyEncrypterDecrypter \
  --project KMS_PROJECT_ID
```
בדוגמאות הקוד הקודמות, מחליפים את ערכי הדוגמה באופן הבא:
- ‫KEY_NAME: השם של מפתח Cloud KMS.
- ‫KEY_LOCATION: האזור של אוסף המפתחות (לדוגמה, us-east4).
- ‫KEY_RING_NAME: השם של אוסף המפתחות.
- ‫PROJECT_NUMBER: מספר הפרויקט ב- Google Cloud שבו אתם יוצרים משאבי API.
- ‫KMS_PROJECT_ID: מזהה הפרויקט שבו נוצר המפתח. הפרויקט הזה יכול להיות אותו פרויקט שבו אתם יוצרים משאבי API.

הגנה על משאבים באמצעות CMEK

בקטע הזה מוסבר איך להגן על משאב חדש של DataAgent או Conversation באמצעות CMEK, על ידי שימוש ב-API בארכיטקטורת REST כדי לציין מפתח Cloud KMS בשדה kms_key במהלך יצירת המשאב.

אפשר להפעיל את CMEK רק כשיוצרים משאב DataAgent או Conversation.

המיקום הנדרש של מפתח Cloud KMS תלוי בסוג ובמיקום של המשאב שעליו הוא מגן. מידע נוסף זמין במאמר דרישות לגבי מיקום המפתח.

הגנה על משאב ב-`DataAgent` באמצעות CMEK

כדי להגן על משאב DataAgent חדש באמצעות CMEK, צריך לציין מפתח Cloud KMS בשדה kms_key כשיוצרים את הסוכן לאינטראקציה עם נתונים.

Python SDK

בדוגמה הבאה מוסבר איך לציין מפתח Cloud KMS כשיוצרים משאב DataAgent באמצעות Python SDK. דוגמה לבקשת create מלאה מופיעה במאמר יצירת סוכן לאינטראקציה עם נתונים באמצעות Python SDK.

# Define the KMS key.
billing_project = "BILLING_PROJECT_ID"
key_ring = "KEY_RING_NAME"
key_name = "KEY_NAME"
key_project = "KMS_PROJECT_ID" # Project where the key was created
location = "LOCATION" # Location of the data agent
key_location = "KEY_LOCATION" # Location of your key ring

if key_project == "":
  key_project = billing_project
if key_location == "":
  key_location = location

kms_key_data_agent = f"projects/{key_project}/locations/{key_location}/keyRings/{key_ring}/cryptoKeys/{key_name}"

data_agent = geminidataanalytics.DataAgent()
data_agent.data_analytics_agent.published_context = published_context
data_agent.kms_key = kms_key_data_agent

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

‫BILLING_PROJECT_ID: מזהה הפרויקט לחיוב.
‫KEY_RING_NAME: השם של אוסף המפתחות ב-Cloud KMS.
‫KEY_NAME: השם של מפתח Cloud KMS.
‫KMS_PROJECT_ID: מזהה הפרויקט שבו נוצר המפתח. אם משאירים את השדה ריק, המערכת משתמשת ב-billing_project.
‫LOCATION: המיקום של סוכן הנתונים, לדוגמה us,‏ eu או us-east4.
‫KEY_LOCATION: המיקום של אוסף המפתחות. בשביל eu במספר אזורים, משתמשים ב-europe. בכל שאר המיקומים, צריך להשתמש באותו מיקום כמו של LOCATION. אם לא בוחרים מיקום, כברירת מחדל נבחר המיקום של סוכן לאינטראקציה עם נתונים, שמתאים לכל המיקומים חוץ מהמיקום eu במספר אזורים.

HTTP

בדוגמה הבאה מוסבר איך לציין מפתח Cloud KMS בגוף הבקשה כשיוצרים משאב DataAgent באמצעות HTTP ו-Python. דוגמה לבקשת create מלאה מופיעה במאמר יצירת סוכן לאינטראקציה עם נתונים באמצעות HTTP ו-Python.

# Define the KMS key.
key_ring = "KEY_RING_NAME"
key_name = "KEY_NAME"
key_project = "KMS_PROJECT_ID" # Project where the key was created
location = "LOCATION" # Location of the data agent
key_location = "KEY_LOCATION" # Location of your key ring

data_agent_payload = {
      "name": f"projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}",
      "description": "This is the description of data_agent_1.",
      # If using CMEK, include the kms_key field.
      "kms_key": f"projects/{key_project}/locations/{key_location}/keyRings/{key_ring}/cryptoKeys/{key_name}",
      "data_analytics_agent": {
          "published_context": {
              "datasource_references": looker_data_source,
              "system_instruction": system_instruction,
          }
      }
  }

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

‫KEY_RING_NAME: השם של אוסף המפתחות ב-Cloud KMS.
‫KEY_NAME: השם של מפתח Cloud KMS.
‫KMS_PROJECT_ID: מזהה הפרויקט שבו נוצר המפתח.
‫LOCATION: המיקום של סוכן הנתונים, לדוגמה us,‏ eu או us-east4.
‫KEY_LOCATION: המיקום של אוסף המפתחות. בשביל eu במספר אזורים, משתמשים ב-europe. בכל המיקומים האחרים, צריך להשתמש באותו מיקום כמו של הסוכן לאינטראקציה עם נתונים.

הגנה על משאב ב-`Conversation` באמצעות CMEK

כדי להגן על משאב Conversation חדש באמצעות CMEK, צריך לציין מפתח Cloud KMS בשדה kms_key כשיוצרים את השיחה.

Python SDK

בדוגמה הבאה מוסבר איך לציין מפתח Cloud KMS כשיוצרים משאב Conversation באמצעות Python SDK. דוגמה לבקשת create מלאה מופיעה במאמר יצירת סוכן לאינטראקציה עם נתונים באמצעות Python SDK.

# Define the KMS key.
billing_project = "BILLING_PROJECT_ID"
key_ring = "KEY_RING_NAME"
key_name = "KEY_NAME"
key_project = "KMS_PROJECT_ID" # Project where the key was created
location = "LOCATION" # Location of the conversation and data agent
key_location = "KEY_LOCATION" # Location of your key ring

if key_project == "":
  key_project = billing_project
if key_location == "":
  key_location = location

kms_key_conversation = f"projects/{key_project}/locations/{key_location}/keyRings/{key_ring}/cryptoKeys/{key_name}"

conversation = geminidataanalytics.Conversation()
conversation.agents = [f"projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}"]
conversation.kms_key = kms_key_conversation

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

‫BILLING_PROJECT_ID: מזהה הפרויקט לחיוב.
‫KEY_RING_NAME: השם של אוסף המפתחות ב-Cloud KMS.
‫KEY_NAME: השם של מפתח Cloud KMS.
‫KMS_PROJECT_ID: מזהה הפרויקט שבו נוצר המפתח. אם משאירים את השדה ריק, המערכת משתמשת ב-billing_project.
‫LOCATION: המיקום של השיחה ושל הסוכן לאינטראקציה עם נתונים, לדוגמה us,‏ eu או us-east4.
‫KEY_LOCATION: המיקום של אוסף המפתחות. בשביל us במספר אזורים, משתמשים ב-us-central1. בשביל eu במספר אזורים, משתמשים ב-europe-west1. לאזור יחיד, משתמשים באותו אזור כמו LOCATION. אם משאירים את השדה ריק, ברירת המחדל היא המיקום של השיחה, וזה עובד רק באזורים בודדים.

HTTP

בדוגמה הבאה מוסבר איך לציין מפתח Cloud KMS בגוף הבקשה כשיוצרים משאב Conversation באמצעות HTTP ו-Python. דוגמה לבקשת create מלאה מופיעה במאמר יצירת סוכן לאינטראקציה עם נתונים באמצעות HTTP ו-Python.

# Define the KMS key.
key_ring = "KEY_RING_NAME"
key_name = "KEY_NAME"
key_project = "KMS_PROJECT_ID" # Project where the key was created
location = "LOCATION" # Location of the conversation and data agent
key_location = "KEY_LOCATION" # Location of your key ring

conversation_payload = {
    "agents": [
        f"projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}"
    ],
    "name": f"projects/{billing_project}/locations/{location}/conversations/{conversation_id}",
    # If using CMEK, include the kms_key field.
    "kms_key": f"projects/{key_project}/locations/{key_location}/keyRings/{key_ring}/cryptoKeys/{key_name}"
}

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

‫KEY_RING_NAME: השם של אוסף המפתחות ב-Cloud KMS.
‫KEY_NAME: השם של מפתח Cloud KMS.
‫KMS_PROJECT_ID: מזהה הפרויקט שבו נוצר המפתח.
‫LOCATION: המיקום של השיחה ושל הסוכן לאינטראקציה עם נתונים, לדוגמה us,‏ eu או us-east4.
‫KEY_LOCATION: המיקום של אוסף המפתחות. בשביל us במספר אזורים, משתמשים ב-us-central1. בשביל eu במספר אזורים, משתמשים ב-europe-west1. אם אתם בוחרים אזור אחד, בחרו את האזור שבו מתנהלת השיחה.

פתרון בעיות

בקטע הזה מפורטות בעיות נפוצות ושיקולים חשובים כשמשתמשים ב-CMEK עם Conversational Analytics API.

שינויים במצב המפתח

אם גרסה של מפתח Cloud KMS שמגן על משאב של Conversational Analytics API לא זמינה, אתם מאבדים את הגישה לנתונים שמוצפנים באמצעות המפתח הזה. אם תנסו לגשת לנתונים מוגנים כשהמפתח לא זמין, למשל על ידי קריאת ההקשר של משאב DataAgent או גישה להיסטוריה של Conversation, הבקשה תיכשל. השגיאה שמוחזרת תלויה בסיבה לכך שהמפתח לא זמין:

אם גרסת המפתח מושבתת או מושמדת, הפעולה בדרך כלל נכשלת ומוצגת השגיאה FAILED_PRECONDITION.
אם תפקיד ה-IAM‏ cloudkms.cryptoKeyEncrypterDecrypter בוטל לסוכן השירות gcp-sa-geminidataanalytics או gcp-sa-cloudaicompanion, הפעולה בדרך כלל נכשלת עם השגיאה PERMISSION_DENIED או NOT_FOUND.

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

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

מכסות ב-Cloud KMS וב-Conversational Analytics API

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

פעולות הצפנה ופענוח באמצעות מפתחות CMEK משפיעות על המכסות של Cloud KMS בדרכים הבאות:

במפתחות CMEK של תוכנה שנוצרו ב-Cloud KMS, לא נעשה שימוש במכסה של Cloud KMS.
במפתחות CMEK חיצוניים (לפעמים נקראים מפתחות Cloud EKM), פעולות ההצפנה והפענוח נספרות במסגרת המכסות של Cloud EKM בפרויקט שמכיל את המפתח.

מידע נוסף מופיע במאמר מכסות ב-Cloud KMS.

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

מפתחות CMEK למשאבים של Conversational Analytics API

מה מוגן באמצעות CMEK

מגבלות

דרישות עיקריות לגבי מיקום

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

המסוף

gcloud

הגנה על משאבים באמצעות CMEK

הגנה על משאב ב-DataAgent באמצעות CMEK

Python SDK

HTTP

הגנה על משאב ב-Conversation באמצעות CMEK

Python SDK

HTTP

פתרון בעיות

שינויים במצב המפתח

מכסות ב-Cloud KMS וב-Conversational Analytics API

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

מפתחות הצפנה בניהול הלקוח (CMEK)

הגנה על משאב ב-`DataAgent` באמצעות CMEK

הגנה על משאב ב-`Conversation` באמצעות CMEK