ייצוא הנתונים ל-BigQuery

בדף הזה מוסבר איך להעלות נתונים של מוצרים קמעונאיים ואירועים של משתמשים אל BigQuery. אחרי שהנתונים יהיו ב-BigQuery, תוכלו להשתמש בהם כדי לבצע חיזוי מכירות באמצעות Vertex AI ולצפות בנתונים בלוחות בקרה מוכנים מראש של Looker.

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

הערה: רק bigqueryDestination נתמך לייצוא אירועים שקשורים למשתמשים. בנוסף, מערך הנתונים ב-BigQuery שצוין ב-bigqueryDestination חייב להיות ממוקם באזור ארה"ב שפרוס על פני כמה אזורים.

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

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

למשל:

• ייבוא פרטי קטלוג.
• הקלטת אירועים של משתמשים בזמן אמת.
• ייבוא אירועים היסטוריים של משתמשים.

יצירת מערך נתונים ב-BigQuery

צריך ליצור מערך נתונים אחד או שניים ב-BigQuery כדי לאחסן את נתוני האירועים של המוצר והמשתמש.

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

צריך ליצור את מערכי הנתונים באותו פרויקט שבו הטמעתם את AI Commerce Search.

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

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

2. יוצרים מערך נתונים ב-BigQuery במספר אזורים בארה"ב. לדוגמה, נותנים את השם retail_data.

   הערה: אי אפשר לייצא נתוני אירועים של משתמשים ב-AI Commerce Search לאזורים מחוץ לארה"ב. חשוב לזכור ש-AI Commerce Search לא משתמש בפרטים אישיים מזהים (PII). אם בוחרים אזור שמבוסס באיחוד האירופי למיקום של מערך הנתונים, נתוני הלקוחות העיקריים של BigQuery נמצאים באיחוד האירופי. נתוני ליבה של לקוחות BigQuery מוגדרים בתנאים הספציפיים לשירות של BigQuery.

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

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

מערך הנתונים הזה ישמש לאחסון טבלאות הנתונים שתייצאו. בקטעים הבאים מוסבר איך לייצא.

ייצוא קטלוג החיפוש של AI Commerce לטבלה ב-BigQuery

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

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

• ‫PROJECT_ID: המזהה של פרויקט AI Commerce Search API שבו יצרתם את מערך הנתונים ב-BigQuery.
• ‫BRANCH_ID: המזהה של הענף בקטלוג. משתמשים ב-default_branch כדי לקבל נתונים מהענף שמוגדר כברירת מחדל. מידע נוסף זמין במאמר בנושא ענפים בקטלוג.
• ‫DATASET_ID: השם של מערך הנתונים שיצרתם במאמר יצירת מערך נתונים ב-BigQuery. לדוגמה, אפשר להשתמש ב-retail_data או ב-retail_product_data. מערך הנתונים צריך להיות באותו פרויקט. אל תוסיפו את מזהה הפרויקט בשדה datasetId.
• ‫TABLE_ID_PREFIX: קידומת למזהה הטבלה. הקידומת לא יכולה להיות מחרוזת ריקה. הסיומת _retail_products_BRANCH_ID מתווספת כדי להשלים את שם הטבלה. לדוגמה, אם הקידומת היא test, שם הטבלה הוא _test_retail_products_BRANCH_ID.

תוכן בקשת JSON:

{
  "outputConfig":
  {
    "bigqueryDestination":
    {
      "datasetId": "DATASET_ID",
        "tableIdPrefix": "TABLE_ID_PREFIX",
        "tableType": "view"
    }
  }
}

כדי לשלוח את הבקשה צריך להרחיב אחת מהאפשרויות הבאות:

‫Curl (Linux,‏ macOS או Cloud Shell)

הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login, או באמצעות Cloud Shell שמחבר אתכם אוטומטית ל-CLI של gcloud. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

שומרים את גוף הבקשה בקובץ בשם request.json. כדי ליצור או להחליף את הקובץ הזה בספרייה הנוכחית, מריצים את הפקודה הבאה בטרמינל:

cat > request.json << 'EOF'
{
  "outputConfig":
  {
    "bigqueryDestination":
    {
      "datasetId": "DATASET_ID",
        "tableIdPrefix": "TABLE_ID_PREFIX",
        "tableType": "view"
    }
  }
}
EOF

לאחר מכן מבצעים את הפקודה הבאה כדי לשלוח את בקשת ה-REST:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://retail.googleapis.com/v2alpha/projects/PROJECT_ID/locations/global/catalogs/default_catalog/branches/BRANCH_ID/products:export"

‎PowerShell (Windows)

הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

שומרים את גוף הבקשה בקובץ בשם request.json. כדי ליצור או להחליף את הקובץ הזה בספרייה הנוכחית, מריצים את הפקודה הבאה בטרמינל:

@'
{
  "outputConfig":
  {
    "bigqueryDestination":
    {
      "datasetId": "DATASET_ID",
        "tableIdPrefix": "TABLE_ID_PREFIX",
        "tableType": "view"
    }
  }
}
'@  | Out-File -FilePath request.json -Encoding utf8

לאחר מכן מבצעים את הפקודה הבאה כדי לשלוח את בקשת ה-REST:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://retail.googleapis.com/v2alpha/projects/PROJECT_ID/locations/global/catalogs/default_catalog/branches/BRANCH_ID/products:export" | Select-Object -Expand Content

אתם אמורים לקבל תגובת JSON שדומה לזו:

