Implantar um conector de banco de dados

Este guia se destina aos administradores do conector de banco de dados do Google Cloud Search, ou seja, qualquer pessoa responsável por receber, implantar, configurar e manter o conector de banco de dados.

O conteúdo deste guia inclui instruções para executar as principais tarefas relacionadas à implantação do conector:

  • Fazer o download do software Cloud Search Connector for Databases.
  • Configurar o conector para uso com uma fonte de dados SQL específica
  • Executar o conector.

Para entender os conceitos incluídos neste documento, é recomendável que você esteja familiarizado com os conceitos de banco de dados, Structured Query Language (SQL), listas de controle de acesso (ACLs, na sigla em inglês) e os sistemas operacionais Windows ou Linux.

As informações sobre as tarefas que o administrador do Google Workspace precisa executar para mapear o Google Cloud Search no conector de banco de dados não estão presentes neste guia. Para mais informações sobre essas tarefas, consulte Gerenciar fontes de dados de terceiros.

Por padrão, o Cloud Search pode detectar, indexar e exibir conteúdo de dados do Google Workspace, como documentos e planilhas. No entanto, é possível estender o Cloud Search para que você detecte e indexe dados dos seus próprios repositórios de banco de dados usando o conector de banco de dados do Google Cloud Search.

O conector faz upload de solicitações de indexação para a API Indexing do Cloud Search e mantém o índice do Cloud Search em sincronia com o repositório de banco de dados de terceiros reindexando periodicamente todo o banco de dados.

O conector de banco de dados do Cloud Search é compatível com o uso de ACLs para controlar o acesso de usuários a documentos nos resultados da pesquisa. Para mais informações sobre esse tópico, consulte Opções de lista de controle de acesso.

Comportamento do conector

Como administrador do conector, você controla o comportamento do conector de banco de dados do Cloud Search criando o arquivo de configuração dele. Nesse arquivo, você define estes aspectos principais do comportamento do conector:

  • Acesso ao banco de dados de destino
  • Identificação de conteúdo pesquisável
  • Realização de traversals
  • Cumprimento da programação de traversals
  • Envio de consultas SQL ao banco de dados para recuperar registros
  • Adoção de listas de controle de acesso

Para definir o comportamento específico do conector, preencha o arquivo de configuração com pares de chave-valor para cada parâmetro de configuração a ser personalizado. Para informações detalhadas sobre esse processo, consulte Configurar o conector de banco de dados.

Quando o arquivo de configuração estiver preenchido, você terá as configurações necessárias para implantar o conector.

Indexação de conteúdo do banco de dados

Depois de implantado, o conector de banco de dados do Cloud Search se comunica com a origem de dados conectada à sua conta do Google Workspace e detecta o conteúdo dela por meio de em processo chamado travessia. Durante esse processo, o conector emite consultas SQL SELECT ao repositório para recuperar dados de documentos. O conector recupera esses dados e os envia para a API Indexing. Nela, eles são indexados e, por fim, exibidos aos usuários.

Inicialmente, o conector de banco de dados executa uma travessia completa, em que cada registro do banco de dados é lido e indexado. É possível programar travessias completas subsequentes em um intervalo de tempo fixo. Além disso, também é possível programar travessias incrementais caso haja suporte para isso no seu banco de dados. As travessias incrementais apenas leem e reindexam registros do banco de dados que tenham sido modificados.

Configuração do conector

É possível instalar e executar o conector de banco de dados do Cloud Search em praticamente qualquer ambiente que execute aplicativos Java, desde que o conector tenha acesso tanto à Internet quanto ao banco de dados. Como você implanta o conector de banco de dados em um host separado do Google Cloud Search ou do repositório de dados, precisa primeiro ter as informações do Google Workspace e do banco de dados que são necessárias para estabelecer relações entre o Google Cloud Search, o conector e o repositório de dados. Para permitir que o conector acesse o banco de dados, forneça informações específicas ao conector durante as etapas de configuração descritas na seção Comportamento do conector deste documento.

