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

אזהרה: מחברי ההפניה של 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 הוא קובץ ה-Jam במחבר מסד הנתונים
  • 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}

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

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

    כדי להשתמש בהגדרת עימוד לפי היסט, שאילתת השאילתה חייבת לכלול סימן שאלה 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.columns = column-1[, column-2]

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

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

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

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

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

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

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

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

  • כדי להשתמש בכתובת URL סטטית שלא נעשה בה שימוש בערכים של רשומת מסד נתונים: 
    url.format = https://www.example.com
  • כדי להשתמש בערך אחד בעמודה שהוא כתובת ה-URL של התצוגה המפורטת: 
    url.format = {0}
url.columns = customer_id
  • כדי להשתמש בערך עמודה יחיד המוחלף בכתובת האתר של התצוגה המפורטת במיקום {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, היא נחשבת כשגיאה אם גם עמודות התוכן מוגדרות. עם זאת, ניתן להמשיך להשתמש בהגדרות העמודות של המטא נתונים ושל הנתונים המוב areנים יחד עם עמודות blob.