פריסת מחבר למסד נתונים

אזהרה: מחברי העזר של Cloud Search מסופקים "כפי שהם" כקוד לדוגמה לשימוש כשיוצרים מחברים פעילים משלכם. הקוד לדוגמה הזה מחייב התאמה אישית ובדיקה משמעותיות לפני השימוש בו בסביבות של הוכחת רעיון או ייצור. לשימוש בסביבת הייצור, מומלץ מאוד להיעזר באחד מהשותפים שלנו ב-Cloud Search. לקבלת עזרה נוספת במציאת שותף מתאים של Cloud Search, תוכלו לפנות לנציג של חשבון Google שלכם.

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

שיקולים חשובים

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

דרישות מערכת

דרישות מערכת
מערכת הפעלה Windows או Linux
מסד נתונים של SQL כל מסד נתונים של SQL עם מנהל התקן שתואם ל-JDBC 4.0 ואילך, כולל:
  • MS SQL Server (2008, 2012, 2014, 2016)
  • Oracle (11g, 12c)
  • Google Cloud SQL
  • MySQL
תוכנות מנהל התקן JDBC של המחבר שישמש לצורך גישה למסד הנתונים (הורדה והתקנה בנפרד)

פריסת המחבר

בשלבים הבאים מוסבר איך להתקין את המחבר ולהגדיר אותו ליצירת אינדקס של מסדי הנתונים שצוינו ולהחזיר את התוצאות למשתמשי Cloud Search.

דרישות מוקדמות

לפני פריסת מחבר מסד הנתונים של Cloud Search, צריך לאסוף את המידע הבא:

שלב 1. מורידים ויוצרים את התוכנה של מחבר מסד הנתונים

  1. שכפול מאגר המחברים מ-GitHub. 
    $ git clone https://github.com/google-cloudsearch/database-connector.git
$ cd database-connector
  2. בודקים את הגרסה הרצויה של המחבר:
    $ git checkout tags/v1-0.0.3
  3. בניית המחבר. 
    $ mvn package
    כדי לדלג על הבדיקות בזמן יצירת המחבר, אפשר להשתמש ב-mvn package -DskipTests.
  4. מעתיקים את קובץ ה-ZIP של המחבר לספריית ההתקנה המקומית ופורסים אותו: 
    $ cp target/google-cloudsearch-database-connector-v1-0.0.3.zip installation-dir
$ cd installation-dir
$ unzip google-cloudsearch-database-connector-v1-0.0.3.zip
$ cd google-cloudsearch-database-connector-v1-0.0.3

שלב 2: הגדרת המחבר של מסד הנתונים

  1. יוצרים קובץ טקסט ונותנים לו את השם connector-config.properties (ברירת המחדל) או סוג דומה. Google ממליצה לתת לקובצי התצורה בשם .properties או .config ולהשאיר את הקובץ באותה ספרייה שבה נמצא המחבר. אם אתם משתמשים בשם או בנתיב אחר, עליכם לציין את הנתיב בעת הפעלת המחבר.
  2. מוסיפים פרמטרים בתור צמדי מפתח/ערך לתוכן הקובץ. קובץ התצורה חייב לציין את הפרמטרים לגישה למקור הנתונים, גישה למסד הנתונים, הצהרת SQL למעבר מלא של מסד נתונים, כותרת של שדה תוכן והגדרות עמודות. אפשר גם להגדיר התנהגות אחרת של מחברים באמצעות פרמטרים אופציונליים. לדוגמה: 
    # Required parameters for data source access
