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

אזהרה: מחברי העזר של 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 שאילתות בקובץ התצורה. עליך להגדיר שאילתת מעבר מלאה; שאילתות לגבי מעברים הדרגתיים הם אופציונליים.

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

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

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

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

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

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

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

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

    כדי להשתמש בעימוד לפי היסט, בשאילתת ה-SQL צריך להופיע סימן שאלה של placeholder (?) להיסט שורה, שמתחיל באפס. בכל מעבר מלא, השאילתה מופעלת שוב ושוב עד שלא מוחזרות תוצאות.
שאילתת מעבר מצטברת 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.format = https://www.example.com/{0}

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