Развертывание соединителя CSV

Это руководство предназначено для администраторов соединителя Google Cloud Search CSV (значения, разделенные запятыми), то есть всех, кто отвечает за загрузку, настройку, запуск и мониторинг соединителя.

В это руководство включены инструкции по выполнению основных задач, связанных с развертыванием соединителя CSV:

  • Загрузите программное обеспечение для подключения Google Cloud Search CSV.
  • Настройте соединитель для использования с определенным источником данных CSV.
  • Развертывание и запуск соединителя

Чтобы понять концепции, изложенные в этом документе, вы должны быть знакомы с основами Google Workspace, CSV-файлами и списками управления доступом (ACL).

Обзор коннектора CSV Google Cloud Search

Коннектор Cloud Search CSV работает с любым текстовым файлом со значениями, разделенными запятыми (CSV). В файле CSV хранятся табличные данные, и каждая строка файла представляет собой запись данных.

Коннектор CSV Google Cloud Search извлекает отдельные строки из CSV-файла и индексирует их в Cloud Search через API индексирования Cloud Search. После успешной индексации отдельные строки из CSV-файлов доступны для поиска с помощью клиентов Cloud Search или API запросов Cloud Search. Соединитель CSV также поддерживает управление доступом пользователей к содержимому результатов поиска с помощью списков управления доступом.

Соединитель Google Cloud Search CSV можно установить в Linux или Windows. Прежде чем развертывать CSV-коннектор Google Cloud Search, убедитесь, что у вас есть следующие необходимые компоненты:

  • Java JRE 1.8 установлена ​​на компьютере, на котором работает соединитель Google Cloud Search CSV.

  • Информация Google Workspace, необходимая для установления связи между Google Cloud Search и источником данных:

    Обычно эти учетные данные может предоставить администратор Google Workspace домена.

Этапы развертывания

Чтобы развернуть соединитель CSV Google Cloud Search, выполните следующие действия:

  1. Установите программное обеспечение для подключения Google Cloud Search CSV.
  2. Укажите конфигурацию соединителя CSV.
  3. Настройте доступ к источнику данных Google 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. Проверьте нужную версию 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 и индексировать соответствующее содержимое, необходимо сначала создать его файл конфигурации.

Чтобы создать файл конфигурации:

  1. Откройте текстовый редактор по вашему выбору и назовите файл конфигурации.
    Добавьте пары ключ = значение к содержимому файла, как описано в следующих разделах.
  2. Сохраните и назовите файл конфигурации.
    Google рекомендует назвать файл конфигурации connector-config.properties , чтобы для запуска соединителя не требовалось никаких дополнительных параметров командной строки.

Поскольку вы можете указать путь к файлу конфигурации в командной строке, стандартное расположение файла не требуется. Однако храните файл конфигурации в том же каталоге, что и соединитель, чтобы упростить отслеживание и запуск соединителя.

Чтобы убедиться, что соединитель распознает ваш файл конфигурации, укажите его путь в командной строке. В противном случае соединитель использует connector-config.properties в вашем локальном каталоге в качестве имени файла по умолчанию. Информацию об указании пути конфигурации в командной строке см. в разделе Запуск соединителя Cloud Search CSV .

3. Настройте доступ к источнику данных Google Cloud Search.

Первые параметры, которые должен указывать каждый файл конфигурации, — это те, которые необходимы для доступа к источнику данных Cloud Search, как показано в следующей таблице. Как правило, вам потребуется идентификатор источника данных, идентификатор учетной записи службы и путь к файлу закрытого ключа учетной записи службы, чтобы настроить доступ соединителя к Cloud Search. Шаги, необходимые для настройки источника данных, описаны в разделе «Управление сторонними источниками данных».

Параметр Параметр
Идентификатор источника данных api.sourceId= 1234567890abcdef

Необходимый. Идентификатор источника Google Cloud Search, настроенный администратором Google Workspace, как описано в разделе «Управление сторонними источниками данных».

Путь к файлу закрытого ключа сервисного аккаунта api.serviceAccountPrivateKeyFile= ./PrivateKey.json

Необходимый. Ключевой файл учетной записи службы Google Cloud Search, обеспечивающий доступность CSV-коннектора Google Cloud Search.

Идентификатор источника идентификационной информации api.identitySourceId= x0987654321

Требуется при использовании внешних пользователей и групп. Идентификатор источника идентификации Google Cloud Search, установленный администратором Google Workspace.

4. Настройте параметры файла CSV.

Прежде чем соединитель сможет пройти через CSV-файл и извлечь из него данные для индексации, необходимо определить путь к файлу. Вы также можете указать формат файла и тип кодировки файла. Добавьте следующие параметры, чтобы указать свойства файла CSV в файле конфигурации.

Параметр Параметр
Путь к CSV-файлу csv.filePath= ./movie_content.csv

