אזהרה: מחברי העזר של Cloud Search מסופקים "כפי שהם" כקוד לדוגמה לשימוש ביצירת מחברים פעילים משלכם. הקוד לדוגמה דורש התאמה אישית משמעותית ובדיקות לפני שימוש בהוכחת היתכנות או בסביבות ייצור. לשימוש בסביבת הייצור, מומלץ מאוד לקבל עזרה מאחד מהשותפים שלנו ב-Cloud Search. לעזרה נוספת במציאת ענן מתאים שותף חיפוש, עליך לפנות לנציג של חשבון Google שלך. |
ניתן להגדיר את Google Cloud Search כדי לאתר ולהוסיף נתונים לאינדקס של הארגון מסדי נתונים באמצעות מחבר מסד הנתונים של Google Cloud Search.
שיקולים חשובים
אפשר להתקין ולהפעיל את מחבר מסד הנתונים של Cloud Search כמעט בכל סביבה שבה אפליקציות Java יכולות לפעול, כל עוד למחבר יש גישה האינטרנט ומסד הנתונים.
דרישות מערכת
דרישות מערכת | |
---|---|
מערכת הפעלה | Windows או Linux |
מסד נתונים של SQL | כל מסד נתונים של SQL עם מנהל התקן שתואם ל-JDBC 4.0 ואילך, כולל:
|
תוכנה | מנהל התקן JDBC למחבר להשתמש בו כדי לגשת למסד הנתונים (שהורד והותקן בנפרד) |
פריסת המחבר
בשלבים הבאים מוסבר איך להתקין את המחבר ולהגדיר אותו כדי ליצור אינדקס של מסדי הנתונים שצוינו ולהחזיר את התוצאות למשתמשי Cloud Search.
דרישות מוקדמות
לפני שפורסים את מחבר מסד הנתונים של Cloud Search, צריך לאסוף את המידע הבא:
- המפתח הפרטי של Google Workspace, שמכיל גם את מזהה חשבון השירות. למידע על קבלת מפתח פרטי, אפשר לעבור אל הגדרת הגישה ל-Google Cloud חיפוש API ל-REST.
- מזהה מקור נתונים ב-Google Workspace. כדי ללמוד איך לקבל מזהה של מקור נתונים, אפשר לעבור אל מוסיפים מקור נתונים לחיפוש
שלב 1. הורדה ופיתוח של התוכנה של מחבר מסדי נתונים
- משכפלים את מאגר המחברים מ-GitHub.
$ git clone https://github.com/google-cloudsearch/database-connector.git $ cd database-connector
- כדאי לבדוק את הגרסה הרצויה של המחבר:
$ git checkout tags/v1-0.0.3
- יוצרים את המחבר.
כדי לדלג על הבדיקות בזמן פיתוח המחבר, אפשר להשתמש ב-$ mvn package
mvn package -DskipTests
. - מעתיקים את קובץ ה-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. הגדרת המחבר של מסד הנתונים
- יוצרים קובץ טקסט ונותנים לו את השם
connector-config.properties
(ברירת המחדל) או שם דומה. Google ממליצה לתת שם לקובצי תצורה עם התחילית.properties
או.config
ולהשאיר את הקובץ באותה ספרייה שבה נמצא המחבר. אם משתמשים בשם אחר או בנתיב אחר, צריך לציין את הנתיב בזמן שמריצים את המחבר. - מוסיפים פרמטרים לתוכן הקובץ בתור צמדי מפתח/ערך. קובץ התצורה חייב לציין
את הפרמטרים לגישה למקור נתונים, גישה למסד נתונים, הצהרת 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
חובה.
הנתיב המלא של מסד הנתונים שצריך לגשת אליו, כמו |
שם משתמש וסיסמה של מסד נתונים | 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}
הערך יכול להיות:
|
שאילתת מעבר מצטברת | db.incrementalUpdateSql = SELECT column-1[, column-2,...] FROM database-name WHERE last_update_time > ?
חובה אם מתזמנים מעברים מצטברים. הסימן "?" בשאילתה הוא placeholder חובה בשביל ערך של חותמת זמן. המחבר משתמש בחותמת הזמן כדי לעקוב אחר שינויים בין שאילתות 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...]
הקצאת עמודות תוכן (מלבד קבוצת העמודות עבור |
עמודות של נתוני תוכן | db.contentColumns = column-1[, column-2...]
לציין עמודות תוכן במסד הנתונים. הן צריכות להיות בפורמט שהועלו ל-Cloud Search כתוכן מסמך שאפשר לחפש בו. אם לא מציינים ערך, ברירת המחדל היא '*' שמציין שכל צריך להשתמש בעמודות של התוכן. |
עמודת blob | db.blobColumn = column-name
ציון השם של blob יחיד לשימוש בתוכן במסמך במקום בשילוב של עמודות תוכן. אם מצוינת עמודת blob, היא נחשבת לשגיאה אם עמודות תוכן מוגדרות גם הן. עם זאת, הגדרות העמודות של מטא-נתונים ונתונים מובְנים עדיין מותרת יחד עם עמודות blob. |