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 usar na criação dos seus próprios conectores de trabalho. Este exemplo de código exige personalização e testes substanciais antes de serem usados na prova de conceito ou ambientes de produção. Para uso em produção, recomendamos obter ajuda de um dos parceiros do Cloud Search. Para mais ajuda sobre como encontrar Parceiro de pesquisa, entre em contato com seu gerente de contas do Google.

É possível configurar o Google Cloud Search para descobrir e indexar dados da 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 praticamente qualquer ambiente em que aplicativos Java possam ser executados, desde que o conector tenha acesso a ambos Internet e 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:
  • MS SQL Server (2008, 2012, 2014, 2016);
  • Oracle (11g, 12c)
  • Google Cloud SQL
  • MySQL
Software Driver JDBC para o conector usar para acessar o banco de dados (baixado e instalado separadamente)

Implantar o conector

As etapas a seguir descrevem como instalar e configurar o conector 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-o: 
    $ 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 com o nome connector-config.properties (o padrão) ou algo semelhante. Recomendações do Google nomeie os arquivos de configuração com o método .properties ou .config e mantenha o arquivo no mesmo diretório que o conector. Se você usar um nome ou caminho diferente, deverá especificar o caminho ao executar o conector.
  2. Adicionar parâmetros como pares de chave-valor ao conteúdo do arquivo. O arquivo de configuração deve especificar os parâmetros de acesso à fonte e 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 outros comportamentos 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 o Referência dos parâmetros de configuração ao final deste artigo.

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

    Se aplicável, especifique as propriedades do objeto de esquema no SQL de travessia. parâmetros de consulta. Em geral, é possível adicionar aliases . Por exemplo, se você tiver um filme banco de dados, e o esquema da fonte de dados contém uma definição de propriedade chamada "ActorName", uma instrução SQL poderia 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 de configuração, especifique o caminho na linha de comando. Caso contrário, o conector usa connector-config.properties na sua região como o nome de arquivo padrão.

O conector informa erros de configuração ao detectá-los. Alguns erros são informados quando O conector é inicializado, por exemplo, 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 da banco de dados (em db.allRecordsSql). Outros erros só são detectados e informados quando o conector tenta acessar o banco de dados na primeira travessia, como sintaxe inválida de uma 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 Cloud Search ID da origem que o administrador do Google Workspace configurou.
Código da origem de identidade api.identitySourceId = identity-source-ID

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

Obrigatório. O caminho para o Cloud Search arquivo da chave da conta de serviço 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. A 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 análise

O conector transmite registros do banco de dados com SQL SELECT. no arquivo de configuração. É preciso configurar uma consulta de travessia completa. consultas para travessias incrementais são opcionais.

Uma travessia completa 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 somente bancos de dados recém-modificados. registros e entradas recentes no banco de dados. Travessias incrementais podem ser mais eficientes do que travessias completas. Para usar travessias incrementais, seu 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 em parâmetros da programação do traversal.

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 usa A capacidade (conteúdo, ID exclusivo, ACLs) precisa estar presente nesta 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 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. A usa o carimbo de data/hora para rastrear modificações entre consultas SQL de travessia incremental.

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

Para a primeira travessia incremental, o conector usa o horário de início dele. Após o primeira travessia incremental, o Cloud Search armazena o carimbo de data/hora para que As reinicializações do conector podem acessar a travessia incremental anterior carimbo de data/hora.
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 inclusões de novos registros ou registros e modificar os registros 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 SQL 2008 padrão):

    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 usadas nas instruções de travessia e para identifiquem cada registro de forma exclusiva.

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. Todas outro parâmetro de definição de coluna é comparado a esse conjunto de colunas.

Exemplo:

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 de banco de dados contendo valores exclusivos ou por uma combinação de colunas com valores que juntos definem um ID exclusivo.

O Cloud Search exige que todo documento pesquisável tenha um identificador exclusivo em uma fonte de dados. Você precisa ser capaz de definir um ID exclusivo para cada registro de banco de dados. dos valores das colunas. Se você executar vários conectores em bancos de dados separados, mas em 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 de link do URL url.columns = column-1[, column-2]

Obrigatório. Especifica um ou mais campos válidos, definidos nomes das colunas usadas para o URL usado 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}".

Confira alguns exemplos após a tabela.
Colunas codificadas por porcentagem para 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 usar valores de registro do banco de dados: 
    url.format = https://www.example.com
  • Para usar um único valor de coluna que é o URL de visualização: 
    url.format = {0}
url.columns = customer_id
  • Para usar um único valor de coluna que seja 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 diversos 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 como contentTemplate.db.title) como campos de alta, média ou baixa qualidade de pesquisa. Colunas não especificadas são padronizadas como baixas.
Colunas de dados de conteúdo db.contentColumns = column-1[, column-2...]

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

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

Especificar o nome de um único blob coluna 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.