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

Внимание: эталонные коннекторы Cloud Search предоставляются «как есть» в виде примеров кода для создания собственных рабочих коннекторов. Этот пример кода требует существенной доработки и тестирования перед использованием в экспериментальных или производственных средах. Для использования в производственной среде мы настоятельно рекомендуем обратиться за помощью к одному из наших партнеров Cloud Search. Для получения помощи в поиске подходящего партнера свяжитесь со своим менеджером аккаунта Google.

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

Данное руководство содержит инструкции по выполнению следующих ключевых задач:

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

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

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

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

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

Коннектор можно установить на Linux или Windows. Перед развертыванием убедитесь, что у вас есть следующие компоненты:

• На компьютере, где запущен коннектор, установлена ​​Java JRE 1.8.
• Информация о Google Workspace для установления соединений:
  • Закрытый ключ Google Workspace (содержащий идентификатор учетной записи службы).
  • Идентификатор источника данных Google Workspace .

Как правило, эти учетные данные предоставляет администратор 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 Формат файла. Возможные значения берутся из класса 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 для использования. По умолчанию используется кодировка символов платформы.

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	url.columns= movieId Обязательно. Названия столбцов CSV-файла, значения которых будут использоваться для генерации URL-адреса просмотра записи.
Параметры URL-адресов результатов поиска для экранирования	url.columnsToEscape= movieId Необязательно. Названия столбцов CSV-файла, значения которых будут экранированы для генерации допустимого 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 — добавить в шаблон неуказанные поля содержимого. ИГНОРИРОВАТЬ — игнорировать неуказанные поля содержимого Значение по умолчанию — APPEND.

8. Планирование обхода данных

Обход — это процесс обнаружения контента. Коннектор обходит строки CSV-файла и индексирует их с помощью API индексирования. Коннектор CSV выполняет только полный обход.

Параметр	Параметр
Интервал прохождения	schedule.traversalIntervalSecs = 7200 Интервал между полными проходами в секундах. Значение по умолчанию — 86400 (один день).
Обход на этапе запуска	schedule.performTraversalOnStart = false Коннектор выполняет обход при запуске, а не ждет истечения первого интервала. Значение по умолчанию — true.

9. Укажите параметры ACL.

Коннектор использует списки контроля доступа (ACL) для управления доступом. Если ваш репозиторий предоставляет списки ACL, загрузите их. В противном случае настройте списки ACL по умолчанию. Установите значение defaultAcl.mode , отличное от none .

Параметр	Параметр
режим ACL	defaultAcl.mode =fallback Обязательно. Коннектор поддерживает только резервный режим.
Имя ACL по умолчанию	defaultAcl.name = VIRTUAL_CONTAINER_FOR_CONNECTOR_1 Необязательный параметр. Переопределяет имя виртуального контейнера, используемого коннектором для списков контроля доступа по умолчанию. Значение по умолчанию — 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
Обычная передняя крестообразная связка (ПКС) недоступна для читателей.	defaultAcl.denied.users = user4, user5
Доступ ко всему домену	Чтобы указать, что каждая проиндексированная запись должна быть общедоступна для каждого пользователя в домене, задайте значения для обоих следующих параметров: defaultAcl.mode =fallback defaultAcl.public =true
Общепринятое определение передней крестообразной связки	Чтобы задать общий список контроля доступа (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. Дата выпуска
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"
            }
          }
        }
      ]
    }
  ]
}

Примечание: Использование схемы необязательно, но рекомендуется для повышения качества поиска и включения пользовательских операторов. В качестве альтернативы вы можете настроить коннектор для индексирования строк CSV как неструктурированного HTML.

Пример файла конфигурации

В приведенном ниже примере конфигурационного файла показаны пары 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 .