api.sourceId=1234567890abcdef
api.identitySourceId=0987654321lmnopq
api.serviceAccountPrivateKeyFile=./PrivateKey.json
#
# Required parameters for database access
db.url=jdbc:mysql://localhost:3306/mysql_test
db.user=root
db.password=passw0rd
#
# Required full traversal SQL statement parameter
db.allRecordsSql=select customer_id, first_name, last_name, phone, change_timestamp from address_book
#
# Required parameters for column definitions and URL format
db.allColumns=customer_id, first_name, last_name, phone, change_timestamp
db.uniqueKeyColumns=customer_id
url.columns=customer_id
#
# Required content field parameter
contentTemplate.db.title=customer_id
#
# Optional parameters to set ACLs to "entire domain" access
defaultAcl.mode=fallback
defaultAcl.public=true
#
# Optional parameters for schedule traversals
schedule.traversalIntervalSecs=36000
schedule.performTraversalOnStart=true
schedule.incrementalTraversalIntervalSecs=3600

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

    כדי לקבל מידע על הפרמטרים שמשותפים לכל המחברים של Cloud Search, כמו הגדרת מטא-נתונים, פורמטים של תאריך ושעה ואפשרויות ACL, אפשר לקרוא את המאמר פרמטרים של מחברים שסופקו על ידי Google.

    אם רלוונטי, מציינים מאפיינים של אובייקט הסכימה בפרמטרים של שאילתת ה-SQL למעבר. בדרך כלל אפשר להוסיף כינויים להצהרת ה-SQL. לדוגמה, אם יש לכם מסד נתונים של סרטים והסכימה של מקור הנתונים מכילה הגדרת מאפיין בשם "ActorName", הצהרת SQL יכולה להופיע בצורה הבאה: SELECT …, last_name AS ActorName, … FROM … .

שלב 3. הפעלת המחבר של מסד הנתונים

בדוגמה הבאה ההנחה היא שהרכיבים הנדרשים ממוקמים בספרייה המקומית במערכת Linux.

כדי להפעיל את המחבר משורת הפקודה, מזינים את הפקודה הבאה: 

java \
   -cp "google-cloudsearch-database-connector-v1-0.0.3.jar:mysql-connector-java-5.1.41-bin.jar" \
   com.google.enterprise.cloudsearch.database.DatabaseFullTraversalConnector \
   [-Dconfig=mysql.config]

כאשר:

  • google-cloud-search-database-connector-v1-0.0.3.jar הוא קובץ ה- .jar של מחבר מסד הנתונים
  • mysql-connector-java-5.1.41-bin.jar הוא מנהל התקן JDBC שמשמש לגישה למסד הנתונים
  • mysql.config הוא קובץ תצורה עם שם מותאם אישית. כדי לוודא שהמחבר מזהה את קובץ התצורה, צריך לציין את הנתיב שלו בשורת הפקודה. אחרת, המחבר ישתמש ב-connector-config.properties בספרייה המקומית בתור שם הקובץ שמוגדר כברירת מחדל.

המחבר מדווח על שגיאות תצורה כאשר הוא מזהה אותן. שגיאות מסוימות מדווחות כשהמחבר מופעל, למשל כאשר עמודת מסד נתונים מוגדרת כחלק מתוכן הרשומה (ב-db.allColumns), אבל לא נעשה שימוש בעמודה בשאילתת SQL למעבר במסד הנתונים (ב-db.allRecordsSql). שגיאות אחרות מאותרות ומדווחות רק כשהמחבר מנסה לגשת למסד הנתונים לצורך המעבר הראשון, למשל תחביר הצהרת SQL לא חוקי.

הסבר על פרמטרים של הגדרות

פרמטרים של גישה למקור נתונים

ההגדרה פרמטר
מזהה של מקור נתונים api.sourceId = source-ID

חובה. מזהה המקור ב-Cloud Search שהאדמין ב-Google Workspace הגדיר
המזהה של מקור הזהות api.identitySourceId = identity-source-ID

נדרש כדי להשתמש בקבוצות ומשתמשים חיצוניים ברשימות ACL. המזהה של מקור הזהות ב-Cloud Search שהאדמין ב-Google Workspace הגדיר
חשבון שירות api.serviceAccountPrivateKeyFile = path-to-private-key

חובה. הנתיב לקובץ המפתח של חשבון השירות ב-Cloud Search שהאדמין ב-Google Workspace יצר.

פרמטרים של גישה למסד הנתונים

ההגדרה פרמטר
כתובת ה-URL של מסד הנתונים db.url = database-URL

חובה. הנתיב המלא של מסד הנתונים שאליו יש לגשת, למשל jdbc:mysql://127.0.0.1/dbname.
שם משתמש וסיסמה למסד הנתונים db.user = username
db.password = password

חובה. שם משתמש וסיסמה תקפים שבהם המחבר משתמש כדי לגשת למסד הנתונים. למשתמש במסד הנתונים חייבת להיות גישת קריאה לרשומות הרלוונטיות של מסד הנתונים שנקרא.
מנהל התקן JDBC db.driverClass = oracle.jdbc.OracleDriver

נדרש רק אם מנהל התקן JDBC 4.0 לא צוין כבר בנתיב המחלקה.

פרמטרים של שאילתת SQL למעבר