Para configurar o acesso do conector ao Cloud Search, você precisa de uma conta de serviço, um ID de conta de serviço e um ID de origem de dados, além de adicionar o ID de origem e o caminho ao arquivo de chave privada da conta de serviço na configuração do conector, conforme mostrado no exemplo do arquivo de configuração. Normalmente, o administrador do Google Workspace do domínio pode fornecer essas credenciais para você.

Depois de verificar se o ambiente está configurado corretamente, inicie as etapas de implantação.

Bancos de dados compatíveis

O conector de banco de dados do Cloud Search funciona com qualquer banco de dados SQL que tenha um driver compatível com JDBC 4.0 ou posterior, como:

  • MS SQL Server (2008, 2012, 2014, 2016);
  • Oracle (11g, 12c)
  • Google Cloud SQL
  • MySQL.

As informações que identificam o banco de dados de destino são fornecidas por você durante o processo de configuração do conector. Para informações detalhadas, consulte Acesso ao banco de dados.

Antes de implantar o conector de banco de dados

Antes de implantar o conector de banco de dados do Cloud Search, verifique se o ambiente tem todos estes componentes obrigatórios:

  • Chave privada do Google Workspace (que contém o ID da conta de serviço)
  • Código da fonte de dados do Google Workspace
  • Arquivo .jar do conector de banco de dados instalado em uma máquina host
  • Banco de dados de destino compatível
  • Driver JDBC usado para acessar o banco de dados (baixado e instalado separadamente)

Etapas da implantação

Para implantar o conector de banco de dados do Cloud Search, siga estas etapas básicas:

  1. Faça o download do software do conector de banco de dados do Cloud Search e salve-o.
  2. Configure o conector de banco de dados do Cloud Search.
  3. Execute o conector de banco de dados do Cloud Search.

Etapa 1: fazer o download do software do conector de banco de dados do Cloud Search e salvá-lo

  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 se é a versão desejada do conector:
    $ git checkout tags/v1-0.0.3
  3. Crie o conector. 
    $ mvn package
    Para pular os testes durante a criação do 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-windows-filesystems-connector-v1-0.0.3

Etapa 2: configurar o conector de banco de dados

Para que o conector acesse corretamente um banco de dados e indexe o conteúdo relevante, primeiro é preciso criar o arquivo de configuração dele.

Para criar um arquivo de configuração, execute estas ações:

  1. Abra um editor de texto de sua preferência.
  2. Adicione pares de chave-valor ao conteúdo do arquivo. Para mais orientações, consulte o exemplo de arquivo de configuração.
  3. Nomeie o arquivo de configuração.

    É possível atribuir qualquer nome ao arquivo de configuração, por exemplo: Mysql.properties. O Google recomenda manter consistência na nomeação de extensões de arquivos de configuração usando .properties ou .config .

Não é necessário ter um local de arquivo padrão porque é possível especificar o caminho do arquivo de configuração na linha de comando. No entanto, mantenha o arquivo de configuração no mesmo diretório do conector para simplificar o monitoramento e a execução do conector.

Especifique o caminho do conector na linha de comando a fim de garantir que ele reconheça o arquivo de configuração. Caso contrário, o conector usará connector-config.properties no diretório local como o nome do arquivo padrão. Para informações sobre como especificar o caminho de configuração na linha de comando, consulte Executar o conector de banco de dados.

Exemplo de arquivo de configuração

O exemplo de arquivo de configuração a seguir mostra os pares de chave-valor do parâmetro que definem o comportamento de um conector de exemplo. Muitos parâmetros têm padrões que são usados quando o valor do parâmetro não está definido no arquivo. 

