יצירת מחבר בהתאמה אישית

בדף הזה מוסבר איך ליצור מחבר בהתאמה אישית.

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

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

• איך בודקים אם החיוב מופעל בפרויקט Google Cloud

• מתקינים ומפעילים את ה-CLI של gcloud. מוודאים שהאימות שלו בוצע בפרויקט.

• מתקינים את ספריות Python הנדרשות:

  pip install google-cloud-discoveryengine requests
  

• מקבלים גישת אדמין ל-Discovery Engine עבור הפרויקט Google Cloud .

• מקבלים פרטי גישה למקור הנתונים של הצד השלישי (כמו מפתחות API או אימות מסד נתונים).

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

הערה: אפשר להגדיר מחברים מותאמים אישית לממשקי API שזמינים בשבע שפות שונות. במסמכי התיעוד האלה אנחנו משתמשים ב-Python בכל דוגמאות הקוד, אבל הקריאות ל-API והלוגיקה הבסיסית זהים בכל שפה נתמכת. מידע נוסף על שפות נתמכות וספריות לקוח זמין במאמר ספריות לקוח של Gemini Enterprise.

יצירת מחבר בסיסי

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

אחזור נתונים

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

Python

    from typing import List
    import requests

    def fetch_posts(base_url: str, per_page: int = 15) -> List[dict]:
        #Fetch all posts from the given site.#
        url = base_url.rstrip("/") + "/wp-json/wp/v2/posts"
        posts: List[dict] = []
        page = 1
        while True:
            resp = requests.get(
                url,
                params={"page": page, "per_page": per_page},
                # headers={"Authorization": "Bearer YOUR_API_KEY"}, # Add auth if needed
            )
            resp.raise_for_status()
            batch = resp.json()
            posts.extend(batch)
            if len(batch) < per_page:
                break
            page += 1
        return posts

טרנספורמציה של נתונים

כדי להמיר את נתוני המקור לפורמט המסמך של Discovery Engine, צריך לבנות אותם כמו בדוגמה הבאה של מטען ייעודי (payload). אפשר לכלול כמה צמדי מפתח/ערך שרוצים. לדוגמה, אפשר לכלול את התוכן המלא כדי לבצע חיפוש מקיף. אפשר גם לכלול שדות מובנים לחיפוש עם היבטים, או שילוב של שניהם.

Python

    from typing import List
    import json
    from google.cloud import discoveryengine_v1 as discoveryengine

    def convert_posts_to_documents(posts: List[dict]) -> List[discoveryengine.Document]:
        # Convert WP posts into Discovery Engine Document messages.
        docs: List[discoveryengine.Document] = []
        for post in posts:
            payload = {
                "title": post.get("title", {}).get("rendered"),
                "body": post.get("content", {}).get("rendered"),
                "url": post.get("link"),
                "author": post.get("author"),
                "categories": post.get("categories"),
                "tags": post.get("tags"),
                "date": post.get("date"),
            }
            doc = discoveryengine.Document(
                id=str(post["id"]),
                json_data=json.dumps(payload),
            )
            docs.append(doc)
        return docs

אחזור או יצירה של מאגר זהויות

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

Python

    from google.cloud import discoveryengine_v1 as discoveryengine

    def get_or_create_ims_data_store(
        project_id: str,
        location: str,
        identity_mapping_store_id: str,
    ) -> discoveryengine.DataStore:
      """Get or create a DataStore."""
      # Initialize the client
      client_ims = discoveryengine.IdentityMappingStoreServiceClient()
      # Construct the parent resource name
      parent_ims = client_ims.location_path(project=project_id, location=location)

      try:
        # Create the request object
        name = f"projects/{project_id}/locations/{location}/identityMappingStores/{identity_mapping_store_id}"
        request = discoveryengine.GetIdentityMappingStoreRequest(
            name=name,
        )
        return client_ims.get_identity_mapping_store(request=request)
      except:
        # Create the IdentityMappingStore object (it can be empty for basic creation)
        identity_mapping_store = discoveryengine.IdentityMappingStore()
        # Create the request object
        request = discoveryengine.CreateIdentityMappingStoreRequest(
            parent=parent_ims,
            identity_mapping_store=identity_mapping_store,
            identity_mapping_store_id=identity_mapping_store_id,
        )
        return client_ims.create_identity_mapping_store(request=request)