המחבר עובר בין רשומות מסד הנתונים באמצעות שאילתות SQL SELECT בקובץ התצורה. יש להגדיר שאילתת מעבר מלאה. שאילתות של מעברים מצטברים הן אופציונליות.

מעבר מלא קורא כל רשומת מסד נתונים שהוגדרה להוספה לאינדקס. יש צורך במעבר מלא כדי ליצור אינדקס של רשומות חדשות ל-Cloud Search וגם כדי ליצור מחדש את כל הרשומות הקיימות לאינדקס.

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

המחבר מריץ את המעברים האלה בהתאם ללוחות הזמנים שהגדרת ב פרמטרים של תזמון המעבר.

ההגדרה פרמטר
שאילתת מעבר מלאה db.allRecordsSql = SELECT column-1[, column-2,...] FROM database-name

חובה. הרצת השאילתה בכל מעבר מלא.

בשאילתה הזו חייב להיכלל כל שם עמודה שהמחבר ישתמש בו בכל קיבולת (תוכן, מזהה ייחודי, רשימות ACL). המחבר מבצע מספר אימותים ראשוניים בזמן ההפעלה כדי לזהות שגיאות והשמטות. לכן אין להשתמש בשאילתה כללית מסוג "SELECT * FROM ...".
עימוד מעבר מלא db.allRecordsSql.pagination = {none | offset}

הערך יכול להיות:

  • none: ללא שימוש בעימוד
  • offset: שימוש בעימוד לפי היסט שורה

    כדי להשתמש בעימוד באמצעות היסט, שאילתת ה-SQL חייבת לכלול סימן שאלה (?) עבור היסט שורה, שמתחיל באפס. בכל מעבר מלא, השאילתה מופעלת שוב ושוב עד שלא מוחזרות תוצאות.
שאילתת מעבר מצטבר db.incrementalUpdateSql = SELECT column-1[, column-2,...] FROM database-name WHERE last_update_time > ?

חובה אם מתזמנים מעברים מצטברים.

התו '?' בשאילתה הוא placeholder שנדרש לערך של חותמת זמן. המחבר משתמש בחותמת הזמן כדי לעקוב אחר שינויים בין שאילתות SQL במעבר מצטברות.

כדי לעקוב אחר עמודת חותמת הזמן של מסד הנתונים של מועד העדכון האחרון, מוסיפים את הכינוי timestamp_column להצהרת ה-SQL. אם לא, משתמשים בחותמת הזמן הנוכחית של המעבר מהמחבר.

במעבר המצטבר הראשון, המחבר משתמש בשעת ההתחלה של המחבר. אחרי המעבר המצטבר הראשון, המערכת שומרת את חותמת הזמן ב-Cloud Search כדי לאפשר למחבר להפעיל מחדש לגשת לחותמת הזמן של המעבר המצטבר הקודם.
אזור הזמן של מסד הנתונים db.timestamp.timezone = America/Los_Angeles

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

דוגמאות לשאילתות SQL של מעבר

  • שאילתת מעבר מלאה בסיסית שקוראת את כל הרשומות של תחומי עניין במסד הנתונים של העובדים לצורך הוספה לאינדקס: 
    db.allRecordsSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field \
    FROM employee
  • ציון עימוד לפי היסט ופיצול של מעבר מלא לשאילתות מרובות.

    ל-SQL Server 2012 או Oracle 12c (תחביר סטנדרטי של SQL 2008):

    db.allRecordsSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field \
    FROM employee \
    ORDER BY customer_id OFFSET ? ROWS FETCH FIRST 1000 ROWS ONLY
db.allRecordsSql.pagination = offset

    או, ל-MySQL או ל-Google Cloud SQL:

    db.allRecordsSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field \
    FROM employee \
    ORDER BY customer_id LIMIT 1000 OFFSET ?