#
    # data source access
    api.sourceId=1234567890abcdef
    api.identitySourceId=0987654321lmnopq
    api.serviceAccountPrivateKeyFile=./PrivateKey.json
    #
    # database access
    db.url=jdbc:mysql://localhost:3306/mysql_test
    db.user=root
    db.password=passw0rd
    #
    # traversal SQL statements
    db.allRecordsSql=select customer_id, first_name, last_name, phone, change_timestamp from address_book
    db.incrementalUpdateSql=select customer_id, first_name, last_name, phone, change_timestamp from address_book where change_timestamp > ?
    #
    # schedule traversals
    schedule.traversalIntervalSecs=36000
    schedule.performTraversalOnStart=true
    schedule.incrementalTraversalIntervalSecs=3600
    #
    # column definitions
    db.allColumns=customer_id, first_name, last_name, phone, change_timestamp
    db.uniqueKeyColumns=customer_id
    url.columns=customer_id
    #
    # content fields
    contentTemplate.db.title=customer_id
    db.contentColumns=customer_id, first_name, last_name, phone
    #
    # setting ACLs to "entire domain accessible"
    defaultAcl.mode=fallback
    defaultAcl.public=true

Para descrições detalhadas de cada parâmetro, consulte a Referência dos parâmetros de configuração.

Etapa 3: executar o conector de banco de dados

No exemplo a seguir, presume-se que os componentes necessários estão 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

Detalhes do comando:

  • google-cloud-search-database-connector-v1-0.0.3.jar é o arquivo .jar do conector do banco de dados.
  • mysql-connector-java-5.1.41-bin.jar é o driver JDBC usado para acessar o banco de dados.
  • mysql.config é o arquivo de configuração.

O conector tenta detectar erros de configuração o mais cedo possível. Por exemplo, se uma coluna do banco de dados for definida como parte do conteúdo do registro, mas estiver ausente da consulta SQL do banco de dados, a coluna ausente será vista como um erro quando o conector for inicializado.

No entanto, o conector detecta apenas outros erros, como sintaxe inválida de uma instrução SQL, quando tenta acessar o banco de dados para a primeira travessia.

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

Os parâmetros de configuração são descritos detalhadamente nas seções a seguir. Nelas, os exemplos em linha estão neste formato:

chave = valor

Em que "chave" (em negrito) é o nome literal do parâmetro específico e "valor" (em itálico) é o valor específico do parâmetro.

Acesso à origem de dados

Os primeiros parâmetros que cada arquivo de configuração precisa especificar são aqueles exigidos para acessar a origem de dados do Cloud Search. As etapas necessárias para configurar uma origem de dados podem ser encontradas em Gerenciar origens de dados de terceiros.

Configuração Parâmetro
Código da fonte de dados api.sourceId = 1234567890abcdef

Obrigatório. O ID da origem do Cloud Search configurado pelo administrador do Google Workspace.
ID da origem de identidade api.identitySourceId = 0987654321lmnopq

Obrigatório na utilização de usuários e grupos externos. O ID da origem de identidade do Cloud Search configurado pelo administrador do Google Workspace.
Conta de serviço api.serviceAccountPrivateKeyFile = ./PrivateKey.json

Obrigatório. O arquivo da chave da conta de serviço do Cloud Search criado pelo administrador do Google Workspace para a acessibilidade do conector.

Acesso ao banco de dados

Para que o conector possa transferir um banco de dados, é preciso identificar o caminho para o banco de dados e as credenciais que permitem que o conector faça login nele. Use os seguintes parâmetros de acesso ao banco de dados para incluir informações de acesso no arquivo de configuração.

Configuração Parâmetro
URL do banco de dados db.url = jdbc:mysql://127.0.0.1/dbname

Obrigatório. O caminho completo do banco de dados a ser acessado.
Nome de usuário e senha do banco de dados db.user = dbadmin
db.password = pas5w0rd

Obrigatório. Um nome de usuário e senha válidos 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.

Configurar instruções SQL de traversals

O conector acessa e indexa os registros do banco de dados realizando travessias. Para permitir que o conector transfira registros do banco de dados, forneça consultas SQL SELECT no arquivo de configuração. O conector é compatível com dois tipos de métodos de travessia:

O conector executa essas travessias de acordo com as programações definidas por você nas opções de programação do arquivo de configuração, conforme descrito em Programar travessias abaixo.

Travessia completa

