פריסת מחבר CSV

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

במדריך הזה מפורטות הוראות לביצוע המשימות העיקריות הבאות:

  • מורידים את תוכנת המחבר CSV ל-Cloud Search.
  • מגדירים את המחבר למקור נתונים ספציפי בפורמט CSV.
  • פורסים ומריצים את המחבר.

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

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

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

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

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

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

שלבי הפריסה

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

  1. התקנת תוכנת המחבר
  2. הגדרת המחבר
  3. הגדרת גישה למקור הנתונים של Cloud Search
  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. כדי לבדוק את הגרסה שבחרתם: 

    $ git checkout tags/v1-0.0.3

  3. בניית המחבר: 

    $ mvn package

  4. מחילוץ והתקנה של המחבר: 

    $ 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 וההגדרות שלו.
  • עמודות עם מזהים ייחודיים.
  • אפשרויות של מעבר בין תיקיות ורשימות ACL.

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

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

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

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

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

הגדרה פרמטר
מזהה מקור הנתונים api.sourceId=1234567890abcdef

חובה. מזהה המקור ב-Cloud Search שהוגדר על ידי האדמין ב-Google Workspace.
הנתיב למפתח הפרטי של חשבון השירות api.serviceAccountPrivateKeyFile=./PrivateKey.json

חובה. קובץ המפתח של חשבון השירות לגישה למחבר.
המזהה של מקור הזהות api.identitySourceId=x0987654321

נדרש אם משתמשים במשתמשים ובקבוצות חיצוניים. מזהה מקור הזהויות שהוגדר על ידי האדמין ב-Google Workspace.

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

מאתרים את הנתיב, הפורמט והקידוד של הקובץ.

הגדרה פרמטר
הנתיב לקובץ ה-CSV csv.filePath=./movie_content.csv

חובה. הנתיב לקובץ להוספה לאינדקס.
תבנית קובץ csv.format=DEFAULT

הפורמט של הקובץ. הערכים האפשריים הם מהמחלקה CSVFormat של Apache Commons CSV.

ערכי הפורמט כוללים: DEFAULT, ‏EXCEL, ‏INFORMIX_UNLOAD, ‏INFORMIX_UNLOAD_CSV, ‏MYSQL, ‏RFC4180, ‏ORACLE, ‏POSTGRESQL_CSV, ‏POSTGRESQL_TEXT ו-TDF. אם לא מציינים ערך, Cloud Search משתמש ב-DEFAULT.
ערך מקדם של פורמט קובץ csv.format.withMethod=value

שינוי באופן שבו Cloud Search מטפל בקובץ. השיטות האפשריות הן מהמחלקה CSVFormat של Apache Commons CSV, והן כוללות שיטות שמקבלות תו בודד, מחרוזת או ערך בוליאני.

לדוגמה, כדי לציין נקודה-פסיק כמפריד, משתמשים ב-csv.format.withDelimiter=;. כדי להתעלם משורות ריקות, משתמשים בפונקציה csv.format.withIgnoreEmptyLines=true.
סוג קידוד הקובץ csv.fileEncoding=UTF-8

קבוצת התווים של Java שבה רוצים להשתמש. ברירת המחדל היא קבוצת התווים של הפלטפורמה.

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

מספקים את פרטי העמודות בקובץ ההגדרות.

הגדרה פרמטר
עמודות לאינדקס csv.csvColumns=movieId,movieTitle,description,actors,releaseDate,year,userratings...

שמות העמודות שייכללו באינדקס מקובץ ה-CSV. כברירת מחדל, השורה הראשונה בקובץ ה-CSV משמשת ככותרת. אם מציינים את csv.csvColumns, הוא מקבל עדיפות. כדי למנוע את הוספת השורה הראשונה לאינדקס כנתונים כשמגדירים את csv.csvColumns והשורה הראשונה מכילה כותרות, צריך להגדיר גם את csv.skipHeaderRecord=true.
עמודות מפתח ייחודיות csv.uniqueKeyColumns=movieId