db.allRecordsSql.pagination = offset
  • שאילתת מעבר מלאה שמחילה רשימות ACL נפרדות עם כינויים: 
    db.allRecordsSql = SELECT customer_id, first_name, last_name,  employee_id, interesting_field, last_update_time, \
     permitted_readers AS readers_users, \
     denied_readers AS denied_users, \
     permitted_groups AS readers_groups, \
     denied_groups AS denied_groups \
     FROM employee
  • שאילתת מעבר מצטבר בסיסית: 
    db.incrementalUpdateSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field, last_update_time \
     FROM employee \
     WHERE last_update_time > ?
  • שאילתת מעבר מצטברת שמחילה רשימות ACL נפרדות עם כינויים: 
    db.incrementalUpdateSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field, last_update_time, \
     permitted_readers AS readers_users, \
     denied_readers AS denied_users, \
     permitted_groups AS readers_groups, \
     denied_groups AS denied_groups \
     FROM employee \
     WHERE last_update_time > ?
  • שאילתת מעבר מצטברת שמשתמשת בחותמת הזמן של מסד הנתונים ולא בשעה הנוכחית: 
    db.incrementalUpdateSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field, \
     last_update_time AS timestamp_column \
     FROM employee \
     WHERE last_update_time > ?

פרמטרים של הגדרת עמודה

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

ההגדרה פרמטר
כל העמודות db.allColumns = column-1, column-2, ...column-N

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

דוגמה:

db.allColumns = customer_id, first_name, last_name, phone, change_timestamp
עמודות מפתח ייחודיות db.uniqueKeyColumns = column-1[, column-2]

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

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

דוגמאות:

db.uniqueKeyColumns = customer_id
# or
db.uniqueKeyColumns = last_name, first_name
עמודת קישור לכתובת URL url.columns = column-1[, column-2]

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

עם זאת, אם ערכי העמודות מגדירים קישור חוקי לכל רשומה, צריך לציין את העמודות של כתובת ה-URL של התצוגה ואת הערכים של הגדרות הפורמט.
הפורמט של כתובת ה-URL url.format = https://www.example.com/{0}

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

אם לא צוין, ברירת המחדל היא "{0}."

דוגמאות מופיעות אחרי הטבלה הזו.
עמודות מקודדות באחוזים עבור כתובת URL url.columnsToEscape = column-1[, column-2]

מציינת עמודות מ-db.columns שהערכים שלהן יקודדו באחוזים לפני שיכללו אותם במחרוזת של כתובת ה-URL המעוצבת.

דוגמאות לעמודות של כתובות URL

כדי לציין את העמודות שמשמשות בשאילתות מעבר ואת הפורמט של כתובת האתר של התצוגה:

  • כדי להשתמש בכתובת URL סטטית שלא נעשה בה שימוש בערכים של רשומת מסד נתונים: 
    url.format = https://www.example.com
  • כדי להשתמש בערך של עמודה אחת שהוא כתובת ה-URL של התצוגה: 
    url.format = {0}
url.columns = customer_id
  • כדי להשתמש בערך של עמודה אחת שיוחלף בכתובת ה-URL של התצוגה המפורטת במיקום {0}: 
    url.format = https://www.example.com/customer/id={0}
url.columns = customer_id
url.columnsToEscape = customer_id
  • כדי להשתמש במספר ערכים של עמודות ליצירת כתובת ה-URL של התצוגה (העמודות תלויות-סדר): 
    url.format = {1}/customer={0}
url.columns = customer_id, linked_url
url.columnsToEscape = customer_id

שדות תוכן

אפשר להשתמש באפשרויות התוכן כדי להגדיר אילו ערכי רשומות יהפכו לחלק מהתוכן שמיועד לחיפוש.

ההגדרה פרמטר
עמודת החיפוש האיכותית ביותר contentTemplate.db.title = column-name

חובה. העמודה באיכות הגבוהה ביותר להוספה לאינדקס של חיפוש ולתעדוף תוצאות.
קביעת סדר העדיפות של עמודות לחיפוש contentTemplate.db.quality.high = column-1[, column-2...]
contentTemplate.db.quality.medium = column-1[, column-2...]
contentTemplate.db.quality.low = column-1[, column-2...]

ציון עמודות תוכן (למעט קבוצת העמודות של contentTemplate.db.title) כשדות באיכות גבוהה, בינונית או נמוכה של חיפוש. עמודות שלא צוינו ברירת המחדל הן 'נמוך'.
עמודות של נתוני תוכן db.contentColumns = column-1[, column-2...]

ציון עמודות התוכן במסד הנתונים. הם מעוצבים ומועלים אל Cloud Search כתוכן שניתן לחפש בו.

אם לא מציינים ערך, ברירת המחדל היא '*', ומציינת שיש להשתמש בכל העמודות לתוכן.
עמודת blob db.blobColumn = column-name

צריך לציין את השם של עמודת blob בודדת שתשמש בתוכן המסמך במקום שילוב של עמודות תוכן.

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