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

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

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

Важные замечания.

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

Системные требования

Системные требования
Операционная система Windows или Linux
База данных SQL Любая база данных SQL с драйвером, совместимым с JDBC 4.0 или более поздней версии, включая следующее:
  • MS SQL Server (2008, 2012, 2014, 2016)
  • Oracle (11g, 12c)
  • Google Cloud SQL
  • MySQL
Software Драйвер JDBC для соединителя, который будет использоваться для доступа к базе данных (загружается и устанавливается отдельно)

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

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

Предварительные требования.

Прежде чем развернуть коннектор базы данных Cloud Search, соберите следующую информацию:

Шаг 1. Загрузите и создайте программное обеспечение соединителя базы данных.

  1. Клонируйте репозиторий соединителя с GitHub. 
    $ git clone https://github.com/google-cloudsearch/database-connector.git
$ cd database-connector
  2. Ознакомьтесь с желаемой версией разъема:
    $ git checkout tags/v1-0.0.3
  3. Создайте соединитель. 
    $ mvn package
    Чтобы пропустить тесты при построении коннектора, используйте mvn package -DskipTests .
  4. Скопируйте zip-файл соединителя в локальный каталог установки и разархивируйте его: 
    $ cp target/google-cloudsearch-database-connector-v1-0.0.3.zip installation-dir
$ cd installation-dir
$ unzip google-cloudsearch-database-connector-v1-0.0.3.zip
$ cd google-cloudsearch-database-connector-v1-0.0.3

Шаг 2. Настройте соединитель базы данных.

  1. Создайте текстовый файл и назовите его connector-config.properties (по умолчанию) или аналогичное. Google рекомендует называть файлы конфигурации с расширением .properties или .config и хранить файл в том же каталоге, что и соединитель. Если вы используете другое имя или путь, необходимо указать путь при запуске соединителя.
  2. Добавьте параметры в виде пар ключ/значение в содержимое файла. В файле конфигурации должны быть указаны параметры доступа к источнику данных, доступа к базе данных, оператор SQL полного обхода базы данных, заголовок поля содержимого и определения столбцов. Вы также можете настроить другое поведение соединителя с помощью дополнительных параметров. Например: 
    # Required parameters for data source access
api.sourceId=1234567890abcdef
api.identitySourceId=0987654321lmnopq
api.serviceAccountPrivateKeyFile=./PrivateKey.json
#
# Required parameters for database access
db.url=jdbc:mysql://localhost:3306/mysql_test
db.user=root
db.password=passw0rd
#
# Required full traversal SQL statement parameter
db.allRecordsSql=select customer_id, first_name, last_name, phone, change_timestamp from address_book
#
# Required parameters for column definitions and URL format
db.allColumns=customer_id, first_name, last_name, phone, change_timestamp
db.uniqueKeyColumns=customer_id
url.columns=customer_id
#
# Required content field parameter
contentTemplate.db.title=customer_id
#
# Optional parameters to set ACLs to "entire domain" access
defaultAcl.mode=fallback
defaultAcl.public=true
#
# Optional parameters for schedule traversals
schedule.traversalIntervalSecs=36000
schedule.performTraversalOnStart=true
schedule.incrementalTraversalIntervalSecs=3600

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

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

    Если применимо, укажите свойства объекта схемы в параметрах запроса SQL обхода. Обычно вы можете добавлять псевдонимы в оператор SQL. Например, если у вас есть база данных фильмов и схема источника данных содержит определение свойства с именем «ActorName», оператор SQL может иметь форму: SELECT …, last_name AS ActorName, … FROM … .

Шаг 3. Запустите соединитель базы данных.

В следующем примере предполагается, что необходимые компоненты расположены в локальном каталоге системы Linux.

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

java \
   -cp "google-cloudsearch-database-connector-v1-0.0.3.jar:mysql-connector-java-5.1.41-bin.jar" \
   com.google.enterprise.cloudsearch.database.DatabaseFullTraversalConnector \
   [-Dconfig=mysql.config]

Где:

  • google-cloud-search-database-connector-v1-0.0.3.jar — это соединитель базы данных.jar-файл
  • mysql-connector-java-5.1.41-bin.jar — это драйвер JDBC, используемый для доступа к базе данных
  • mysql.config — это файл конфигурации с произвольным именем. Чтобы убедиться, что соединитель распознает ваш файл конфигурации, укажите его путь в командной строке. В противном случае соединитель использует connector-config.properties в вашем локальном каталоге в качестве имени файла по умолчанию.