העמודות שמשמשות ליצירת מזהה ייחודי. ברירת המחדל היא קוד הגיבוב של הרשומה.

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

הפעלת כתובות URL שניתן ללחוץ עליהן בתוצאות החיפוש.

הגדרה פרמטר
הפורמט של כתובת ה-URL של תוצאת חיפוש url.format=https://mymoviesite.com/movies/{0}

חובה. הפורמט שמשמש ליצירת כתובת ה-URL של התצוגה המפורטת.
פרמטרים של כתובת אתר url.columns=movieId

חובה. שמות העמודות ב-CSV שהערכים שלהן ישמשו ליצירת כתובת ה-URL של התצוגה של הרשומה.
פרמטרים של כתובת URL של תוצאות חיפוש שצריך להוסיף להם תווי Escape url.columnsToEscape=movieId

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

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

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

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

הפרמטרים האלה מתארים עמודות לאכלוס מטא-נתונים של פריטים.

הגדרה פרמטר
כותרת itemMetadata.title.field=movieTitle
itemMetadata.title.defaultValue=Gone with the Wind

מאפיין המטא-נתונים של כותרת המסמך. ברירת המחדל היא מחרוזת ריקה.
כתובת URL itemMetadata.sourceRepositoryUrl.field=url
itemMetadata.sourceRepositoryUrl.defaultValue=https://www.imdb.com/title/tt0031381/
מאפיין המטא-נתונים של כתובת ה-URL של המסמך בתוצאות החיפוש.
חותמת הזמן של היצירה itemMetadata.createTime.field=releaseDate
itemMetadata.createTime.defaultValue=1940-01-17

מאפיין המטא-נתונים של חותמת הזמן של יצירת המסמך.
זמן השינוי האחרון itemMetadata.updateTime.field=releaseDate
itemMetadata.updateTime.defaultValue=1940-01-17

מאפיין המטא-נתונים של חותמת הזמן של השינוי האחרון במסמך.
שפת המסמך itemMetadata.contentLanguage.field=languageCode
itemMetadata.contentLanguage.defaultValue=en-US

שפת התוכן של המסמכים שמתווספים לאינדקס.
סוג אובייקט הסכימה itemMetadata.objectType.field=type
itemMetadata.objectType.defaultValue=movie

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

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

הגדרה פרמטר
פורמטים נוספים של תאריך ושעה structuredData.dateTimePatterns=MM/dd/uuuu HH:mm:ssXXX
רשימה של תבניות נוספות שמופרדות באמצעות נקודה-פסיק.java.time.format.DateTimeFormatter הדפוסים האלה משמשים לניתוח של ערכי מחרוזות בשדות של תאריך או של תאריך ושעה במטא-נתונים או בסכימה. ערך ברירת המחדל הוא רשימה ריקה, אבל תמיד יש תמיכה בפורמטים RFC 3339 ו-RFC 1123.

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

הפרמטרים האלה מציינים איך לנתח עמודות בקובץ ה-CSV.

הגדרה פרמטר
דילוג על הכותרת העליונה csv.skipHeaderRecord=true

מתעלמים מהשורה הראשונה. ברירת המחדל היא False.
עמודות עם ערכים מרובים csv.multiValueColumns=genre,actors

שמות עמודות עם כמה ערכים.
תו הפרדה לעמודות עם כמה ערכים csv.multiValue.genre=;

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

איכות החיפוש

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

הגדרה פרמטר
שם התוכן contentTemplate.csv.title=movieTitle

שדה איכות החיפוש הכי גבוה הוא שם התוכן.
איכות חיפוש גבוהה בשדות תוכן contentTemplate.csv.quality.high=actors

שדות תוכן שמקבלים ערך גבוה של איכות החיפוש. ברירת המחדל היא מחרוזת ריקה.
איכות חיפוש נמוכה בשדות תוכן contentTemplate.csv.quality.low=genre

