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

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

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

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

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

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

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

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

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

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

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

ייבוא היסטוריה של אירועי משתמשים מ-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 שמכיל את נתוני אירועי המשתמש. חשוב לוודא שכל אירוע משתמש נמצא בשורה נפרדת, בלי מעברי שורה. במאמר userEvents בהפניה ל-API מוסבר על ייצוג JSON של אירועים של משתמשים. השדות בקובץ הקלט צריכים להיות בפורמט הבא: 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.
  9. לוחצים על Save.

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

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

REST

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

  1. כדי לייבא את אירועי המשתמשים, שולחים בקשת POST ל-method‏ 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 מקומיים של האירועים בקריאה ל-method‏ userEvents.import.

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

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

    {
  "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"