Implantar um conector CSV

Este guia destina-se aos administradores de conectores de valores separados por vírgula (CSV, na sigla em inglês) do Google Cloud Search, ou seja, qualquer pessoa responsável pelo download e monitoramento ou pela configuração e execução de um conector.

Este guia inclui instruções para executar as principais tarefas relacionadas à implantação de conectores CSV:

• Fazer o download do software do conector CSV do Google Cloud Search
• Configurar o conector para uso com uma fonte de dados CSV específica
• Implantar e executar o conector.

Para entender os conceitos deste documento, é preciso estar familiarizado com os princípios básicos do Google Workspace, arquivos CSV e listas de controle de acesso (ACLs).

Visão geral do conector CSV do Google Cloud Search

O conector CSV do Cloud Search funciona com qualquer arquivo de texto CSV. Um arquivo CSV armazena dados tabulares, e cada linha do arquivo é um registro de dados.

O conector CSV do Google Cloud Search extrai linhas individuais de um arquivo CSV e as indexa no Cloud Search por meio da API Indexing. Depois de indexadas, elas podem ser pesquisadas por meio dos clientes do Cloud Search ou da API Query. O conector CSV também pode controlar o acesso dos usuários ao conteúdo nos resultados de pesquisa por meio das ACLs.

O conector CSV do Google Cloud Search pode ser instalado no Linux ou no Windows. Antes de implantá-lo, verifique se você tem os seguintes componentes necessários:

• Java JRE 1.8 instalado em um computador que executa o conector CSV do Google Cloud Search

• Informações do Google Workspace necessárias para estabelecer relações entre o Google Cloud Search e a origem de dados:

  • Chave privada do Google Workspace (que contém o ID da conta de serviço)
  • ID da fonte de dados do Google Workspace

  Normalmente, o administrador do Google Workspace do domínio pode fornecer essas credenciais para você.

Etapas da implantação

Para implantar o conector CSV do Google Cloud Search, siga estas etapas:

1. Instalar o software do conector CSV do Google Cloud Search
2. Especificar a configuração do conector CSV
3. Configurar o acesso à origem de dados do Google Cloud Search
4. Configurar o acesso ao arquivo CSV
5. Especificar os nomes das colunas a serem indexadas, de chave exclusiva e de data e hora
6. Especificar as colunas a serem usadas nos URLs clicáveis de resultados de pesquisa
7. Especificar informações de metadados e formatos de coluna
8. Programar a travessia de dados
9. Especificar opções de lista de controle de acesso (ACL)

1. Instalar o SDK

Instale o SDK no seu repositório Maven local.

1. Clone o repositório do SDK que está no GitHub.

   $ git clone https://github.com/google-cloudsearch/connector-sdk.git
   $ cd connector-sdk/csv

2. Confira se é a versão desejada do SDK:

   $ git checkout tags/v1-0.0.3

3. Crie o conector:

   $ mvn package

4. Copie o arquivo ZIP do conector para o diretório de instalação local:

   $ cp target/google-cloudsearch-csv-connector-v1-0.0.3.zip installation-dir
   $ cd installation-dir
   $ unzip google-cloudsearch-csv-connector-v1-0.0.3.zip
   $ cd google-cloudsearch-csv-connector-v1-0.0.3

2. Especificar a configuração do conector CSV

Como administrador do conector, você controla o comportamento dele e os parâmetros que definem os atributos no arquivo de configuração. Os parâmetros configuráveis incluem:

• Acesso a uma fonte de dados
• Localização do arquivo CSV
• Definições das colunas do CSV
• Colunas que definem um código exclusivo
• Opções de traversal
• Opções da ACL para restringir o acesso aos dados

Para que o conector acesse corretamente um arquivo CSV e indexe o conteúdo relevante, primeiro é necessário criar um arquivo de configuração.

Para criar um arquivo de configuração, faça o seguinte:

1. Abra um editor de texto de sua escolha e nomeie o arquivo de configuração.
   Adicione pares de chave=valor ao conteúdo do arquivo, conforme descrito nas seções a seguir.
2. Salve e nomeie o arquivo de configuração.
   O Google recomenda que você nomeie o arquivo de configuração como connector-config.properties. Assim, nenhum outro parâmetro de linha de comando será necessário para executar o conector.

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

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

3. Configurar o acesso à origem de dados do Google Cloud Search

