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

בדף הזה מוסבר איך לייבא נתונים של אירועי משתמשים מאירועים קודמים בכמות גדולה.

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

אם באירוע יש מסמכים שמופיעים ב-userEvents.Documents, Gemini Enterprise מצטרף אוטומטית לאירועים עם המסמך הזה. הצטרפות מאפשרת ל-Gemini Enterprise לשייך אירועים כמו קליקים וצפיות למסמך הנכון בתוצאת חיפוש או בהמלצה. באפליקציות של חיפוש והמלצות בהתאמה אישית, ההצטרפות מתרחשת באופן אסינכרוני, כלומר, אירועי משתמשים מצורפים למסמכים אחרי שהייבוא של קבוצת המסמכים מסתיים (בדרך כלל תוך דקות).

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

מידע נוסף על שיטת הייבוא זמין במאמר userEvents.import.

כדי לייבא אירועים של משתמשים בזמן אמת, אפשר לעיין במאמר בנושא תיעוד אירועים של משתמשים בזמן אמת.

אפשר לייבא אירועים היסטוריים בדרכים הבאות:

לייצוג JSON של אירועי משתמשים, אפשר לעיין בuserEvents בהפניה ל-API.

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

לפני שמייבאים אירועים של משתמשים:

ייבוא של אירועי משתמשים היסטוריים מ-Cloud Storage

REST

כדי לייבא אירועי משתמשים היסטוריים בכמות גדולה מ-Cloud Storage, פועלים לפי השלבים הבאים:

  1. יוצרים קובץ נתונים אחד או יותר לפרמטרים של הקלט לייבוא. משתמשים באובייקט gcsSource כדי להפנות לקטגוריה של Cloud Storage.

    {
"gcsSource": {
  "inputUris": ["INPUT_FILE_1", "INPUT_FILE_2"],
  "dataSchema": "user_event"
  },
  "errorConfig":{
      "gcsPrefix":"ERROR_DIRECTORY"
  }
}

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

    • ‫INPUT_FILE: קובץ ב-Cloud Storage שמכיל את נתוני האירועים של המשתמש. חשוב לוודא שכל אירוע משתמש מופיע בשורה נפרדת, בלי מעברי שורה. לעיון בייצוג JSON של אירועים שקשורים למשתמשים, אפשר לעיין ב-userEvents בהפניה ל-API. השדות בקובץ הקלט צריכים להיות בפורמט הבא: gs://<bucket>/<path-to-file>/.
    • ‫ERROR_DIRECTORY: אופציונלי. ספרייה ב-Cloud Storage למידע על שגיאות בייבוא – לדוגמה, gs://<your-gcs-bucket>/directory/import_errors. ‫Google ממליצה להשאיר את השדה הזה ריק כדי לאפשר ל-Gemini Enterprise ליצור באופן אוטומטי ספרייה זמנית.

  2. כדי לייבא את האירועים, שולחים בקשת POST לשיטה userEvents.import ומציינים את השם של קובץ הנתונים.

    curl -X POST \
    -v \
    -H "Content-Type: application/json; charset=utf-8" \
    -H "Authorization: Bearer "$(gcloud auth print-access-token)"" \
    --data @DATA_FILE.json \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_NUMBER/locations/global/userEvents:import"

ייבוא של אירועים היסטוריים של משתמשים מ-BigQuery

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

הגדרת גישה ל-BigQuery

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

  1. פותחים את הדף IAM & Admin במסוף Google Cloud .
  2. בוחרים את הפרויקט שמכיל את מאגר הנתונים שרוצים לייבא אליו אירועים של משתמשים.
  3. מסמנים את תיבת הסימון Include Google-provided role grants.
  4. מחפשים את חשבון השירות עם השם Discovery Engine Service Account.
  5. אם לא הפעלתם בעבר פעולת ייבוא באמצעות Discovery Engine, יכול להיות שחשבון השירות הזה לא יופיע ברשימה. אם חשבון השירות הזה לא מופיע, חוזרים למשימת הייבוא ומפעילים את הייבוא. אם הפעולה נכשלת בגלל שגיאות הרשאה, צריך לחזור לכאן ולהשלים את המשימה הזו. חשבון השירות של Discovery Engine יופיע ברשימה.
  6. מעתיקים את המזהה של חשבון השירות, שנראה כמו כתובת אימייל – לדוגמה, service-525@gcp-sa-discoveryengine.iam.gserviceaccount.com.
  7. עוברים לפרויקט BigQuery (באותו דף IAM & Admin) ולוחצים על Grant Access (מתן גישה).
  8. בקטע New principals (ישויות חדשות), מזינים את המזהה של חשבון השירות ובוחרים בתפקיד BigQuery > BigQuery Data Viewer (בעל הרשאת צפייה בנתונים ב-BigQuery).
  9. לוחצים על Save.

מידע נוסף על גישה ל-BigQuery זמין במאמר שליטה בגישה למערכי נתונים במסמכי התיעוד של BigQuery.

ייבוא אירועים מ-BigQuery

REST

כדי לייבא אירועים היסטוריים של משתמשים בכמות גדולה מ-BigQuery, פועלים לפי השלבים הבאים:

  1. כדי לייבא את אירועי המשתמשים, שולחים בקשת POST לשיטה userEvents.import ומציינים את שם הפרויקט ב-BigQuery, את מזהה מערך הנתונים ואת מזהה הטבלה.

    כשמייבאים את האירועים, צריך להשתמש בערך user_event עבור dataSchema.

    curl \
  -v \
  -X POST \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "Authorization: Bearer "$(gcloud auth print-access-token)"" \
  "https://discoveryengine.googleapis.com/v1/projects/[PROJECT_NUMBER]/locations/global/userEvents:import" \
  --data '{
      "bigquerySource": {
          "projectId":"PROJECT_ID",
          "datasetId": "DATASET_ID",
          "tableId": "TABLE_ID",
          "dataSchema": "user_event"
      }
    }'

ייבוא אירועים היסטוריים של משתמשים כנתוני JSON מקומיים

כדי לייבא אירועים שקשורים למשתמשים, צריך לכלול נתוני JSON מקומיים של האירועים בקריאה לשיטה userEvents.import.

כדי להכניס נתוני אירועים של משתמשים לקובץ JSON ולציין את הקובץ בבקשת API, פועלים לפי ההוראות הבאות:

  1. יוצרים קובץ JSON שמכיל את נתוני אירועי המשתמש. בuserEvents במאמרי העזרה של ה-API מופיע ייצוג JSON של אירועים שקשורים למשתמשים.

    {
  "inlineSource": {
    "userEvents": [
      {
        USER_EVENT_1
      },
      {
        USER_EVENT_2
      }
    ]
  }
}

  2. כדי לייבא את האירועים, שולחים בקשת POST לשיטה userEvents.import ומציינים את השם של קובץ הנתונים.

    curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    --data @[JSON_FILE] \
  "https://discoveryengine.googleapis.com/v1/projects/PROJECT_NUMBER/locations/global/userEvents:import"