Implantar um conector de banco de dados

Aviso: os conectores de referência do Cloud Search são fornecidos "no estado em que se encontram" como exemplo de código para uso na criação dos seus próprios conectores de trabalho. Este exemplo de código requer personalização e testes substanciais antes de ser usado em ambientes de prova de conceito ou produção. Para uso em produção, é altamente recomendável pedir ajuda a um dos nossos parceiros do Cloud Search. Se precisar de mais ajuda para encontrar um parceiro do Cloud Search adequado, entre em contato com o gerente de contas do Google.

É possível configurar o Google Cloud Search para descobrir e indexar dados dos bancos da sua organização usando o conector de banco de dados do Google Cloud Search.

Considerações importantes

É possível instalar e executar o conector de banco de dados do Cloud Search em quase todos os ambientes onde aplicativos Java podem ser executados, desde que o conector tenha acesso à Internet e ao banco de dados.

Requisitos do sistema

Requisitos do sistema
Sistema operacional Windows ou Linux
Banco de dados SQL Qualquer banco de dados SQL com um driver compatível com JDBC 4.0 ou posterior, incluindo o seguinte:
  • MS SQL Server (2008, 2012, 2014, 2016);
  • Oracle (11g, 12c)
  • Google Cloud SQL
  • MySQL
Software Driver JDBC para que o conector use para acessar o banco de dados (transferido por download e instalado separadamente)

Implantar o conector

As etapas a seguir descrevem como instalar o conector e configurá-lo para indexar os bancos de dados especificados e retornar os resultados aos usuários do Cloud Search.

Pré-requisitos

Antes de implantar o conector de banco de dados do Cloud Search, colete as seguintes informações:

Etapa 1. Fazer o download e criar o software do conector de banco de dados

  1. Clone o repositório do conector que está no GitHub. 
    $ git clone https://github.com/google-cloudsearch/database-connector.git
$ cd database-connector
  2. Confira a versão desejada do conector:
    $ git checkout tags/v1-0.0.3
  3. Crie o conector. 
    $ mvn package
    Para pular os testes ao criar o conector, use mvn package -DskipTests.
  4. Copie o arquivo ZIP do conector no diretório de instalação local e descompacte: 
    $ 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

Etapa 2: configurar o conector de banco de dados

  1. Crie um arquivo de texto chamado connector-config.properties (padrão) ou similar. O Google recomenda que você nomeie os arquivos de configuração com a extensão .properties ou .config e mantenha-os no mesmo diretório do conector. Se você usar um nome ou caminho diferente, especifique o caminho ao executar o conector.
  2. Adicione parâmetros como pares de chave-valor ao conteúdo do arquivo. O arquivo de configuração precisa especificar os parâmetros de acesso à fonte e ao acesso ao banco de dados, uma instrução SQL de travessia completa do banco de dados, um título de campo de conteúdo e definições de coluna. Também é possível configurar outro comportamento do conector com parâmetros opcionais. Por exemplo: 
    # 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

    Para descrições detalhadas dos parâmetros específicos do banco de dados, acesse a Referência dos parâmetros de configuração no fim deste artigo.

    Para saber mais sobre os parâmetros comuns a todos os conectores do Cloud Search, como configuração de metadados, formatos de data e hora e opções de ACL, acesse Parâmetros de conector fornecidos pelo Google.

    Se aplicável, especifique as propriedades do objeto de esquema nos parâmetros de consulta SQL de travessia. Geralmente, é possível adicionar aliases à instrução SQL. Por exemplo, se você tiver um banco de dados de filmes e o esquema da fonte de dados contiver uma definição de propriedade chamada "ActorName", uma instrução SQL poderá ter o formato: SELECT …, last_name AS ActorName, … FROM … .

Etapa 3. Executar o conector de banco de dados

No exemplo a seguir, presume-se que os componentes necessários estejam localizados no diretório local de um sistema Linux.

Para executar o conector na linha de comando, digite o seguinte comando: 

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]

Em que:

  • google-cloud-search-database-connector-v1-0.0.3.jar é o arquivo .jar do conector de banco de dados;
  • mysql-connector-java-5.1.41-bin.jar é o driver JDBC que está sendo usado para acessar o banco de dados
  • mysql.config é um arquivo de configuração com nome personalizado. Para garantir que o conector reconheça o arquivo de configuração, especifique o caminho dele na linha de comando. Caso contrário, o conector usará connector-config.properties no seu diretório local como o nome de arquivo padrão.

O conector informa erros de configuração à medida que os detecta. Alguns erros são informados quando o conector é inicializado, como quando uma coluna do banco de dados é definida como parte do conteúdo do registro (em db.allColumns), mas a coluna não é usada na consulta SQL de travessia do banco de dados (em db.allRecordsSql). Outros erros são detectados e informados somente quando o conector tenta acessar o banco de dados para a primeira travessia, como a sintaxe inválida da instrução SQL.