Uma travessia completa lê todos os registros do banco de dados configurados para indexação. Ela é necessária para indexar novos registros do Cloud Search e também para reindexar todos os registros atuais.

Configuração Parâmetro
Traversal completo db.allRecordsSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field FROM employee

OU

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

Obrigatório. Esse exemplo inclui uma consulta SQL SELECT que lê todos os registros que são de interesse em um banco de dados de um funcionário para indexação.

Para usar paginação por deslocamento, a consulta SQL precisa ter um marcador ("?") para um deslocamento de linha, começando por zero. A consulta será executada diversas vezes em cada travessia completa, até que nenhum resultado seja retornado.
db.allRecordsSql.pagination = offset

As opções de paginação válidas são:

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

Todo nome de coluna que o conector usar em qualquer capacidade (conteúdo, ID exclusivo, ACLs) precisa estar presente nesta consulta. O conector realiza algumas verificações preliminares na inicialização para detectar erros e omissões. Por esse motivo, não use uma consulta geral "SELECT * FROM ...".

Exemplos de paginação

Para especificar paginação por deslocamento e dividir um traversal completo em várias consultas: 
# For SQL Server 2012 or Oracle 12c (standard SQL 2008 syntax)
    db.allRecordsSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field \
        FROM employee \
        ORDER BY key OFFSET ? ROWS FETCH FIRST 1000 ROWS ONLY
    db.allRecordsSql.pagination = offset

ou

# For MySQL or Google Cloud SQL
    db.allRecordsSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field \
        FROM employee \
        ORDER BY key LIMIT 1000 OFFSET ?
    db.allRecordsSql.pagination = offset

Traversal incremental

Por padrão, o conector não executa travessias incrementais. No entanto, caso seu banco de dados contenha campos de carimbo de data/hora para indicar registros modificados, configure o conector para realizar travessias incrementais que leem e reindexam somente registros recém-modificados e entradas recentes no banco de dados. Como uma travessia incremental lê um conjunto de dados menor, ela pode ser muito mais eficiente do que uma completa.

Os parâmetros da travessia incremental definem o escopo da travessia e identificam o carimbo de data/hora do banco de dados usado para identificar registros recém-modificados do banco de dados ou novas inclusões no registro.

Configuração Parâmetro
Traversal incremental db.incrementalUpdateSql = select customer_id, first_name, last_name, employee_id, interesting_field, last_update_time from employee where last_update_time > ?

OU

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 > ?

Obrigatório ao usar travessias incrementais. Para monitorar a coluna de carimbo de data/hora do banco de dados referente à hora da última atualização, adicione timestamp_column à instrução SQL. Caso contrário, use o carimbo de data/hora da travessia do conector.

A consulta SQL SELECT de exemplo lê todos os registros modificados e que precisam ser reindexados.

O "?" obrigatório na consulta é um marcador para um valor de carimbo de data/hora que o conector monitora e mantém entre consultas SQL de travessia incremental.

Por padrão, o conector armazena o horário de início da consulta incremental para uso na travessia incremental a seguir. Se não tiver ocorrido nenhuma travessia incremental anterior, será usado o horário de início da execução do conector.

Após a primeira travessia incremental, o Cloud Search armazena o carimbo de data/hora para que as reinicializações do conector possam acessar o carimbo de data/hora da travessia 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 padrão é o fuso horário local em que o conector está sendo executado.

Programar travessias

Os parâmetros de agendamento determinam com que frequência o conector espera entre as travessias.

Configuração Parâmetro
Travessia completa após um intervalo especificado schedule.traversalIntervalSecs = 7200

Especifica o intervalo entre travessias, expresso em segundos. O valor padrão é 86400 (número de segundos em um dia).
Travessia completa na inicialização do conector schedule.performTraversalOnStart = false

Especifica que a primeira travessia completa precisa ocorrer imediatamente após cada inicialização do conector (true), ou não (false). O valor padrão é true.
Travessia incremental após um intervalo especificado schedule.incrementalTraversalIntervalSecs = 900

