Развертывание соединителя 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-коннектор также поддерживает управление доступом пользователей к контенту в результатах поиска с помощью списков контроля доступа (ACL).

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

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

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

  • Закрытый ключ Google Workspace (который содержит идентификатор учетной записи службы)
  • Идентификатор источника данных Google Workspace

  Обычно эти учетные данные может предоставить администратор домена 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 не требовались дополнительные параметры командной строки.

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

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

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

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

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

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

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

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

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

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

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

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

• Параметры конфигурации метаданных
• Форматы столбцов
• Качество поиска

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

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

Форматы даты и времени

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

Форматы столбцов

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

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

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

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

8. Планирование прохождения данных

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

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

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

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

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

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

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

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

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

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

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

1. movieId
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

Подробное описание каждого параметра см. в справочнике «Параметры конфигурации».

Запустите CSV-коннектор Cloud Search

Чтобы запустить коннектор из командной строки, введите следующую команду:

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

По умолчанию журналы коннектора доступны в стандартном выводе. Вы можете записывать журналы в файлы, указав logging.properties .