{
  "name": "projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/BRANCH_ID/operations/17986570020347019923",
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.retail.v2alpha.ExportProductsResponse",
    "outputResult": {
      "bigqueryResult": [
        {
          "datasetId": "DATASET_ID",
          "tableId": "TABLE_ID_PREFIX_retail_products_BRANCH_ID"
        }
      ]
    }
  }
}

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

כדי לייצא את אירועי המשתמשים שלכם בתחום הקמעונאות לטבלה ב-BigQuery, משתמשים בשיטה userEvents.export:

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

• ‫PROJECT_ID: המזהה של פרויקט AI Commerce Search API שבו יצרתם את מערך הנתונים ב-BigQuery.
• ‫DATASET_ID: השם של מערך הנתונים שיצרתם בשלב יצירת מערך נתונים ב-BigQuery. לדוגמה, אפשר להשתמש ב-retail_data או ב-retail_product_data.
• ‫TABLE_ID_PREFIX: קידומת למזהה הטבלה. הקידומת לא יכולה להיות מחרוזת ריקה. הסיומת retail_products מתווספת כדי להשלים את שם הטבלה. לדוגמה, אם הקידומת היא test, שם הטבלה הוא test_retail_products.

תוכן בקשת JSON:

{
  "outputConfig":
  {
    "bigqueryDestination":
    {
      "datasetId": "DATASET_ID",
        "tableIdPrefix": "TABLE_ID_PREFIX",
        "tableType": "view"
    }
  }
}

כדי לשלוח את הבקשה צריך להרחיב אחת מהאפשרויות הבאות:

‫Curl (Linux,‏ macOS או Cloud Shell)

הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login, או באמצעות Cloud Shell שמחבר אתכם אוטומטית ל-CLI של gcloud. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

שומרים את גוף הבקשה בקובץ בשם request.json. כדי ליצור או להחליף את הקובץ הזה בספרייה הנוכחית, מריצים את הפקודה הבאה בטרמינל:

cat > request.json << 'EOF'
{
  "outputConfig":
  {
    "bigqueryDestination":
    {
      "datasetId": "DATASET_ID",
        "tableIdPrefix": "TABLE_ID_PREFIX",
        "tableType": "view"
    }
  }
}
EOF

לאחר מכן מבצעים את הפקודה הבאה כדי לשלוח את בקשת ה-REST:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://retail.googleapis.com/v2alpha/projects/PROJECT_ID/locations/global/catalogs/default_catalog/userEvents:export"

‎PowerShell (Windows)

הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

שומרים את גוף הבקשה בקובץ בשם request.json. כדי ליצור או להחליף את הקובץ הזה בספרייה הנוכחית, מריצים את הפקודה הבאה בטרמינל:

@'
{
  "outputConfig":
  {
    "bigqueryDestination":
    {
      "datasetId": "DATASET_ID",
        "tableIdPrefix": "TABLE_ID_PREFIX",
        "tableType": "view"
    }
  }
}
'@  | Out-File -FilePath request.json -Encoding utf8

לאחר מכן מבצעים את הפקודה הבאה כדי לשלוח את בקשת ה-REST:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://retail.googleapis.com/v2alpha/projects/PROJECT_ID/locations/global/catalogs/default_catalog/userEvents:export" | Select-Object -Expand Content

אתם אמורים לקבל תגובת JSON שדומה לזו:

{
  "name": "projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/operations/17203443067109586170",
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.retail.v2alpha.ExportUserEventsResponse",
    "outputResult": {
      "bigqueryResult": [
        {
          "datasetId": "DATASET_ID",
          "tableId": "TABLE_ID_PREFIX_retail_user_events"
        }
      ]
    }
  }
}

מידע על הנתונים המיוצאים

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

• הנתונים שמיוצאים לטבלאות BigQuery בפרויקט הם תצוגות מורשות, ולא תצוגות חומריות.

• אי אפשר לשנות או לעדכן את הנתונים בטבלאות האלה.

• המוצרים מתעדכנים כל שעה.

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

מידע על נתוני אירועים של משתמשים שיוצאו

הנה כמה דברים שכדאי לדעת על פרטי המוצר שכלולים בנתוני אירועי המשתמש שייצאו.

פרטי מחיר המוצר

האופן שבו מוחזרים פרטי מחיר המוצר באמצעות השיטה userEvents.export תלוי בגורמים הבאים:

• כללתם נתוני מחירים בנתוני אירועי המשתמשים בזמן ההטמעה. כשמפעילים את השיטה userEvents.export, המחיר שמוחזר עם אירוע משתמש הוא המחיר של המוצר בזמן האירוע.

• לא כללתם פרטי מחיר בנתוני האירועים של המשתמשים, אבל כללתם פרטי מחיר בנתוני המוצרים בזמן ההטמעה. כשמפעילים את השיטה userEvents.export, המחיר שמוחזר עם אירוע משתמש הוא לא בהכרח המחיר של המוצר בזמן האירוע. זה המחיר שנמצא בנתוני המוצרים בזמן ההעלאה.

• לא כללתם פרטי מחיר בנתוני אירועי המשתמשים, ולא קיימים פרטי מחיר בנתוני המוצרים. כשמפעילים את השיטה userEvents.export, לא מוחזר מחיר עם אירועי המשתמש.

פרטי מוצר נוספים

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

אופציונלי: אישור שהטבלאות החדשות נמצאות ב-BigQuery

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

1. ב-BigQuery, עוברים למערך הנתונים או למערכי הנתונים שיצרתם בשלב יצירת מערך נתונים ב-BigQuery.

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

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

מידע נוסף על האופן שבו AI Commerce Search מטפל בנתוני לקוחות זמין בדף משילות מידע (data governance).