Соединитель сообщает об ошибках конфигурации по мере их обнаружения. О некоторых ошибках сообщается при инициализации соединителя, например, когда столбец базы данных определен как часть содержимого записи (в db.allColumns ), но этот столбец не используется в SQL-запросе обхода базы данных (в db.allRecordsSql ). ). Другие ошибки обнаруживаются и сообщаются только тогда, когда соединитель пытается получить доступ к базе данных для первого обхода, например неверный синтаксис оператора SQL.

Справочник по параметрам конфигурации

Параметры доступа к источнику данных

Настройка параметра
Идентификатор источника данных api.sourceId = source-ID

Обязательно. Идентификатор источника Cloud Search, настроенный администратором Google Workspace.

Идентификатор источника удостоверений api.identitySourceId = identity-source-ID

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

Учетная запись службы api.serviceAccountPrivateKeyFile = path-to-private-key

. Обязательно. Путь к файлу ключа аккаунта службы Cloud Search, созданному администратором Google Workspace.

Параметры доступа к базе данных

Настройка параметра
URL-адрес базы данных db.url = database-URL

Требуется. Полный путь к базе данных, к которой осуществляется доступ, например jdbc:mysql://127.0.0.1/dbname .

Имя пользователя и пароль базы данных db.user = username
db.password = password

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

Драйвер JDBC db.driverClass = oracle.jdbc.OracleDriver

Требуется только в том случае, если драйвер JDBC 4.0 еще не указан в пути к классам.

Параметры запроса SQL

Соединитель просматривает записи базы данных с помощью запросов SQL SELECT в файле конфигурации. Вы должны настроить запрос полного обхода; запросы для дополнительных обходов не являются обязательными.

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

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

Соединитель выполняет эти обходы в соответствии с расписаниями, которые вы определяете в параметрах расписания обхода .

Параметр установки
Запрос полного обхода db.allRecordsSql = SELECT column-1 [, column-2 ,...] FROM database-name

Обязательно. Запрос выполняется для каждого полного обхода.

В этом запросе должно присутствовать каждое имя столбца, которое соединитель будет использовать в любом качестве (содержимое, уникальный идентификатор, списки управления доступом). При запуске соединитель выполняет некоторые предварительные проверки для обнаружения ошибок и упущений. По этой причине не используйте общий запрос « SELECT * FROM… ».

Полное разбиение на страницы db.allRecordsSql.pagination = {none | offset}

Значение может быть:

  • none : не использовать
  • смещение нумерации страниц: использовать нумерацию страниц по смещению строки

    . Чтобы использовать нумерацию страниц по смещению, в запросе SQL должен быть знак вопроса ( ? ) для смещения строки, начиная с нуля. При каждом полном обходе запрос выполняется повторно, пока результаты не будут возвращены.

Запрос добавочного обхода db.incrementalUpdateSql = SELECT column-1 [, column-2 ,...] FROM database-name WHERE last_update_time > ?

Требуется, если вы планируете инкрементные обходы .

Знак "?" в запросе является обязательным заполнителем для значения отметки времени. Соединитель использует метку времени для отслеживания изменений между SQL-запросами добавочного обхода.

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

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

Часовой пояс базы данных db.timestamp.timezone = America/Los_Angeles

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

Примеры SQL-запросов обхода.

  • Базовый запрос полного обхода, который считывает каждую интересующую запись в базе данных сотрудников для индексации: 
    db.allRecordsSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field \
    FROM employee
  • Укажите нумерацию страниц по смещению и разбейте полный обход на несколько запросов.

    Для SQL Server 2012 или Oracle 12c (стандартный синтаксис SQL 2008):

    db.allRecordsSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field \
    FROM employee \
    ORDER BY customer_id OFFSET ? ROWS FETCH FIRST 1000 ROWS ONLY
db.allRecordsSql.pagination = offset

    или для MySQL или Google Cloud SQL:

    db.allRecordsSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field \
    FROM employee \
    ORDER BY customer_id LIMIT 1000 OFFSET ?