Os primeiros parâmetros que todo arquivo de configuração precisa especificar são aqueles necessários para acessar a origem de dados do Cloud Search, conforme mostrado na tabela a seguir. Normalmente, você precisará do código da fonte de dados, do código da conta de serviço e do caminho para o arquivo de chave privada dessa conta para configurar o acesso do conector ao Cloud Search. As etapas necessárias para configurar uma fonte de dados são descritas em Gerenciar fontes de dados de terceiros.

4. Configure parâmetros de um arquivo CSV

Antes que o conector possa fazer a traversal em um arquivo CSV e extrair dados dele para indexação, é necessário identificar o caminho desse arquivo. Também é possível especificar o formato e o tipo de codificação do arquivo. Adicione os seguintes parâmetros para especificar as propriedades do arquivo CSV no arquivo de configuração.

5. Especifique nomes de colunas para índice e colunas-chave exclusivas

Para o conector acessar e indexar arquivos CSV, você precisa enviar informações sobre as definições de colunas no arquivo de configuração. Se o arquivo de configuração não contiver os parâmetros que especificam os nomes das colunas a serem indexadas e as colunas-chave exclusivas, os valores padrão serão usados.

6. Especificar as colunas a serem usadas nos URLs clicáveis de resultados de pesquisa.

Quando um usuário pesquisa usando o Google Cloud Search, ele mostra uma página de resultados que inclui URLs clicáveis para cada resultado. Para ativar esse recurso, adicione o parâmetro mostrado na tabela a seguir ao arquivo de configuração.

7. Especificar informações de metadados, formatos de coluna e qualidade da pesquisa

É possível adicionar parâmetros ao arquivo de configuração que especificam o seguinte:

• Parâmetros de configuração de metadados
• Formatos de coluna
• Qualidade da pesquisa

Parâmetros de configuração de metadados

Os parâmetros de configuração de metadados descrevem as colunas do CSV usadas para preencher os metadados do item. Se o arquivo de configuração não contiver esses parâmetros, os valores padrão serão usados. Veja esses parâmetros na tabela a seguir.

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.

Formatos de coluna

Os formatos de coluna especificam informações sobre as colunas que precisam fazer parte do conteúdo pesquisável. Se o arquivo de configuração não contiver esses parâmetros, os valores padrão serão usados. Veja esses parâmetros na tabela a seguir.

Qualidade da pesquisa

O conector CSV do Cloud Search permite a formatação automática de HTML para campos de dados e define os campos de dados no início da execução e depois usa um modelo de conteúdo para formatar cada registro antes de fazer o upload para o Cloud Search.

O modelo de conteúdo define a importância de cada valor de campo para pesquisa. O campo de título é obrigatório e é definido como a prioridade mais alta. É possível definir os níveis de importância de qualidade da pesquisa para todos os outros campos de conteúdo como alto, médio ou baixo. Qualquer campo de conteúdo não definido em uma categoria específica tem como padrão prioridade baixa. Veja esses parâmetros na tabela a seguir.

8. Programar a traversal dos dados

Traversal é o processo do conector para descobrir o conteúdo da fonte de dados, nesse caso, um arquivo CSV. À medida que o conector CSV é executado, ele realiza a traversal das linhas de um arquivo CSV e indexa cada linha no Cloud Search por meio da API Indexing.

A traversal completa indexa todas as colunas no arquivo. A traversal incremental indexa somente as colunas adicionadas ou modificadas após o processo anterior. O conector CSV executa somente traversais completas, e não traversais incrementais.

Os parâmetros de agendamento determinam quanto tempo o conector aguarda entre as traversais. Se o arquivo de configuração não contiver esses parâmetros, os valores padrão serão utilizados. Veja esses parâmetros na tabela a seguir.

9. Especificar as opções da lista de controle de acesso (ACL, na sigla em inglês)

O conector CSV do Google Cloud Search oferece suporte a permissões por meio de ACLs para controlar o acesso ao conteúdo do arquivo CSV nos resultados de pesquisas. Existem várias opções de ACL disponíveis para proteger o acesso do usuário aos registros indexados.

Se o repositório tiver informações individuais da ACL associadas a cada documento, faça o upload de todas as informações dela para controlar o acesso aos documentos no Cloud Search. Se o repositório incluir informações parciais ou nenhuma informação da ACL, será possível fornecê-las nos parâmetros a seguir que serão enviados pelo SDK ao conector.