Необходимый. Путь к CSV-файлу, к которому нужно получить доступ, и извлечь содержимое для индексации.

Формат файла csv.format= DEFAULT

Формат файла. Возможные значения взяты из класса Apache Commons CSV CSVFormat .

Значения формата включают: DEFAULT , EXCEL , INFORMIX_UNLOAD , INFORMIX_UNLOAD_CSV , MYSQL , RFC4180 , ORACLE , POSTGRESQL_CSV , POSTGRESQL_TEXT и TDF . Если не указано, Cloud Search использует DEFAULT .

Модификатор формата файла csv.format. withMethod = value

Изменение способа обработки файла Cloud Search. Возможные методы взяты из класса Apache Commons CSV CSVFormat и включают те, которые принимают один символ, строку или логическое значение.

Например, чтобы указать точку с запятой в качестве разделителя, используйте csv.format.withDelimiter=; . Чтобы игнорировать пустые строки, используйте csv.format.withIgnoreEmptyLines=true .

Тип кодировки файла csv.fileEncoding= UTF-8

Набор символов Java, который будет использоваться при чтении файла Cloud Search. Если не указано, Cloud Search использует набор символов платформы по умолчанию.

5. Укажите имена столбцов для индексирования и уникальные ключевые столбцы.

Чтобы соединитель мог получать доступ к файлам CSV и индексировать их, необходимо предоставить информацию об определениях столбцов в файле конфигурации. Если файл конфигурации не содержит параметров, определяющих имена индексируемых столбцов и уникальные ключевые столбцы, используются значения по умолчанию.

Параметр Параметр
Столбцы для индексирования csv.csvColumns= movieId,movieTitle,description,actors,releaseDate,year,userratings...

Имена столбцов, которые будут индексироваться из CSV-файла. Если csv.csvColumns не установлен, то в качестве заголовка используется первая строка CSV-файла. Если установлен csv.csvColumns , он имеет приоритет над первой строкой CSV. Если вы установили csv.csvColumns и первая строка файла CSV представляет собой список имен столбцов, вам необходимо установить csv.skipHeaderRecord=true чтобы избежать попыток индексировать первую строку как данные. Значения по умолчанию — это столбцы в строке заголовка файла.

Уникальные ключевые столбцы csv.uniqueKeyColumns= movieId

Столбцы CSV, значения которых будут использоваться для создания уникального идентификатора каждой записи. Если не указано, в качестве уникального ключа следует использовать хэш записи CSV. Значением по умолчанию является хэш-код записи.

6. Укажите столбцы, которые будут использоваться в интерактивных URL-адресах результатов поиска.

Когда пользователь выполняет поиск с помощью Google Cloud Search, он в ответ показывает страницу результатов, содержащую кликабельные URL-адреса для каждого результата. Чтобы включить эту функцию, необходимо добавить в файл конфигурации параметр, показанный в следующей таблице.

Параметр Параметр
Формат URL результатов поиска url.format= https://mymoviesite.com/movies/{0}

Необходимый. Формат создания URL-адреса представления для содержимого CSV.

Параметры URL результатов поиска. url.columns= movieId

Необходимый. Имена столбцов CSV, значения которых будут использоваться для создания URL-адреса просмотра записи.

Параметры URL результатов поиска, которые нужно экранировать url.columnsToEscape= movieId

Необязательный. Имена столбцов CSV, значения которых будут экранированы URL-адресом для создания действительного URL-адреса просмотра.

7. Укажите метаданные, форматы столбцов, качество поиска.

В файл конфигурации можно добавить параметры, которые определяют:

Параметры конфигурации метаданных

Параметры конфигурации метаданных описывают столбцы CSV, используемые для заполнения метаданных элемента. Если файл конфигурации не содержит этих параметров, используются значения по умолчанию. В следующей таблице показаны эти параметры.

Параметр Параметр
Заголовок 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.skipHeaderRecord=true

Логическое значение. Игнорируйте запись заголовка (первая строка) в файле CSV. Если вы установили csv.csvColumns и в файле CSV есть строка заголовка, вам необходимо установить skipHeaderRecord=true . Это предотвращает индексацию первой строки файла как данных. Если в файле CSV нет строки заголовка, установите skipHeaderRecord=false . Значение по умолчанию — ложь.

Столбцы с несколькими значениями csv.multiValueColumns= genre,actors

Имена столбцов в CSV-файле, имеющие несколько значений. Значение по умолчанию — пустая строка.

Разделитель для столбцов с несколькими значениями csv.multiValue.genre= ;

Разделитель для столбцов с несколькими значениями. Разделителем по умолчанию является запятая.

Качество поиска

Соединитель Cloud Search CSV позволяет автоматически форматировать HTML для полей данных. Ваш соединитель определяет поля данных в начале выполнения соединителя, а затем использует шаблон контента для форматирования каждой записи данных перед ее загрузкой в ​​Cloud Search.