Especifica o intervalo entre travessias, expresso em segundos. O valor padrão é 300 (número de segundos em 5 minutos). Esse parâmetro não será usado se o SQL de travessia incremental não estiver definido.

Definições de coluna

Para que o conector acesse e indexe registros do banco de dados, é preciso fornecer informações sobre definições de coluna no arquivo de configuração. O conector também usa essas definições de coluna para detectar erros de configuração na inicialização do conector.

Configuração Parâmetro
Todas as colunas db.allColumns = customer_id, first_name, last_name, employee_id, interesting_field, last_update_time, linked_url

Obrigatório. Identifica todas as colunas 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 verificados nesse conjunto de colunas.
Colunas de chave exclusiva db.uniqueKeyColumns = customer_id
db.uniqueKeyColumns = last_name, first_name

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 origem de dados. Por esse motivo, é preciso que cada registro de banco de dados possa usar os valores de coluna para definir um ID exclusivo. Tome cuidado extra para fornecer um ID exclusivo em todos os documentos caso você esteja executando vários conectores em bancos de dados separados, mas indexando-os em um conjunto de dados comum.
Colunas 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}".
url.columns = customer_id

Obrigatório. Especifica os nomes válidos e definidos das colunas utilizadas 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.
url.columnsToEscape = customer_id

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 e o formato do URL de visualização: 

# static URL not using any database record values
    url.format = https://www.example.com
    url.columns = customer_id

ou 

# single column value that is the view URL
    url.format = {0}
    url.columns = customer_url

ou 

# single column value that will be substituted into the view URL at position {0}
    url.format = https://www.example.com/customer/id={0}
    url.columns = customer_id
    url.columnsToEscape = customer_id

ou 

# multiple column values used to build the view URL (columns are order dependent)
    url.format = {1}/customer={0}
    url.columns = customer_id, linked_url
    url.columnsToEscape = customer_id

Parâmetros de configuração de metadados

Os parâmetros de configuração de metadados descrevem as colunas de banco de dados usadas para preencher metadados do item. Se o arquivo de configuração não contiver esses parâmetros, os valores padrão serão utilizados. A tabela a seguir mostra esses parâmetros.
Configuração Parâmetro
Título itemMetadata.title.field=movieTitle
itemMetadata.title.defaultValue=Gone with the Wind
O atributo de metadados que contém o valor correspondente ao título do documento. O valor padrão é uma string vazia.
URL itemMetadata.sourceRepositoryUrl.field=url
itemMetadata.sourceRepositoryUrl.defaultValue=https://www.imdb.com/title/tt0031381/
O atributo de metadados que contém o valor do URL de documento para os resultados de pesquisa.
Carimbo de data/hora criado itemMetadata.createTime.field=releaseDate
itemMetadata.createTime.defaultValue=1940-01-17
O atributo de metadados que contém o valor do carimbo de data/hora da criação do documento.
Horário da última modificação itemMetadata.updateTime.field=releaseDate
itemMetadata.updateTime.defaultValue=1940-01-17
O atributo de metadados que contém o valor do carimbo de data/hora da modificação mais recente do documento.
Idioma do documento itemMetadata.contentLanguage.field=languageCode
itemMetadata.contentLanguage.defaultValue=en-US
O idioma do conteúdo dos documentos que estão sendo indexados.
Tipo de objeto de esquema itemMetadata.objectType=movie
O tipo de objeto usado pelo conector, conforme definido em Criar e registrar um esquema. O conector não indexará nenhum dado estruturado se essa propriedade não for especificada.

Se aplicável, as propriedades desse objeto de esquema precisarão ser especificadas nas consultas SQL definidas na configuração. Na maioria das vezes, isso pode ser feito adicionando aliases às instruções SQL. Por exemplo, suponha que, para um banco de dados de filmes, o esquema da origem de dados contenha uma definição de propriedade denominada "ActorName". Uma instrução SQL poderia ter o formato: select …, last_name as ActorName, … from …

Cada coluna que corresponde a um nome de propriedade no objeto de esquema é automaticamente transmitida com o registro de banco de dados indexado e usada como dados estruturados na origem de dados.

