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 neste documento, é preciso estar familiarizado com os fundamentos do Google Workspace, dos arquivos CSV e das 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 de valores separados por vírgulas (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. Após a indexação, as linhas individuais dos arquivos CSV podem ser pesquisadas pelos clientes do Cloud Search ou pela API Query. O conector CSV também permite controlar o acesso de usuários ao conteúdo nos resultados da pesquisa usando 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:

    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. Especifique os nomes das colunas a serem indexadas, de chave exclusiva e de data e hora
  6. Especificar as colunas que serão usadas nos URLs clicáveis de resultados da pesquisa
  7. Especificar informações de metadados, formatos de coluna
  8. Programar a travessia de dados
  9. Especificar opções da 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 para que nenhum outro parâmetro de linha de comando seja 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 seu 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.

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

Obrigatório. O ID da origem do Google Cloud Search configurado pelo administrador do Google Workspace, conforme descrito em Gerenciar origens de dados de terceiros.

Caminho para o arquivo de chave privada da conta de serviço api.serviceAccountPrivateKeyFile=./PrivateKey.json

Obrigatório. O arquivo da chave da conta de serviço do Google Cloud Search para a acessibilidade do conector CSV ao Google Cloud Search.

Código da origem de identidade api.identitySourceId=x0987654321

Obrigatório na utilização de usuários e grupos externos. O ID da origem de identidade do Google Cloud Search configurado pelo administrador do Google Workspace.

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.

Configuração Parâmetro
Caminho para o arquivo CSV csv.filePath=./movie_content.csv

Obrigatório. O caminho para o arquivo CSV a ser acessado e o local do qual será extraído o conteúdo para indexação.

Formato do arquivo csv.format=DEFAULT

O formato do arquivo. Os valores possíveis são da classe CSVFormat do Apache Commons CSV (link em inglês).

Os valores de formato incluem: DEFAULT, EXCEL, INFORMIX_UNLOAD, INFORMIX_UNLOAD_CSV, MYSQL, RFC4180, ORACLE, POSTGRESQL_CSV, POSTGRESQL_TEXT e TDF. Se não for especificado, o Cloud Search usará DEFAULT.

Modificador de formato do arquivo csv.format.withMethod=value

Uma modificação na maneira como o Cloud Search lida com o arquivo. Os métodos possíveis são da classe CSVFormat (em inglês) do Apache Commons CSV e incluem aqueles que assumem um único caractere, string ou valor booleano.

Por exemplo, para especificar um ponto e vírgula como delimitador, use csv.format.withDelimiter=;. Para ignorar linhas vazias, use csv.format.withIgnoreEmptyLines=true.

Tipo de codificação do arquivo csv.fileEncoding=UTF-8

O conjunto de caracteres em Java a ser usado quando o Cloud Search lê o arquivo. Se não for especificado, o Cloud Search usará o conjunto de caracteres padrão da plataforma.

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 de chave exclusivas, os valores padrão serão usados.

Configuração Parâmetro
Colunas a serem indexadas csv.csvColumns=movieId,movieTitle,description,actors,releaseDate,year,userratings...

Os nomes das colunas a serem indexadas do arquivo CSV. Se csv.csvColumns não estiver definido, a primeira linha do arquivo CSV será usada como cabeçalho. Se csv.csvColumns estiver definido, ele vai ter precedência sobre a primeira linha do CSV. Se você definiu csv.csvColumns e a primeira linha do arquivo CSV for uma lista de nomes de colunas, defina csv.skipHeaderRecord=true para evitar tentar indexar a primeira linha como dados. Os valores padrão são as colunas na linha de cabeçalho no arquivo.

Colunas de chave exclusiva csv.uniqueKeyColumns=movieId

As colunas CSV cujos valores serão usados para gerar o ID exclusivo de cada registro. Se não for especificado, o hash do registro CSV precisará ser usado como chave exclusiva. O valor padrão é o código hash do registro.

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.

Configuração Parâmetro
Formato do URL de resultados de pesquisa url.format=https://mymoviesite.com/movies/{0}

Obrigatório. O formato para criar um URL de visualização do conteúdo do CSV.

Parâmetros de URL dos resultados de pesquisa url.columns=movieId

Obrigatório. Os nomes das colunas do CSV contendo os valores que serão usados para gerar o URL de visualização do registro.

Parâmetros de URL dos resultados de pesquisa para escape url.columnsToEscape=movieId

Opcional. Os nomes das colunas do CSV contendo os valores que terão escape de URL para gerar um URL de visualização válido.

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

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.

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 do documento para os resultados da 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.field=type
itemMetadata.objectType.defaultValue=movie

O tipo de objeto usado pelo conector, conforme definido no esquema. O conector não indexará nenhum dado estruturado se essa propriedade não for especificada.

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

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.

Configuração Parâmetro
Ignorar cabeçalho csv.skipHeaderRecord=true

Booleano. Ignore o registro de cabeçalho (primeira linha) no arquivo CSV. Se você tiver definido csv.csvColumns e o arquivo CSV tiver uma linha de cabeçalho, será necessário definir skipHeaderRecord=true. Isso impede a indexação da primeira linha do arquivo como dados. Se o arquivo CSV não tiver uma linha de cabeçalho, defina skipHeaderRecord=false. O valor padrão é falso.

Colunas com vários valores csv.multiValueColumns=genre,actors

Os nomes das colunas no arquivo CSV que têm vários valores. O valor padrão é uma string vazia.

Delimitador para colunas com vários valores csv.multiValue.genre=;

O delimitador para as colunas com vários valores. O delimitador padrão é uma vírgula.

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.

Configuração Parâmetro
Título do conteúdo contentTemplate.csv.title=movieTitle

O título do conteúdo é o campo de maior qualidade da pesquisa.

Alta qualidade da pesquisa para campos de conteúdo contentTemplate.csv.quality.high=actors

Campos de conteúdo com um valor de qualidade da pesquisa alto. O padrão é uma string vazia.

Baixa qualidade da pesquisa para campos de conteúdo contentTemplate.csv.quality.low=genre

Campos de conteúdo com um valor baixo de qualidade da pesquisa. O padrão é uma string vazia.

Qualidade da pesquisa média para campos de conteúdo contentTemplate.csv.quality.medium=description

Campos de conteúdo com um valor de qualidade da pesquisa médio. O padrão é uma string vazia.

Campos de conteúdo não especificado contentTemplate.csv.unmappedColumnsMode=IGNORE

Como o conector lida com campos de conteúdo não especificado. Os valores válidos são:

  • APPEND: anexa campos de conteúdo não especificados ao modelo.
  • IGNORE: ignora campos de conteúdo não especificados.

    O valor padrão é APPEND..

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.

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

O conector executa uma traversal completa após um intervalo especificado. Especifique o intervalo entre as traversais em segundos. O valor padrão é 86400 (número de segundos em um dia).

Travessia completa na inicialização do conector schedule.performTraversalOnStart=false

O conector executa uma traversal completa na inicialização do conector, em vez de esperar que o primeiro intervalo expire. O valor padrão é true.

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.*.

Configuração Parâmetro
Modo da ACL defaultAcl.mode=fallback

Obrigatório. O conector CSV depende da funcionalidade padrão da ACL. O conector aceita apenas o modo de fallback.

Nome padrão da ACL defaultAcl.name=VIRTUAL_CONTAINER_FOR_CONNECTOR_1

Opcional. Permite modificar o nome do contêiner virtual usado pelo conector para configurar as ACLs padrão. O valor padrão é "DEFAULT_ACL_VIRTUAL_CONTAINER", mas será possível modificá-lo se vários conectores estiverem indexando o conteúdo na mesma fonte de dados.

ACL pública padrão defaultAcl.public=true

A ACL padrão usada para todo o repositório é definida como acesso de domínio público. O valor padrão é false.

Leitores de grupo de ACL comum defaultAcl.readers.groups=google:group1, group2
Leitores de ACL comum defaultAcl.readers.users=user1, user2, google:user3
Leitores de grupo de ACL comum negados defaultAcl.denied.groups=group3
Leitores de ACL comum negados defaultAcl.denied.users=user4, user5
Acesso ao domínio inteiro Para especificar que todos os registros indexados possam ser acessados publicamente por todos os usuários no domínio, defina as duas opções a seguir com valores:
  • defaultAcl.mode=fallback
  • defaultAcl.public=true
ACL comum definida Para especificar uma ACL para cada registro do repositório de dados, defina todos os valores de parâmetro a seguir:
  • defaultAcl.mode=fallback
  • defaultAcl.public=false
  • defaultAcl.readers.groups=google:group1, group2
  • defaultAcl.readers.users=user1, user2, google:user3
  • defaultAcl.denied.groups=group3
  • defaultAcl.denied.users=user4, user5

    Cada usuário e grupo especificado é considerado um usuário/grupo definido pelo domínio local, a menos que seja prefixado com "google:" (constante literal).

    O usuário ou grupo padrão é uma string vazia. Forneça opções de usuário e grupo somente se defaultAcl.public estiver definido como false. Para listar vários grupos e usuários, use uma lista delimitada por vírgulas.

    Se defaultAcl.mode for definido como none, os registros não poderão ser pesquisados sem ACLs individuais definidas.

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. movieId
  2. movieTitle
  3. Descrição
  4. Ano
  5. releaseDate
  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 arquivo de configuração de exemplo a seguir mostra os pares de parâmetros 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 registros em arquivos especificando logging.properties.