פריסת מחבר CSV

המדריך הזה מיועד לאדמינים של המחבר של Google Cloud Search ל-CSV (ערכים מופרדים בפסיקים), כלומר לכל מי שאחראי להורדה, להגדרה, להפעלה ולמעקב אחרי המחבר.

המדריך הזה כולל הוראות לביצוע משימות מרכזיות שקשורות לפריסה של מחבר CSV:

• הורדת התוכנה של המחבר של Google Cloud Search ל-CSV
• הגדרת המחבר לשימוש עם מקור נתונים ספציפי מסוג CSV
• פריסה והפעלה של המחבר

כדי להבין את המושגים במסמך הזה, צריך להכיר את העקרונות הבסיסיים של Google Workspace, קבצי CSV ורשימות של בקרת גישה (ACL).

סקירה כללית על המחבר של Google Cloud Search ל-CSV

המחבר של Cloud Search ל-CSV פועל עם כל קובץ טקסט עם ערכים מופרדים בפסיקים (CSV). קובץ CSV מאחסן נתונים בטבלאות, וכל שורה בקובץ היא רשומת נתונים.

המחבר של קובצי CSV ב-Google Cloud Search מחלץ שורות נפרדות מקובץ CSV ומוסיף אותן לאינדקס של Cloud Search דרך Cloud Search Indexing API. אחרי הוספה לאינדקס, אפשר לחפש שורות ספציפיות מקובצי CSV דרך הלקוחות של Cloud Search או דרך Query API של Cloud Search. המחבר של קובצי ה-CSV תומך גם בשליטה בגישה של משתמשים לתוכן בתוצאות החיפוש, באמצעות רשימות ACL.

אפשר להתקין את המחבר של Google Cloud Search ל-CSV ב-Linux או ב-Windows. לפני שמפרסים את המחבר של Google Cloud Search ל-CSV, צריך לוודא שיש לכם את הרכיבים הנדרשים הבאים:

• Java JRE 1.8 מותקנת במחשב שבו פועל המחבר של Google Cloud Search ל-CSV

• המידע ב-Google Workspace שנדרש כדי ליצור קשרים בין Google Cloud Search לבין מקור הנתונים:

  • מפתח פרטי של Google Workspace (שמכיל את מזהה חשבון השירות)
  • מזהה מקור הנתונים ב-Google Workspace

  בדרך כלל, האדמין ב-Google Workspace של הדומיין יכול לספק את פרטי הכניסה האלה.

שלבי הפריסה

כדי לפרוס את המחבר של Google Cloud Search ל-CSV, פועלים לפי השלבים הבאים:

1. התקנת התוכנה של מחבר ה-CSV של חיפוש Google
2. ציון ההגדרות של מחבר ה-CSV
3. הגדרת גישה למקור הנתונים של חיפוש Google ב-Cloud
4. הגדרת הגישה לקובץ CSV
5. ציון שמות העמודות להוספה לאינדקס, עמודות מפתח ייחודיות ועמודות תאריך ושעה
6. ציון העמודות שישמשו בכתובות URL של תוצאות חיפוש שניתן ללחוץ עליהן
7. ציון פרטי מטא-נתונים ופורמטים של עמודות
8. תזמון של סריקה של נתונים
9. ציון אפשרויות של רשימת בקרת גישה (ACL)

1. התקנת ה-SDK

מתקינים את ה-SDK במאגר Maven המקומי.

1. משכפלים את מאגר ה-SDK מ-GitHub.

   $ git clone https://github.com/google-cloudsearch/connector-sdk.git
   $ cd connector-sdk/csv

2. מורידים את הגרסה הרצויה של ה-SDK:

   $ git checkout tags/v1-0.0.3

3. פיתוח המחבר:

   $ mvn package

4. מעתיקים את קובץ ה-zip של המחבר לספריית ההתקנה המקומית:

   $ cp target/google-cloudsearch-csv-connector-v1-0.0.3.zip installation-dir
   $ cd installation-dir
   $ unzip google-cloudsearch-csv-connector-v1-0.0.3.zip
   $ cd google-cloudsearch-csv-connector-v1-0.0.3

2. ציון ההגדרות של מחבר ה-CSV

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

• גישה למקור נתונים
• המיקום של קובץ ה-CSV
• הגדרות של עמודות CSV
• עמודות שמגדירות מזהה ייחודי
• אפשרויות טרנזקציה
• אפשרויות ACL להגבלת הגישה לנתונים

כדי שהמחבר יוכל לגשת לקובץ CSV ולסמן את התוכן הרלוונטי ב-Google שאינדקס, צריך קודם ליצור את קובץ התצורה שלו.

כדי ליצור קובץ תצורה:

1. פותחים כלי לעריכת טקסט לבחירתכם ומעניקים שם לקובץ התצורה.
   מוסיפים תוכן לקובץ בצורת key=value, כפי שמתואר בקטעים הבאים.
2. שומרים את קובץ התצורה ומעניקים לו שם.
   Google ממליצה לתת לקובץ התצורה את השם connector-config.properties כדי שלא יידרשו פרמטרים נוספים בשורת הפקודה להפעלת המחבר.

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

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