הפונקציה get_or_create_ims_data_store משתמשת במשתני המפתח הבאים:

• ‫project_id: מזהה הפרויקט ב- Google Cloud .
• ‫location: Google Cloud המיקום של מאגר מיפוי הזהויות.
• ‫identity_mapping_store_id: מזהה ייחודי של מאגר הזהויות.
• ‫client_ims: מופע של discoveryengine.IdentityMappingStoreServiceClient שמשמש לאינטראקציה עם Identity Store API.
• ‫parent_ims: שם המשאב של מיקום האב, שנוצר באמצעות client_ims.location_path.
• ‫name: שם המשאב המלא של מאגר מיפוי הזהויות, שמשמש ל-GetIdentityMappingStoreRequest.

העברה של מיפוי הזהויות למאגר הזהויות

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

Python

Python

from google.cloud import discoveryengine_v1 as discoveryengine

def load_ims_data(
    ims_store: discoveryengine.DataStore,
    id_mapping_data: list[discoveryengine.IdentityMappingEntry],
) -> discoveryengine.DataStore:
  """Get the IMS data store."""
  # Initialize the client
  client_ims = discoveryengine.IdentityMappingStoreServiceClient()

  #  Create the InlineSource object
  inline_source = discoveryengine.ImportIdentityMappingsRequest.InlineSource(
      identity_mapping_entries=id_mapping_data
  )

  # Create the main request object
  request_ims = discoveryengine.ImportIdentityMappingsRequest(
      identity_mapping_store=ims_store.name,
      inline_source=inline_source,
  )

  try:
    # Create the InlineSource object, which holds your list of entries
    operation = client_ims.import_identity_mappings(
        request=request_ims,
    )
    result = operation.result()
    return result

  except Exception as e:
    print(f"IMS Load Error: {e}")
    return None

הפונקציה load_ims_data משתמשת במשתני המפתח הבאים:

• ‫ims_store: אובייקט discoveryengine.DataStore שמייצג את מאגר מיפוי הזהויות שאליו ייטענו הנתונים.
• ‫id_mapping_data: רשימה של אובייקטים מסוג discoveryengine.IdentityMappingEntry, שכל אחד מהם מכיל זהות חיצונית ואת מזהה המשתמש או הקבוצה התואם.
• ‫result: ערך ההחזרה מסוג discoveryengine.DataStore.

יצירת מאגר נתונים

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

Python

from google.cloud import discoveryengine_v1 as discoveryengine

def get_or_create_data_store(
    project_id: str,
    location: str,
    display_name: str,
    data_store_id: str,
    identity_mapping_store: str,
) -> discoveryengine.DataStore:
  """Get or create a DataStore."""
  client = discoveryengine.DataStoreServiceClient()
  ds_name = client.data_store_path(project_id, location, data_store_id)
  try:
    result = client.get_data_store(request={"name": ds_name})
    return result
  except:
    parent = client.collection_path(project_id, location, "default_collection")
    operation = client.create_data_store(
        request={
            "parent": parent,
            "data_store": discoveryengine.DataStore(
                display_name=display_name,
                acl_enabled=True,
                industry_vertical=discoveryengine.IndustryVertical.GENERIC,
                identity_mapping_store=identity_mapping_store,
            ),
            "data_store_id": data_store_id,
        }
    )
    result = operation.result()
    return result

הפונקציה get_or_create_data_store משתמשת במשתני המפתח הבאים:

• ‫project_id: מזהה הפרויקט ב- Google Cloud .
• ‫location: המיקום של מאגר הנתונים Google Cloud .
• ‫display_name: השם המוצג של מאגר הנתונים שקריא לאנשים.
• ‫data_store_id: מזהה ייחודי של מאגר הנתונים.
• ‫identity_mapping_store: שם המשאב של מאגר מיפוי הזהויות לקשירה.
• ‫result: ערך ההחזרה מסוג discoveryengine.DataStore.

העלאת מסמכים בתוך השורה

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

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

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

