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

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

• המפתח הפרטי של Google Workspace, שמכיל גם את מזהה חשבון השירות. למידע על קבלת מפתח פרטי, אפשר לעבור אל הגדרת הגישה ל-Google Cloud חיפוש API ל-REST.
• מזהה מקור נתונים ב-Google Workspace. כדי ללמוד איך לקבל מזהה של מקור נתונים, אפשר לעבור אל מוסיפים מקור נתונים לחיפוש

שלב 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

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.

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

דוגמאות לשאילתות 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 = customer_id, first_name, last_name, phone, change_timestamp

db.uniqueKeyColumns = customer_id
# or
db.uniqueKeyColumns = last_name, first_name

דוגמאות לעמודות של כתובות 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

שדות תוכן

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