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

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

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

  2. מייבאים את האירועים על ידי שליחת בקשת POST ל-method‏ 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 שמכיל את נתוני האירועים של המשתמשים. במאמרי העזרה של ה-API מוסבר איך userEvents מיוצגים בפורמט JSON.

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

  2. מייבאים את האירועים על ידי שליחת בקשת POST ל-method‏ 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"