db.allRecordsSql.pagination = offset
  • Полный запрос обхода, который применяет отдельные списки ACL с псевдонимами: 
    db.allRecordsSql = SELECT customer_id, first_name, last_name,  employee_id, interesting_field, last_update_time, \
     permitted_readers AS readers_users, \
     denied_readers AS denied_users, \
     permitted_groups AS readers_groups, \
     denied_groups AS denied_groups \
     FROM employee
  • Базовый запрос инкрементного обхода: 
    db.incrementalUpdateSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field, last_update_time \
     FROM employee \
     WHERE last_update_time > ?
  • Запрос добавочного обхода, который применяет отдельные списки ACL с псевдонимами: 
    db.incrementalUpdateSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field, last_update_time, \
     permitted_readers AS readers_users, \
     denied_readers AS denied_users, \
     permitted_groups AS readers_groups, \
     denied_groups AS denied_groups \
     FROM employee \
     WHERE last_update_time > ?
  • Запрос добавочного обхода, использующий временную метку базы данных, а не текущее время: 
    db.incrementalUpdateSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field, \
     last_update_time AS timestamp_column \
     FROM employee \
     WHERE last_update_time > ?

Параметры определения столбца

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

Параметр установки
Все столбцы db.allColumns = column-1 , column-2 , ... column-N

Обязательно. Идентифицирует все столбцы, необходимые в SQL-запросе при доступе к базе данных. Столбцы, определенные с помощью этого параметра, должны быть явно указаны в запросах. Все остальные параметры определения столбца сравниваются с этим набором столбцов.

Пример:

db.allColumns = customer_id, first_name, last_name, phone, change_timestamp
Столбцы с уникальным ключом db.uniqueKeyColumns = column-1 [, column-2 ]

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

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

Примеры:

db.uniqueKeyColumns = customer_id
# or
db.uniqueKeyColumns = last_name, first_name
Столбец URL-ссылки url.columns = column-1 [, column-2 ]

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

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

Формат URL- url.format = https://www.example.com/{0}

Определяет формат URL-адреса представления. Нумерованные параметры относятся к столбцам, указанным в db.columns , по порядку, начиная с нуля.

Если не указано, по умолчанию используется « {0}».

Примеры приведены в этой таблице.

Столбцы в процентном кодировании для URL-адреса url.columnsToEscape = column-1 [, column-2 ]

Указывает столбцы из db.columns , значения которых будут кодироваться в процентах перед включением их в форматированную строку URL-адреса.

Примеры столбцов URL-адресов.

Чтобы указать столбцы, используемые в запросах обхода, и формат URL-адреса представления:

  • Чтобы использовать статический URL-адрес, не используя значения записей базы данных: 
    url.format = https://www.example.com
  • Чтобы использовать одно значение столбца, которое является URL-адресом представления: 
    url.format = {0}
url.columns = customer_id
  • Чтобы использовать одно значение столбца, которое подставляется в URL-адрес представления в позиции {0}: 
    url.format = https://www.example.com/customer/id={0}
url.columns = customer_id
url.columnsToEscape = customer_id
  • Чтобы использовать несколько значений столбца для создания URL-адреса представления (столбцы зависят от порядка): 
    url.format = {1}/customer={0}
url.columns = customer_id, linked_url
url.columnsToEscape = customer_id

Поля содержимого

Используйте параметры содержимого, чтобы определить, какие значения записей должны быть частью содержимого, доступного для поиска.

.
Параметр настройки
Столбец поиска высочайшего качества. contentTemplate.db.title = column-name

Обязательно. Столбец высочайшего качества для поисковой индексации и приоритезации результатов.

Приоритизация столбцов для поиска contentTemplate.db.quality.high = column-1 [, column-2 ...]
contentTemplate.db.quality.medium = column-1 [, column-2 ...]
contentTemplate.db.quality.low = column-1 [, column-2 ...]

Назначьте столбцы контента (кроме столбца, установленного для contentTemplate.db.title ) как поля высокого, среднего или низкого качества поиска. Неуказанные столбцы по умолчанию имеют низкий уровень.

Столбцы данных содержимого db.contentColumns = column-1 [, column-2 ...]

Укажите столбцы содержимого в базе данных. Они форматируются и загружаются в Cloud Search как содержимое документа, доступное для поиска.

Если вы не укажете значение, по умолчанию будет « * », что означает, что для содержимого следует использовать все столбцы.

Столбец больших двоичных объектов db.blobColumn = column-name

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

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