Observação: essa propriedade de configuração indica um valor e não um atributo de metadados, e os sufixos .field e .defaultValue não são compatíveis.

Formatos de data e hora

Os formatos de data e hora especificam os formatos esperados nos atributos de metadados. Se o arquivo de configuração não contiver esse parâmetro, serão usados os valores padrão. A tabela a seguir mostra esse parâmetro.
Configuração Parâmetro
Formatos adicionais de data e hora structuredData.dateTimePatterns=MM/dd/uuuu HH:mm:ssXXX
Uma lista separada por ponto e vírgula de padrões extras de java.time.format.DateTimeFormatter. Os padrões são usados na análise de valores de string em qualquer campo de data ou data/hora nos metadados ou no esquema. O valor padrão é uma lista vazia, mas os formatos RFC 3339 e RFC 1123 são sempre aceitos.

Campos de conteúdo

A vantagem de indexar valores de registro do banco de dados no Cloud Search é que eles podem ser pesquisáveis. Use as opções de conteúdo para definir quais valores de registro precisam fazer parte do conteúdo pesquisável.

Configuração Parâmetro
Colunas de dados de conteúdo db.contentColumns = customer_id, first_name, last_name

Especifica colunas de conteúdo no banco de dados. Todas as colunas que você designar como colunas de conteúdo são formatadas e enviadas 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.

Colunas de modelo de conteúdo contentTemplate.db.title = customer_id

Obrigatório. As colunas de dados de conteúdo são formatadas para indexação com base em um modelo de conteúdo. O modelo define a prioridade de cada valor de coluna de dados para a pesquisa. A definição de coluna de qualidade mais alta é a coluna de "título" obrigatória.
contentTemplate.db.quality.high = first_name, last_name
contentTemplate.db.quality.medium = interesting_field
contentTemplate.db.quality.low = employee_id

É possível designar todas as outras colunas de conteúdo como campos de alta, média ou baixa qualidade de pesquisa. Qualquer coluna de conteúdo não definida em uma categoria específica é padronizada como baixa.
Coluna de blob db.blobColumn = blob_data

Indica 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 como 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.

Opções de lista de controle de acesso

Existem várias opções para proteger o acesso do usuário a registros indexados com ACLs.

Configuração Parâmetro
Domínio inteiro defaultAcl.mode = override
defaultAcl.public = true

Os modos válidos são:

  • none: não use a ACL padrão
  • fallback: use a ACL padrão somente se não houver nenhuma ACL presente
  • append: adicione a ACL padrão à ACL atual
  • override: substitua a ACL atual pela ACL padrão

Se o campo defaultAcl.mode for definido como override e o campo defaultAcl.public for definido como true, esses parâmetros especificarão o acesso de "domínio inteiro", em que todos os registros de banco de dados indexados podem ser acessados publicamente por qualquer usuário do domínio. O valor do modo determina quando aplicar a ACL pública.

Se defaultAcl.mode for definido como none, os registros não poderão ser pesquisados sem ACLs individuais definidas.
ACL comum definida defaultAcl.mode = fallback
defaultAcl.public = false
defaultAcl.readers.users = user1, user2,
google: user3
defaultAcl.readers.groups = google:group1, group2
defaultAcl.denied.users = user4, user5
defaultAcl.denied.groups = group3

Se você definir todos esses parâmetros, o conjunto inteiro especificará uma ACL "comum definida" a ser usada para cada registro do banco de dados caso o registro do banco de dados não tenha uma definição de ACL individual. Essa ACL comum é usada para controlar o acesso em todo o banco de dados, dependendo do modo selecionado.

Todo usuário e grupo é considerado um grupo/usuário definido pelo domínio local, a menos que seja prefixado com "google:" (constante literal).
ACL individual Se os parâmetros de configuração especificarem ACLs individuais, cada registro conterá suas próprias informações de ACL nos seus valores de coluna.