3. הגדרת גישה למקור הנתונים של Google Cloud Search

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

4. הגדרת הפרמטרים של קובץ ה-CSV

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

5. ציון שמות העמודות להוספה לאינדקס ועמודות מפתח ייחודיות

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

6. ציון העמודות שבהן רוצים להשתמש בכתובות URL של תוצאות חיפוש שניתן ללחוץ עליהן

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

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

אפשר להוסיף לקבץ התצורה פרמטרים שמציינים:

• פרמטרים להגדרת מטא-נתונים
• פורמטים של עמודות
• איכות החיפוש

פרמטרים להגדרת מטא-נתונים

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

פורמטים של תאריך ושעה

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

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

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

איכות החיפוש

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

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

8. תזמון סריקה של נתונים

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

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

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

9. ציון אפשרויות של רשימת בקרת גישה (ACL)

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

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

המחבר מסתמך על כך שרשמי ACL שמוגדרים כברירת מחדל מופעלים בקובץ התצורה. כדי להפעיל רשימות ACL שמשמשות כברירת מחדל, מגדירים את defaultAcl.mode לכל מצב אחר מלבד none ומגדירים אותו באמצעות defaultAcl.*.

הגדרת סכימה

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

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

נניח שקובץ ה-CSV של הקלט מכיל את התוכן הבא.

1. movieId
2. movieTitle
3. תיאור
4. שנה
5. releaseDate
6. שחקנים (כמה ערכים מופרדים בפסיקים (,))
7. ז'אנר (ערכים מרובים)
8. דירוגים

על סמך המבנה של הנתונים שמתואר למעלה, אפשר להגדיר סכימה למקור נתונים שבו רוצים ליצור אינדקס לנתונים מקובץ CSV.

{
  "objectDefinitions": [
    {
      "name": "movie",
      "propertyDefinitions": [
        {
          "name": "actors",
          "isReturnable": true,
          "isRepeatable": true,
          "isFacetable": true,
          "textPropertyOptions": {
            "operatorOptions": {
              "operatorName": "actor"
            }
          }
        },
        {
          "name": "releaseDate",
          "isReturnable": true,
          "isRepeatable": false,
          "isFacetable": false,
          "datePropertyOptions": {
            "operatorOptions": {
              "operatorName": "released",
              "lessThanOperatorName": "releasedbefore",
              "greaterThanOperatorName": "releasedafter"
            }
          }
        },
        {
          "name": "movieTitle",
          "isReturnable": true,
          "isRepeatable": false,
          "isFacetable": false,
          "textPropertyOptions": {
            "retrievalImportance": {
              "importance": "HIGHEST"
            },
            "operatorOptions": {
              "operatorName": "title"
            }
          }
        },
        {
          "name": "genre",
          "isReturnable": true,
          "isRepeatable": true,
          "isFacetable": true,
          "enumPropertyOptions": {
            "operatorOptions": {
              "operatorName": "genre"
            },
            "possibleValues": [
              {
                "stringValue": "Action"
              },
              {
                "stringValue": "Documentary"
              },
              {
                "stringValue": "Drama"
              },
              {
                "stringValue": "Crime"
              },
              {
                "stringValue": "Sci-fi"
              }
            ]
          }
        },
        {
          "name": "userRating",
          "isReturnable": true,
          "isRepeatable": false,
          "isFacetable": true,
          "integerPropertyOptions": {
            "orderedRanking": "ASCENDING",
            "maximumValue": "10",
            "operatorOptions": {
              "operatorName": "score",
              "lessThanOperatorName": "scorebelow",
              "greaterThanOperatorName": "scoreabove"
            }
          }
        }
      ]
    }
  ]
}

קובץ תצורה לדוגמה

בקובץ התצורה לדוגמה הבא מוצגים זוגות הפרמטר key=value שמגדירים את ההתנהגות של מחבר לדוגמה.

# data source access
api.sourceId=1234567890abcd
api.serviceAccountPrivateKeyFile=./PrivateKey.json

# CSV data structure
csv.filePath=./movie_content.csv
csv.csvColumns=movieId,movieTitle,description,releaseYear,genre,actors,ratings,releaseDate
csv.skipHeaderRecord=true
url.format=https://mymoviesite.com/movies/{0}
url.columns=movieId
csv.datetimeFormat.releaseDate=yyyy-mm-dd
csv.multiValueColumns=genre,actors
csv.multiValue.genre=;
contentTemplate.csv.title=movieTitle

# metadata structured data and content
itemMetadata.title.field=movieTitle
itemMetadata.createTime.field=releaseDate
itemMetadata.contentLanguage.defaultValue=en-US
itemMetadata.objectType.defaultValue=movie
contentTemplate.csv.quality.medium=description
contentTemplate.csv.unmappedColumnsMode=IGNORE

#ACLs
defaultAcl.mode=fallback
defaultAcl.public=true

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

הפעלת המחבר של Cloud Search ל-CSV

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

$ java -jar google-cloudsearch-csv-connector-v1-0.0.3.jar -Dconfig=my.config

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