Python

    from typing import List
    from google.cloud import discoveryengine_v1 as discoveryengine

    def upload_documents_inline(
        project_id: str,
        location: str,
        data_store_id: str,
        branch_id: str,
        documents: List[discoveryengine.Document],
    ) -> discoveryengine.ImportDocumentsMetadata:
        """Inline import of Document messages."""
        client = discoveryengine.DocumentServiceClient()
        parent = client.branch_path(
            project=project_id,
            location=location,
            data_store=data_store_id,
            branch=branch_id,
        )
        request = discoveryengine.ImportDocumentsRequest(
            parent=parent,
            inline_source=discoveryengine.ImportDocumentsRequest.InlineSource(
                documents=documents,
            ),
        )
        operation = client.import_documents(request=request)
        operation.result()
        result = operation.metadata
        return result

הפונקציה upload_documents_inline משתמשת במשתנים העיקריים הבאים:

• ‫project_id: מזהה הפרויקט ב- Google Cloud .
• ‫location: המיקום של מאגר הנתונים Google Cloud .
• ‫data_store_id: המזהה של מאגר הנתונים.
• ‫branch_id: המזהה של הענף במאגר הנתונים (בדרך כלל '0').
• ‫documents: רשימה של אובייקטים מסוג discoveryengine.Document להעלאה.
• ‫result: ערך ההחזרה של discoveryengine.ImportDocumentsMetadata.

השדה uri באובייקט discoveryengine.Document משמש להפניה למקור התוכן שנקלט, כבייטים גולמיים או כ-URI ב- Google Cloud Storage. הכתובת הזו שונה מכתובת ה-URI של תוכן המקור של הצד השלישי. צריך להגדיר את ה-URI של תוכן המקור של הצד השלישי כשדה במטען הייעודי (payload) של מסמך json_data. לדוגמה, בפונקציה convert_posts_to_documents, השדה url במטען הייעודי (payload) משמש למטרה הזו.

אימות המחבר

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

Python

    from google.cloud import discoveryengine_v1 as discoveryengine
    from google.api_core import exceptions as gcp_exceptions

    SITE = "https://altostrat.com"
    PROJECT_ID = "ucs-3p-connectors-testing"
    LOCATION = "global"
    IDENTITY_MAPPING_STORE_ID = "your-unique-ims-id17" # A unique ID for your new store
    DATA_STORE_ID = "my-acl-ds-id1"
    BRANCH_ID = "0"

    posts = fetch_posts(SITE)
    docs = convert_posts_to_documents(posts)
    print(f"Fetched {len(posts)} posts and converted to {len(docs)} documents.")

    try:
      # Step #1: Retrieve an existing identity mapping store or create a new identity mapping store
      ims_store = get_or_create_ims_data_store(PROJECT_ID, LOCATION, IDENTITY_MAPPING_STORE_ID)
      print(f"STEP #1: IMS Store Retrieval/Creation: {ims_store}")

      RAW_IDENTITY_MAPPING_DATA = [
          discoveryengine.IdentityMappingEntry(
              external_identity="external_id_1",
              user_id="[e-mail]",
          ),
          discoveryengine.IdentityMappingEntry(
              external_identity="external_id_2",
              user_id="[e-mail]",
          ),
          discoveryengine.IdentityMappingEntry(
              external_identity="external_id_2",
              group_id="[e-mail]",
          )
      ]

      # Step #2: Load IMS Data
      response = load_ims_data(ims_store, RAW_IDENTITY_MAPPING_DATA)
      print(
          "\nStep #2: Load Data in IMS Store successful.", response
      )

      # Step #3: Create Entity Data Store & Bind IMS Data Store
      data_store =  get_or_create_data_store(PROJECT_ID, LOCATION, "my-acl-datastore", DATA_STORE_ID, ims_store.name)
      print("\nStep #3: Entity Data Store Create Result: ", data_store)

      metadata = upload_documents_inline(
          PROJECT_ID, LOCATION, DATA_STORE_ID, BRANCH_ID, docs
      )
      print(f"Uploaded {metadata.success_count} documents inline.")

    except gcp_exceptions.GoogleAPICallError as e:
      print(f"\n--- API Call Failed ---")
      print(f"Server Error Message: {e.message}")
      print(f"Status Code: {e.code}")

    except Exception as e:
      print(f"An error occurred: {e}")

מוודאים שקוד המחבר משתמש במשתני המפתח הבאים:

• ‫SITE: כתובת ה-URL הבסיסית של מקור הנתונים של הצד השלישי.
• ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
• ‫LOCATION: Google Cloud המיקום של המשאבים.
• ‫IDENTITY_MAPPING_STORE_ID: מזהה ייחודי של מאגר מיפוי הזהויות.
• ‫DATA_STORE_ID: מזהה ייחודי של מאגר הנתונים.
• ‫BRANCH_ID: המזהה של הענף במאגר הנתונים.
• ‫posts: מאחסן את הפוסטים שאוחזרו ממקור צד שלישי.
• ‫docs: מאחסן את המסמכים שהומרו בפורמט discoveryengine.Document.
• ‫ims_store: אובייקט discoveryengine.DataStore שאוחזר או נוצר למיפוי זהויות.
• ‫RAW_IDENTITY_MAPPING_DATA: רשימה של אובייקטים מסוג discoveryengine.IdentityMappingEntry.

הפלט אמור להיראות כך:

מעטפת

  Fetched 20 posts and converted to 20 documents.
  STEP #1: IMS Store Retrieval/Creation: "projects/ <Project Number>/locations/global/identityMappingStores/your-unique-ims-id17"
  Step #2: Load Data in IMS Store successful.
  Step #3: Entity Data Store Create Result: "projects/ <Project Number>/locations/global/collections/default_collection/dataStores/my-acl-ds-id1"
  display_name: "my-acl-datastore"
  industry_vertical: GENERIC
  create_time {
    seconds: 1760906997
    nanos: 192641000
  }
  default_schema_id: "default_schema"
  acl_enabled: true
  identity_mapping_store: "projects/ <Project Number>/locations/global/identityMappingStores/your-unique-ims-id17".
  Uploaded 20 documents inline.

בשלב הזה אפשר גם לראות את מאגר הנתונים במסוף Google Google Cloud :

מאגר נתונים של מחבר מותאם אישית.

כשמבצעים חיפוש, המערכת משתמשת בשדות מתוך המטען הייעודי (payload) לחיפוש, ובשדה ה-URI של המטען הייעודי לציטוטים. שלושת שדות המאפיינים העיקריים ש-Gemini Enterprise מזהה הם title,‏ description ו-uri. לשדות המסמך המתאימים יכולים להיות שמות שונים, ואפשר למפות אותם באמצעות האפשרות Schema (סכימה) -> Edit (עריכה) במסוף Google Cloud .

יצירת מחבר באמצעות Google Cloud העלאה לאחסון

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

המרת מסמכים ל-JSONL

כדי להכין מסמכים לייבוא בכמות גדולה ל-Discovery Engine, צריך להמיר אותם לפורמט JSON Lines.

Python

    from typing import List
    from google.cloud import discoveryengine_v1 as discoveryengine

    def convert_documents_to_jsonl(
        documents: List[discoveryengine.Document],
    ) -> str:
        """Serialize Document messages to JSONL."""
        return "\n".join(
            discoveryengine.Document.to_json(doc, indent=None)
            for doc in documents
        ) + "\n"

הפונקציה convert_documents_to_jsonl משתמשת במשתנה הבא:

• ‫documents: רשימה של אובייקטים מסוג discoveryengine.Document להמרה.

העלאה ל Google Cloud אחסון

כדי לאפשר ייבוא יעיל של נתונים בכמות גדולה, צריך להכין את הנתונים ב- Google Cloud Storage.

Python

    from google.cloud import storage

    def upload_jsonl_to_gcs(jsonl: str, bucket_name: str, blob_name: str) -> str:
        """Upload JSONL content to Google Cloud Storage."""
        client = storage.Client()
        bucket = client.bucket(bucket_name)
        blob = bucket.blob(blob_name)
        blob.upload_from_string(jsonl, content_type="application/json")
        return f"gs://{bucket_name}/{blob_name}"

הפונקציה upload_jsonl_to_gcs משתמשת במשתני המפתח הבאים:

• ‫jsonl: תוכן המחרוזת בפורמט JSONL שרוצים להעלות.
• ‫bucket_name: השם של קטגוריית Google Cloud האחסון.
• ‫blob_name: השם של ה-blob (אובייקט) בקטגוריה שצוינה.

ייבוא מ Google Cloud אחסון עם התאמה מלאה

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

