פריסת מחבר 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

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

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.