Referência dos parâmetros de configuração

Parâmetros de acesso à fonte de dados

Configuração Parâmetro
ID da origem de dados api.sourceId = source-ID

Obrigatório. O ID da origem do Cloud Search que o administrador do Google Workspace configurou.
ID da origem de identidade api.identitySourceId = identity-source-ID

É necessário usar usuários e grupos externos para as ACLs. O ID da origem de identidade do Cloud Search que o administrador do Google Workspace configurou.
Conta de serviço api.serviceAccountPrivateKeyFile = path-to-private-key

Obrigatório. O caminho para o arquivo de chave da conta de serviço do Cloud Search que o administrador do Google Workspace criou.

Parâmetros de acesso ao banco de dados

Configuração Parâmetro
URL do banco de dados db.url = database-URL

Obrigatório. O caminho completo do banco de dados a ser acessado, como jdbc:mysql://127.0.0.1/dbname.
Nome de usuário e senha do banco de dados db.user = username
db.password = password

Obrigatório. Um nome de usuário e uma senha válidos que são utilizados pelo conector para acessar o banco de dados. Esse usuário do banco de dados precisa ter acesso de leitura aos registros relevantes do banco de dados que está sendo lido.
Driver JDBC db.driverClass = oracle.jdbc.OracleDriver

Obrigatório apenas se o driver JDBC 4.0 não estiver especificado no caminho da classe.

Parâmetros de consulta SQL de travessia

O conector transfere registros do banco de dados com consultas SQL SELECT no arquivo de configuração. Você precisa configurar uma consulta de travessia completa. As consultas por travessias incrementais são opcionais.

Um traversal completo lê todos os registros do banco de dados configurados para indexação. O traversal completo é necessário para indexar novos registros do Cloud Search e também para reindexar todos os registros atuais.

Uma travessia incremental lê e reindexa apenas registros de banco de dados recém-modificados e entradas recentes no banco de dados. As travessias incrementais podem ser mais eficientes do que as completas. Para usar travessias incrementais, o banco de dados precisa conter campos de carimbo de data/hora para indicar registros modificados.

O conector executa essas travessias de acordo com as programações definidas por você nos parâmetros da programação de travessia.

Configuração Parâmetro
Consulta de travessia completa db.allRecordsSql = SELECT column-1[, column-2,...] FROM database-name

Obrigatório. A consulta é executada para cada travessia completa.

Todos os nomes de coluna que o conector usará em qualquer capacidade (conteúdo, ID exclusivo, ACLs) precisam estar presentes nessa consulta. O conector executa algumas verificações preliminares na inicialização para detectar erros e omissões. Por esse motivo, não use uma consulta "SELECT * FROM ..." geral.
Paginação de travessia completa db.allRecordsSql.pagination = {none | offset}

Os valores podem ser os seguintes:

  • none: não use paginação
  • offset: use paginação por deslocamento de linha

    Para usar a paginação por deslocamento, a consulta SQL precisa ter um ponto de interrogação do marcador de posição (?) para um deslocamento de linha, começando por zero. Em cada travessia completa, a consulta é executada repetidamente até que nenhum resultado seja retornado.
Consulta de travessia incremental db.incrementalUpdateSql = SELECT column-1[, column-2,...] FROM database-name WHERE last_update_time > ?

Obrigatório se você programar travessias incrementais.

O "?" na consulta é um marcador obrigatório para um valor de carimbo de data/hora. O conector usa o carimbo de data/hora para acompanhar as modificações entre consultas SQL de travessia incremental.

Para acompanhar a coluna de carimbo de data/hora do banco de dados referente à hora da última atualização, adicione o alias timestamp_column à instrução SQL. Caso contrário, use o carimbo de data/hora atual da travessia do conector.

Para a primeira travessia incremental, o conector usa o horário de início do conector. Após o primeiro traversal incremental, o Cloud Search armazena o carimbo de data/hora para que as reinicializações do conector possam acessar o carimbo de data/hora do traversal incremental anterior.
Fuso horário do banco de dados db.timestamp.timezone = America/Los_Angeles

Especifica o fuso horário a ser usado para carimbos de data/hora do banco de dados. O carimbo de data/hora do banco de dados usado para identificar novos registros adicionados ou registros recém-modificados do banco de dados. O padrão é o fuso horário local em que o conector está sendo executado.

