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:
|
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:
- Chave privada do Google Workspace, que também contém o ID da conta de serviço. Para saber como conseguir uma chave privada, acesse Configurar o acesso à API REST do Google Cloud Search.
- ID da fonte de dados do Google Workspace. Para saber como conseguir um ID de origem de dados, acesse Adicionar uma origem de dados para pesquisar.
Etapa 1. Fazer o download e criar o software do conector de banco de dados
- Clone o repositório do conector que está no GitHub.
$ git clone https://github.com/google-cloudsearch/database-connector.git $ cd database-connector
- Confira a versão desejada do conector:
$ git checkout tags/v1-0.0.3
- Crie o conector.
$ mvn package
Para pular os testes ao criar o conector, usemvn package -DskipTests
. - 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
- 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. - 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 dadosmysql.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 |
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:
|
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 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 |
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. |