הערה: כדי לאפשר ל-Discovery Engine לקרוא מהקטגוריה שלכם ב- Google Cloud Storage, אתם צריכים להקצות לסוכן השירות של Discovery Engine את התפקיד Storage Object Viewer (roles/storage.objectViewer) בקטגוריה. בדרך כלל, סוכן השירות מופיע בפורמט service-{PROJECT_NUMBER}@gcp-sa-discoveryengine.iam.gserviceaccount.com.

כשמייבאים מ- Google Cloud Storage, חשוב לשים לב למגבלות הבאות:

• כל בקשת ייבוא יכולה להכיל עד 100 קבצים, או עד 100,000 קבצים אם הפרמטר dataSchema מוגדר לערך content.

• כל קובץ יכול להיות בגודל של עד 2GB, או 100MB אם הפרמטר dataSchema מוגדר לערך content.

Python

    from google.cloud import discoveryengine_v1 as discoveryengine

    def import_documents_from_gcs(
        project_id: str,
        location: str,
        data_store_id: str,
        branch_id: str,
        gcs_uri: str,
    ) -> discoveryengine.ImportDocumentsMetadata:
        """Bulk-import documents from Google Cloud Storage with FULL reconciliation mode."""
        client = discoveryengine.DocumentServiceClient()
        parent = client.branch_path(
            project=project_id,
            location=location,
            data_store=data_store_id,
            branch=branch_id,
        )
        gcs_source = discoveryengine.GcsSource(input_uris=[gcs_uri])
        request = discoveryengine.ImportDocumentsRequest(
            parent=parent,
            gcs_source=gcs_source,
            reconciliation_mode=
                discoveryengine.ImportDocumentsRequest
                .ReconciliationMode.FULL,
        )
        operation = client.import_documents(request=request)
        operation.result()
        return operation.metadata

הפונקציה import_documents_from_gcs משתמשת במשתני המפתח הבאים:

• ‫project_id: מזהה הפרויקט ב- Google Cloud .
• ‫location: המיקום של מאגר הנתונים Google Cloud .
• ‫data_store_id: המזהה של מאגר הנתונים.
• ‫branch_id: המזהה של הענף במאגר הנתונים (בדרך כלל '0').
• ‫gcs_uri: ה-URI של Google Cloud האחסון שמצביע על קובץ ה-JSONL.

בדיקה Google Cloud העלאה לאחסון

כדי לאמת את Google Cloud זרימת העבודה של ייבוא מבוסס-אחסון, מריצים את הפקודה הבאה:

Python

  BUCKET = "your-existing-bucket"
  BLOB = "path-to-any-blob/wp/posts.jsonl"
  SITE = "https://altostrat.com"
  PROJECT_ID = "ucs-3p-connectors-testing"
  LOCATION = "global"
  IDENTITY_MAPPING_STORE_ID = "your-unique-ims-id17" # A unique ID for your new store
  DATA_STORE_ID = "your-data-store-id"
  BRANCH_ID = "0"
  posts = fetch_posts(SITE)
  docs = convert_posts_to_documents(posts)
  print(f"Fetched {len(posts)} posts and converted to {len(docs)} documents.")
  jsonl_payload = convert_documents_to_jsonl(docs)
  gcs_uri = upload_jsonl_to_gcs(jsonl_payload, BUCKET, BLOB)
  print("Uploaded to:", gcs_uri)

  metadata = import_documents_from_gcs(
      PROJECT_ID, LOCATION, DATA_STORE_ID, BRANCH_ID, gcs_uri
  )
  print(f"Imported: {metadata.success_count} documents")

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

• ‫BUCKET: השם של קטגוריית Google Cloud האחסון.
• ‫BLOB: הנתיב ל-blob בתוך הקטגוריה.
• ‫SITE: כתובת ה-URL הבסיסית של מקור הנתונים של הצד השלישי.
• ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
• ‫LOCATION: Google Cloud המיקום של המשאבים (לדוגמה, global).
• ‫IDENTITY_MAPPING_STORE_ID: מזהה ייחודי של מאגר מיפוי הזהויות.
• ‫DATA_STORE_ID: מזהה ייחודי של מאגר הנתונים.
• ‫BRANCH_ID: המזהה של הענף במאגר הנתונים (בדרך כלל '0').
• ‫jsonl_payload: המסמכים שהומרו לפורמט JSONL.
• ‫gcs_uri: ה-URI של Google Cloud האחסון של קובץ ה-JSONL שהועלה.