Exemplos de consultas SQL de travessia

  • Consulta de travessia completa básica que lê todos os registros de interesse em um banco de dados de funcionários para indexação: 
    db.allRecordsSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field \
    FROM employee
  • Especifique a paginação por deslocamento e divida uma travessia completa em várias consultas.

    Para SQL Server 2012 ou Oracle 12c (sintaxe padrão do 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

    ou, para MySQL ou 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
  • Consulta de travessia completa que aplica ACLs individuais com aliases: 
    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
  • Consulta de travessia incremental básica: 
    db.incrementalUpdateSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field, last_update_time \
     FROM employee \
     WHERE last_update_time > ?
  • Consulta de travessia incremental que aplica ACLs individuais com aliases: 
    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 > ?
  • Consulta de travessia incremental que usa o carimbo de data/hora do banco de dados em vez do horário atual: 
    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 > ?

Parâmetros de definição de coluna

Os parâmetros a seguir especificam as colunas que você usa nas instruções de travessia e para identificar exclusivamente cada registro.

Configuração Parâmetro
Todas as colunas db.allColumns = column-1, column-2, ...column-N

Obrigatório. Identifica todas as colunas que são necessárias em uma consulta SQL ao acessar o banco de dados. As colunas definidas com esse parâmetro precisam ser explicitamente referenciadas nas consultas. Todos os outros parâmetros de definição de coluna são comparados a esse conjunto de colunas.

Exemplos

db.allColumns = customer_id, first_name, last_name, phone, change_timestamp
Colunas de chave exclusiva db.uniqueKeyColumns = column-1[, column-2]

Obrigatório. Lista uma única coluna do banco de dados que contém valores exclusivos ou uma combinação de colunas com valores que definem um ID exclusivo.

O Cloud Search exige que todo documento pesquisável tenha um identificador exclusivo em uma fonte de dados. É preciso que seja possível definir um ID exclusivo para cada registro do banco de dados com base nos valores das colunas. Se você executa vários conectores em bancos de dados separados, mas indexa um conjunto de dados comum, especifique um ID exclusivo em todos os documentos.

Exemplos:

db.uniqueKeyColumns = customer_id
# or
db.uniqueKeyColumns = last_name, first_name
Coluna do link do URL url.columns = column-1[, column-2]

Obrigatório. Especifica um ou mais nomes válidos e definidos das colunas usadas para o URL utilizado em um resultado de pesquisa clicável. No caso de bancos de dados que não têm um URL relevante associado a cada registro de banco de dados, pode ser usado um link estático para cada registro.

No entanto, se os valores da coluna definirem um link válido para cada registro, as colunas do URL de visualização e os valores de configuração de formato precisarão ser especificados.
Formato de URL url.format = https://www.example.com/{0}

Define o formato do URL de visualização. Os parâmetros numerados se referem às colunas especificadas em db.columns, em ordem, começando por zero.

Se não for especificado, o padrão será "{0}".

Os exemplos seguem esta tabela.
Colunas codificadas por porcentagem para o URL url.columnsToEscape = column-1[, column-2]

Especifica colunas de db.columns com os valores que serão codificados por porcentagem antes de serem incluídos na string de URL formatada.

Exemplos de coluna de URL

Para especificar as colunas usadas em consultas de travessia e o formato do URL de visualização:

  • Para usar um URL estático sem valores de registro do banco de dados: 
    url.format = https://www.example.com
  • Para usar um valor de coluna única que é o URL de visualização: 
    url.format = {0}
url.columns = customer_id
  • Para usar um valor de coluna única que é substituído no URL de visualização na posição {0}: 
    url.format = https://www.example.com/customer/id={0}
url.columns = customer_id
url.columnsToEscape = customer_id
  • Para usar vários valores de coluna para criar o URL de visualização (as colunas dependem da ordem): 
    url.format = {1}/customer={0}
url.columns = customer_id, linked_url
url.columnsToEscape = customer_id

Campos de conteúdo

Use as opções de conteúdo para definir quais valores de registro devem fazer parte do conteúdo pesquisável.

Configuração Parâmetro
Coluna de pesquisa de maior qualidade contentTemplate.db.title = column-name

Obrigatório. A coluna de maior qualidade para indexação de pesquisa e priorização de resultados.
Priorização de colunas para pesquisa contentTemplate.db.quality.high = column-1[, column-2...]
contentTemplate.db.quality.medium = column-1[, column-2...]
contentTemplate.db.quality.low = column-1[, column-2...]

Designar colunas de conteúdo (exceto a coluna definida para contentTemplate.db.title) como campos de alta, média ou baixa qualidade de pesquisa. O padrão das colunas não especificadas é baixo.
Colunas de dados de conteúdo db.contentColumns = column-1[, column-2...]

Especifique colunas de conteúdo no banco de dados. Eles são formatados e enviados ao Cloud Search como conteúdo de documento pesquisável.

Se você não especificar um valor, o padrão será "*", indicando que todas as colunas precisam ser usadas para conteúdo.
Coluna de blob db.blobColumn = column-name

Especifique o nome de uma única coluna de blob a ser usada para o conteúdo do documento, em vez de uma combinação de colunas de conteúdo.

Caso uma coluna de blob seja especificada, será considerado um erro se as colunas de conteúdo também forem definidas. No entanto, as definições de coluna de dados estruturados e metadados continuam sendo permitidas junto com colunas de blob.