שדות תוכן שקיבלו ערך נמוך של איכות החיפוש. ברירת המחדל היא מחרוזת ריקה.
איכות חיפוש בינונית בשדות תוכן contentTemplate.csv.quality.medium=description

שדות תוכן שמקבלים ערך בינוני של איכות החיפוש. ברירת המחדל היא מחרוזת ריקה.
שדות תוכן שלא צוינו contentTemplate.csv.unmappedColumnsMode=IGNORE

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

  • ‫APPEND – הוספה של שדות תוכן לא מוגדרים לתבנית
  • ‫IGNORE – התעלמות משדות תוכן לא מוגדרים

ערך ברירת המחדל הוא APPEND.

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

המעבר הוא התהליך של גילוי תוכן. המחבר עובר על שורות CSV ומוסיף אותן לאינדקס באמצעות Indexing API. מחבר ה-CSV מבצע רק סריקות מלאות.

הגדרה פרמטר
מרווח חצייה schedule.traversalIntervalSecs=7200

המרווח בין סריקות מלאות בשניות. ברירת המחדל היא 86,400 (יום אחד).
העברה בזמן ההפעלה schedule.performTraversalOnStart=false

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

9. בחירת אפשרויות ACL

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

הגדרה פרמטר
מצב ACL defaultAcl.mode=fallback

חובה. המחבר תומך רק במצב חזרה.
שם ברירת המחדל של רשימת ACL defaultAcl.name=VIRTUAL_CONTAINER_FOR_CONNECTOR_1

אופציונלי. ההגדרה הזו מחליפה את השם של המאגר הווירטואלי שבו המחבר משתמש עבור רשימות ACL שמוגדרות כברירת מחדל. ערך ברירת המחדל הוא DEFAULT_ACL_VIRTUAL_CONTAINER. מומלץ לבטל את ברירת המחדל הזו אם כמה מחברים מבצעים אינדוקס של תוכן באותו מקור נתונים.
רשימת ACL ציבורית שמוגדרת כברירת מחדל defaultAcl.public=true

הגדרה של גישה לכל המאגר כדומיין ציבורי. ברירת המחדל היא False.
קבוצות נפוצות עם הרשאת קריאה ב-ACL defaultAcl.readers.groups=google:group1, group2
קוראים נפוצים ב-ACL defaultAcl.readers.users=user1, user2, google:user3
רשימות ACL נפוצות שדוחות קוראים בקבוצה defaultAcl.denied.groups=group3
Common Acl denied readers defaultAcl.denied.users=user4, user5
גישה לכל הדומיין כדי לציין שכל רשומה באינדקס תהיה נגישה לכל משתמש בדומיין, צריך להגדיר את שתי האפשרויות הבאות עם ערכים:
  • defaultAcl.mode=fallback
  • defaultAcl.public=true
רשימת ACL מוגדרת נפוצה כדי להגדיר ACL משותף לכל רשומה, מגדירים את הפרמטרים הבאים:
  • defaultAcl.mode=fallback
  • defaultAcl.public=false
  • defaultAcl.readers.groups=google:group1, group2
  • defaultAcl.readers.users=user1, user2, google:user3
  • defaultAcl.denied.groups=group3
  • defaultAcl.denied.users=user4, user5

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

משתמש או קבוצה שמוגדרים כברירת מחדל הם מחרוזת ריקה. אפשר לספק אפשרויות של משתמשים וקבוצות רק אם defaultAcl.public הוא false. אם יש כמה קבוצות ומשתמשים, צריך להשתמש ברשימה מופרדת בפסיקים.

אם defaultAcl.mode הוא none, אי אפשר לחפש רשומות בלי רשימות ACL פרטניות.

הגדרת סכימה

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

לדוגמה, קובץ CSV עם הפרטים הבאים על סרטים:

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

על סמך המבנה הזה, אפשר להגדיר את הסכימה הבאה למקור הנתונים:

{
  "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

הפעלת המחבר

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

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

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