הפלט אמור להיראות כך:

מעטפת

    Fetched 20 posts and converted to 20 documents.
    Uploaded to: gs://alex-de-bucket/wp/posts.jsonl
    Imported: 20 documents

ניהול הרשאות

כדי לנהל גישה ברמת המסמך בסביבות ארגוניות, Gemini Enterprise תומך ברשימות של בקרת גישה (ACL) ובמיפוי זהויות, שעוזרים להגביל את התוכן שהמשתמשים יכולים לראות.

הפעלת רשימות ACL במאגר נתונים

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

Python

  # get_or_create_data_store()
  "data_store": discoveryengine.DataStore(
      display_name=data_store_id,
      industry_vertical=discoveryengine.IndustryVertical.GENERIC,
      acl_enabled=True, # ADDED
  )

הוספת רשימות ACL למסמכים

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

Python

  # convert_posts_to_documents()
  doc = discoveryengine.Document(
      id=str(post["id"]),
      json_data=json.dumps(payload),
      acl_info=discoveryengine.Document.AclInfo(
          readers=[{
              "principals": [
                  {"user_id": "[e-mail]"},
                  {"user_id": "[e-mail]"}
              ]
          }]
      ),
  )

הגדרת תוכן כציבורי

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

Python

  readers=[{"idp_wide": True}]

אימות רשימות ACL

כדי לוודא שהגדרות ה-ACL פועלות כמצופה, כדאי לשקול את הדברים הבאים:

• חיפוש בתור משתמש שאין לו גישה למסמך.

• בודקים את מבנה המסמך שהועלה ב-Cloud Storage ומשווים אותו למבנה של מסמך לדוגמה.

JSON

  {
    "id": "108",
    "jsonData": "{...}",
    "aclInfo": {
      "readers": [
        {
          "principals": [
            { "userId": "[e-mail]" },
            { "userId": "[e-mail]" }
          ],
          "idpWide": false
        }
      ]
    }
  }

שימוש במיפוי זהויות

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

• מקור הנתונים של הצד השלישי משתמש בזהויות שאינן של Google

• אתם רוצים להפנות לקבוצות בהתאמה אישית (למשל, wp-admins) במקום למשתמשים ספציפיים

• ה-API מחזיר רק שמות של קבוצות

• צריך לקבץ משתמשים באופן ידני כדי להשיג עקביות או כדי להרחיב את השימוש בתכונה

• המערכת של הצד השלישי מטמיעה רשימות ACL באמצעות קבוצות שלא מבוססות על IDP, ואתם רוצים להשתמש במאגר הנתונים המותאם אישית ב-Gemini Enterprise כדי לכבד את רשימות ה-ACL האלה.

כדי למפות זהויות, פועלים לפי השלבים הבאים:

1. יוצרים ומקשרים את מאגר נתוני הזהויות.

2. ייבוא זהויות חיצוניות (לדוגמה, external_group:wp-admins). אל תכללו את external_group: prefix כשמייבאים, לדוגמה:

   JSON

     {
       "externalIdentity": "wp-admins",
       "userId": "[e-mail]"
     }
   

3. בפרטי ה-ACL של המסמך, מגדירים את מזהה הישות החיצונית בprincipal identifier. כשמפנים לקבוצות בהתאמה אישית, משתמשים בקידומת external_group: בשדה groupId.

4. הקידומת external_group: נדרשת למזהי קבוצות בפרטי רשימת בקרת הגישה של המסמך במהלך הייבוא, אבל היא לא משמשת לייבוא זהויות למאגר המיפוי. מסמך לדוגמה עם מיפוי זהויות:

   JSON

     {
       "id": "108",
       "aclInfo": {
         "readers": [
           {
             "principals": [
               {
                 "userId": "[e-mail]"
               },
               {
                 "groupId": "external_group:wp-admins"
               }
             ]
           }
         ]
       },
       "structData": {
         "id": 108,
         "date": "2025-04-24T18:16:04",
         ...
       }
     }
   

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

• כדי לספק ממשק משתמש לשאילתות של הנתונים, יוצרים אפליקציה ב-Gemini Enterprise ומקשרים אותה למאגר הנתונים הקיים של מחבר מותאם אישית.