Шаблон контента определяет важность каждого значения поля для поиска. Поле заголовка является обязательным и определяется как имеющее наивысший приоритет. Вы можете назначить уровни важности качества поиска для всех остальных полей контента: высокий, средний или низкий. Любое поле контента, не определенное в определенной категории, по умолчанию имеет низкий приоритет. В следующей таблице показаны эти параметры.

Параметр Параметр
Название контента 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 — игнорировать неуказанные поля содержимого.

    Значение по умолчанию — ДОБАВИТЬ.

8. Запланируйте обход данных

Обход — это процесс коннектора по обнаружению содержимого из источника данных, в данном случае из CSV-файла. При работе соединителя CSV он будет проходить по строкам CSV-файла и индексировать каждую строку в Cloud Search через API индексирования.

Полный обход индексирует все столбцы в файле. Инкрементальный обход индексирует только те столбцы, которые были добавлены или изменены с момента предыдущего обхода. Соединитель CSV выполняет только полный обход. Он не выполняет инкрементальные обходы.

Параметры планирования определяют, как часто соединитель ожидает между проходами. Если файл конфигурации не содержит параметров планирования, используются значения по умолчанию. В следующей таблице показаны эти параметры.

Параметр Параметр
Полный обход после интервала Schedule.traversalIntervalSecs = 7200

Соединитель выполняет полный обход после заданного интервала. Укажите интервал между обходами в секундах. Значение по умолчанию — 86400 (количество секунд в одном дне).

Полный обход при запуске соединителя Schedule.performTraversalOnStart = false

Соединитель выполняет полный обход при запуске соединителя, а не ждет истечения первого интервала. Значение по умолчанию — true.

9. Укажите параметры списка контроля доступа (ACL).

Соединитель Google Cloud Search CSV поддерживает разрешения через списки управления доступом для управления доступом к содержимому CSV-файла в результатах поиска. Доступно несколько вариантов ACL, позволяющих защитить доступ пользователей к индексированным записям.

Если в вашем репозитории есть индивидуальная информация ACL, связанная с каждым документом, загрузите всю информацию ACL, чтобы контролировать доступ к документу в Cloud Search. Если ваш репозиторий предоставляет частичную информацию ACL или не предоставляет ее вообще, вы можете указать информацию ACL по умолчанию в следующих параметрах, которые SDK предоставляет соединителю.

Соединитель использует списки ACL по умолчанию, включенные в файле конфигурации. Чтобы включить списки ACL по умолчанию, установите для defaultAcl.mode любой режим, кроме none , и настройте его с помощью defaultAcl.*

Параметр Параметр
Режим ACL defaultAcl.mode = резервный вариант

Необходимый. Соединитель CSV использует функциональность ACL по умолчанию. Коннектор поддерживает только резервный режим.

Имя ACL по умолчанию defaultAcl.name = VIRTUAL_CONTAINER_FOR_CONNECTOR_1

Необязательный. Позволяет переопределить имя виртуального контейнера, используемое соединителем для настройки списков управления доступом по умолчанию. Значение по умолчанию — «DEFAULT_ACL_VIRTUAL_CONTAINER». Возможно, вы захотите переопределить это значение, если несколько соединителей индексируют содержимое в одном источнике данных.

Публичный список управления доступом по умолчанию defaultAcl.public = true

По умолчанию ACL, используемый для всего репозитория, настроен на общедоступный доступ. Значение по умолчанию — ложь.

Общие считыватели групп ACL defaultAcl.readers.groups = google: group1, group2
Общие читатели ACL defaultAcl.readers.users = user1, user2, google: user3
Общий список ACL запретил чтение групп defaultAcl.denied.groups = group3
Common Acl отказал читателям defaultAcl.denied.users = user4, user5
Полный доступ к домену Чтобы указать, что каждая индексированная запись будет общедоступна для каждого пользователя в домене, установите для обеих следующих опций значения:
  • defaultAcl.mode = резервный вариант
  • defaultAcl.public = истина
Общий определенный ACL Чтобы указать один ACL для каждой записи хранилища данных, установите все следующие значения параметров:
  • defaultAcl.mode = резервный вариант
  • defaultAcl.public = ложь
  • 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.

Определение схемы

Cloud Search позволяет индексировать и обслуживать структурированный и неструктурированный контент. Чтобы поддерживать запросы структурированных данных к вашим данным, вам необходимо настроить схему для вашего источника данных .

После определения CSV Connector может ссылаться на определенную схему для создания запросов на индексирование. В качестве наглядного примера рассмотрим файл CSV, содержащий информацию о фильмах.

Предположим, входной CSV-файл имеет следующее содержимое.

  1. идентификатор фильма
  2. фильмНазвание
  3. описание
  4. год
  5. Дата выпуска
  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 .