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

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

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

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

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

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

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

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

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

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

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

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

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

המסוף

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

  1. נכנסים לדף AI Applications במסוף Google Cloud .

    אפליקציות AI

  2. בדף Apps (אפליקציות), לוחצים על אפליקציית המדיה.

  3. עוברים לדף נתונים.

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

  4. לוחצים על הכרטיסייה אירועים. אם כבר ייבאתם אירועים, המידע עליהם מוצג בכרטיסייה הזו.

  5. לוחצים על ייבוא אירועים.

  6. בוחרים באפשרות אחסון בענן כמקור הנתונים.

  7. מזינים או בוחרים את המיקום של אירועי המשתמש ב-Cloud Storage.

  8. לוחצים על Import.

  9. בכרטיסייה פעילות מוצג הסטטוס של הייבוא.

  10. אם מתרחשות שגיאות בייבוא, בכרטיסייה פעילות:

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

    2. בחלונית פרטים של יומן הפעילות, לוחצים על הצגת יומני השגיאות המלאים כדי לראות את השגיאה ב-Logs Explorer.

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 ממליצה להשאיר את השדה הזה ריק כדי שהתכונה 'חיפוש באמצעות סוכן' תיצור באופן אוטומטי ספרייה זמנית.

  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

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

המסוף

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

  1. נכנסים לדף AI Applications במסוף Google Cloud .

    אפליקציות AI

  2. בדף Apps (אפליקציות), לוחצים על אפליקציית המדיה.

  3. עוברים לדף נתונים.

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

  4. לוחצים על הכרטיסייה אירועים. אם כבר ייבאתם אירועים, המידע עליהם מוצג בכרטיסייה הזו.

  5. לוחצים על ייבוא אירועים.

  6. בוחרים באפשרות BigQuery כמקור הנתונים.

  7. מזינים או בוחרים את הנתיב ב-BigQuery לאירועים של המשתמשים.

  8. לוחצים על Import.

  9. בכרטיסייה פעילות מוצג הסטטוס של הייבוא.

  10. אם מתרחשות שגיאות בייבוא, בכרטיסייה פעילות:

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

    2. בחלונית פרטים של יומן הפעילות, לוחצים על הצגת יומני השגיאות המלאים כדי לראות את השגיאה ב-Logs Explorer.

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 שמכיל את נתוני אירועי המשתמש. לייצוג 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"