Это руководство предназначено для администраторов соединителя 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 (который содержит идентификатор сервисного аккаунта)
- Идентификатор источника данных Google Workspace
Обычно эти учетные данные может предоставить администратор Google Workspace домена.
Этапы развертывания
Чтобы развернуть соединитель CSV Google Cloud Search, выполните следующие действия:
- Установите программное обеспечение для подключения Google Cloud Search CSV.
- Укажите конфигурацию соединителя CSV.
- Настройте доступ к источнику данных Google Cloud Search
- Настроить доступ к файлу CSV
- Укажите имена столбцов для индексирования, уникальные ключевые столбцы и столбцы даты и времени.
- Укажите столбцы для использования в интерактивных URL-адресах результатов поиска.
- Укажите метаданные и форматы столбцов.
- Расписание обхода данных
- Укажите параметры списка управления доступом (ACL)
1. Установите SDK
Установите SDK в локальный репозиторий Maven.
Клонируйте репозиторий SDK с GitHub.
$ git clone https://github.com/google-cloudsearch/connector-sdk.git $ cd connector-sdk/csv
Проверьте нужную версию SDK:
$ git checkout tags/v1-0.0.3
Создайте соединитель:
$ mvn package
Скопируйте 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 рекомендует назвать файл конфигурации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 . Значения формата включают: |
Модификатор формата файла | csv.format. withMethod = value Изменение способа обработки файла Cloud Search. Возможные методы взяты из класса Apache Commons CSV CSVFormat и включают те, которые принимают один символ, строку или логическое значение. Например, чтобы указать точку с запятой в качестве разделителя, используйте |
Тип кодировки файла | csv.fileEncoding= UTF-8 Набор символов Java, который будет использоваться при чтении файла Cloud Search. Если не указано, Cloud Search использует набор символов платформы по умолчанию. |
5. Укажите имена столбцов для индексирования и уникальные ключевые столбцы.
Чтобы соединитель мог получать доступ к файлам CSV и индексировать их, необходимо предоставить информацию об определениях столбцов в файле конфигурации. Если файл конфигурации не содержит параметров, определяющих имена индексируемых столбцов и уникальные ключевые столбцы, используются значения по умолчанию.
Параметр | Параметр |
Столбцы для индексации | csv.csvColumns= movieId,movieTitle,description,actors,releaseDate,year,userratings... Имена столбцов, которые будут индексироваться из CSV-файла. Если |
Уникальные ключевые столбцы | 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.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 Как соединитель обрабатывает неуказанные поля содержимого. Допустимые значения:
|
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 |
Полный доступ к домену | Чтобы указать, что каждая индексированная запись будет общедоступна для каждого пользователя в домене, установите для обеих следующих опций значения:
|
Общий определенный ACL | Чтобы указать один ACL для каждой записи хранилища данных, установите все следующие значения параметров:
|
Определение схемы
Cloud Search позволяет индексировать и обслуживать структурированный и неструктурированный контент. Чтобы поддерживать запросы структурированных данных к вашим данным, вам необходимо настроить схему для вашего источника данных .
После определения CSV Connector может ссылаться на определенную схему для создания запросов на индексирование. В качестве наглядного примера рассмотрим файл CSV, содержащий информацию о фильмах.
Предположим, входной CSV-файл имеет следующее содержимое.
- идентификатор фильма
- фильмНазвание
- описание
- год
- Дата выпуска
- актеры (несколько значений, разделенных запятой (,))
- жанр (несколько значений)
- рейтинги
На основе приведенной выше структуры данных вы можете определить схему источника данных, в соответствии с которой вы хотите индексировать данные из файла 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
.