Se cada registro de banco de dados contiver informações de ACL individuais destinadas à própria acessibilidade, a consulta SQL precisará conter aliases de coluna de constante literal reservados para que o conector saiba como recuperar os usuários "leitores" e "negados". Caso os literais reservados a seguir estejam presentes nas consultas SQL, não será necessária nenhuma outra configuração.

readers_users

readers_groups

denied_users

denied_groups

Exemplos de consultas SQL de ACL individual

Os exemplos a seguir mostram consultas SQL SELECT que usam ACLs "individuais": 

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, 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 > ?

Referência rápida

A tabela a seguir lista os parâmetros obrigatórios e opcionais mais importantes que pertencem ao conector de banco de dados, bem como os valores padrão.

Parâmetro Descrição
db.driverClass Padrão: string vazia

O driver JDBC referente ao conector:

db.driverClass = oracle.jdbc.OracleDriver
db.url Obrigatório

Define o URL do banco de dados:

db.url = jdbc:mysql://localhost:3306/dbname
db.user Padrão: string vazia

O usuário do banco de dados que o conector utiliza para consultar o banco de dados:

db.user = dbadmin
db.password Padrão: string vazia

A senha do usuário do banco de dados que o conector utiliza para consultar o banco de dados:

db.password = pas5w0rd
db.allRecordsSql Obrigatório

Define uma consulta SQL para recuperar todas as colunas relevantes do registro no banco de dados:

db.allRecordsSql = select customer_id, first_name, last_name, employee_id, interesting_field from employee
db.allRecordsSql.pagination Padrão: none

Especifica uma das seguintes opções de paginação:

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

db.allRecordsSql.pagination = offset
db.incrementalUpdateSql Padrão: desativado (string vazia)

Consulta de travessia incremental para recuperar documentos alterados recentemente, geralmente pelo carimbo de data/hora:

db.incrementalUpdateSql = select customer_id, first_name, last_name, employee_id, interesting_field, last_update_time from employee where last_update_time > ?
db.timestamp.timezone Padrão: usa o mesmo fuso horário (string vazia)

Especifica o fuso horário do servidor do banco de dados quando há uma diferença entre os fusos horários do conector e do servidor do banco de dados:

db.timestamp.timezone = America/Los_Angeles
schedule.
traversalIntervalSecs		 Padrão: 86400 (segundos em um dia)

Intervalo de travessia completa. O método traversal() do conector é visto na seguinte programação:

schedule.traversalIntervalSecs = 7200
schedule.
performTraversalOnStart		 Padrão: true

Chame um traversal completo na inicialização:

schedule.performTraversalOnStart = false
schedule.
incrementalTraversalIntervalSecs		 Padrão: 300

Número de segundos entre as invocações da travessia incremental para registros modificados (requer db.updataSql):

schedule.incrementalTraversalIntervalSecs = 900
db.allColumns Obrigatório

Todos os nomes de colunas e aliases na consulta SQL principal que serão utilizados em qualquer outra definição de coluna:

db.allColumns = customer_id, first_name, last_name, employee_id, interesting_field, last_update_time, linked_url
db.uniqueKeyColumns Obrigatório

Um ou mais nomes de cabeçalho de coluna (do formato nome:tipo) separados por vírgulas e que fornecem um identificador exclusivo para um resultado de consulta do banco de dados:

db.uniqueKeyColumns = customer_id
url.format Padrão: {0}

Especifica o formato das colunas de URL:

url.format = https://www.example.com/employee/id={0}
url.columns Obrigatório

Especifica as colunas de uma consulta SQL que serão usadas para criar um URL visível para os resultados da pesquisa:

url.columns = customer_id
url.columnsToEscape Padrão: string vazia

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

url.columnsToEscape = customer_id
itemMetadata.title.field Padrão: string vazia

Especifica a coluna do registro que será usada para o "título" de metadados:

itemMetadata.title.field = customer_id
itemMetadata.createTime.field Padrão: string vazia

Especifica a coluna do registro a ser usada para a "data de criação" dos metadados:

itemMetadata.createTime.field = created_timestamp
itemMetadata.updatetime.field Padrão: string vazia

Especifica a coluna do registro a ser usada para a "data de modificação" dos metadados:

itemMetadata.updatetime.field = last_update_time
itemMetadata.contentLanguage.field Padrão: string vazia

Especifica a coluna do registro a ser usada para o "idioma" dos metadados:

itemMetadata.contentLanguage.field = language_used
itemMetadata.objectType Padrão: string vazia

Especifica a coluna do registro a ser usada para o "objeto" do esquema. Observação: é um nome literal, e não um valor de coluna:

itemMetadata.objectType = schema_object_name
db.contentColumns Padrão: * (todas as colunas de db.allRecords.Sql)

Define as colunas de uma consulta SQL a ser usada para recuperar o conteúdo do registro do banco de dados:

db.contentColumns = customer_id, first_name, last_name
contentTemplate.db.title Obrigatório

Especifica o título HTML do conteúdo e o campo de qualidade mais alta de pesquisa:

contentTemplate.db.title = id
contentTemplate.db.quality.high Padrão: string vazia

Especifica os campos de conteúdo que receberam um valor alto de qualidade de pesquisa:

contentTemplate.db.quality.high = first_name, last_name
contentTemplate.db.quality.medium Padrão: string vazia

Especifica os campos de conteúdo que recebem um valor médio de qualidade de pesquisa:

contentTemplate.db.quality.medium = interesting_field
contentTemplate.db.quality.low Padrão: padronização de todos os campos não especificados com um valor baixo de qualidade de pesquisa

Especifica os campos de conteúdo que receberam um valor baixo de qualidade de pesquisa:

contentTemplate.db.quality.low = employee_id
db.blobColumn Padrão: string vazia

Especifica que o banco de dados usa uma única coluna BLOB para o conteúdo do registro:

db.blobColumn=blob_data
defaultAcl.mode Padrão: none

Especifica um dos seguintes modos de ACL:

  • none: não use a ACL padrão
  • fallback: use a ACL padrão somente se não houver nenhuma ACL presente
  • append: adicione a ACL padrão à ACL atual
  • override: substitua a ACL atual pela ACL padrão

defaultAcl.mode = override
defaultAcl.public Padrão: false

Especifica que a ACL padrão usada para todo o repositório é pública:

defaultAcl.public=true
defaultAcl.readers.users Usado somente se defaultAcl.mode estiver definido como fallback e defaultAcl.public estiver definido como false.

Especifica os leitores de ACL comuns em uma lista delimitada por vírgulas:

defaultAcl.readers.users=user1,user2,user3
defaultAcl.readers.groups Usado somente se defaultAcl.mode estiver definido como fallback e defaultAcl.public estiver definido como false.

Especifica os leitores do grupo de ACL comuns em uma lista delimitada por vírgulas:

defaultAcl.readers.groups=group1,group2
defaultAcl.denied.users Usado somente se defaultAcl.mode estiver definido como fallback e defaultAcl.public estiver definido como false.

Especifica os usuários negados para todo o repositório:

defaultAcl.denied.users=user4,user5
defaultAcl.denied.groups Usado somente se defaultAcl.mode estiver definido como fallback e defaultAcl.public estiver definido como false.

Especifica os grupos permitidos para todo o repositório:

defaultAcl.denied.groups=group3
defaultAcl.name Padrão: DEFAULT_ACL_VIRTUAL_CONTAINER

Especifica o nome do contêiner virtual a que a ACL padrão é aplicada:

defaultAcl.name = employee-db-default-acl
api.defaultRequestMode Padrão: SYNCHRONOUS

Especifica que as travessias utilizem o modo de atualização síncrona (em vez de atualizações assíncronas):

api.defaultRequestMode = ASYNCHRONOUS
traverse.exceptionHandler Padrão: 0

Especifica se a travessia precisa ignorar ("ignore"), cancelar sempre ("0") ou cancelar depois que um determinado número de exceções forem encontradas ("10"):

traverse.exceptionHandler = ignore