O conector depende das ACLs padrão serem ativadas no arquivo de configuração. Para ativar as ACLs padrão, defina defaultAcl.mode para qualquer modo diferente de none e configure-o com defaultAcl.*

Definição do esquema

O Cloud Search permite a indexação e veiculação de conteúdo estruturado e não estruturado. Para fazer consultas de dados estruturados, é necessário configurar o esquema para sua fonte de dados.

Uma vez definido, o conector CSV pode consultar o esquema definido para criar solicitações de indexação. Para fornecer um exemplo ilustrativo, vamos considerar um arquivo CSV contendo informações sobre filmes.

Vamos supor que o arquivo CSV de entrada tenha o seguinte conteúdo.

1. Código do filme
2. Título do filme
3. Descrição
4. Ano
5. Data de lançamento
6. Atores (valores múltiplos separados por vírgula (,))
7. Gênero (múltiplos valores)
8. Avaliações

Com base na estrutura de dados acima, é possível definir o esquema para uma fonte de dados na qual você quer indexar dados do arquivo CSV.

{
  "objectDefinitions": [
    {
      "name": "movie",
      "propertyDefinitions": [
        {
          "name": "actors",
          "isReturnable": true,
          "isRepeatable": true,
          "isFacetable": true,
          "textPropertyOptions": {
            "operatorOptions": {
              "operatorName": "actor"
            }
          }
        },
        {
          "name": "releaseDate",
          "isReturnable": true,
          "isRepeatable": false,
          "isFacetable": false,
          "datePropertyOptions": {
            "operatorOptions": {
              "operatorName": "released",
              "lessThanOperatorName": "releasedbefore",
              "greaterThanOperatorName": "releasedafter"
            }
          }
        },
        {
          "name": "movieTitle",
          "isReturnable": true,
          "isRepeatable": false,
          "isFacetable": false,
          "textPropertyOptions": {
            "retrievalImportance": {
              "importance": "HIGHEST"
            },
            "operatorOptions": {
              "operatorName": "title"
            }
          }
        },
        {
          "name": "genre",
          "isReturnable": true,
          "isRepeatable": true,
          "isFacetable": true,
          "enumPropertyOptions": {
            "operatorOptions": {
              "operatorName": "genre"
            },
            "possibleValues": [
              {
                "stringValue": "Action"
              },
              {
                "stringValue": "Documentary"
              },
              {
                "stringValue": "Drama"
              },
              {
                "stringValue": "Crime"
              },
              {
                "stringValue": "Sci-fi"
              }
            ]
          }
        },
        {
          "name": "userRating",
          "isReturnable": true,
          "isRepeatable": false,
          "isFacetable": true,
          "integerPropertyOptions": {
            "orderedRanking": "ASCENDING",
            "maximumValue": "10",
            "operatorOptions": {
              "operatorName": "score",
              "lessThanOperatorName": "scorebelow",
              "greaterThanOperatorName": "scoreabove"
            }
          }
        }
      ]
    }
  ]
}

Exemplo: arquivo de configuração

O exemplo de arquivo de configuração a seguir mostra os pares de parâmetro key=value que definem o comportamento de um conector de exemplo.

# data source access
api.sourceId=1234567890abcd
api.serviceAccountPrivateKeyFile=./PrivateKey.json

# CSV data structure
csv.filePath=./movie_content.csv
csv.csvColumns=movieId,movieTitle,description,releaseYear,genre,actors,ratings,releaseDate
csv.skipHeaderRecord=true
url.format=https://mymoviesite.com/movies/{0}
url.columns=movieId
csv.datetimeFormat.releaseDate=yyyy-mm-dd
csv.multiValueColumns=genre,actors
csv.multiValue.genre=;
contentTemplate.csv.title=movieTitle

# metadata structured data and content
itemMetadata.title.field=movieTitle
itemMetadata.createTime.field=releaseDate
itemMetadata.contentLanguage.defaultValue=en-US
itemMetadata.objectType.defaultValue=movie
contentTemplate.csv.quality.medium=description
contentTemplate.csv.unmappedColumnsMode=IGNORE

#ACLs
defaultAcl.mode=fallback
defaultAcl.public=true

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

Executar o conector CSV do Cloud Search

Para executar o conector a partir da linha de comando, digite o seguinte comando:

$ java -jar google-cloudsearch-csv-connector-v1-0.0.3.jar -Dconfig=my.config

Por padrão, os registros do conector estão disponíveis na saída padrão. É possível gerar arquivos de registro especificando logging.properties.