Implantar um conector CSV

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

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

  • Fazer o download do software de 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 princípios básicos do G Suite, arquivos CSV e listas de controle de acesso (ACLs, na sigla em inglês).

Visão geral do conector CSV do Google Cloud Search

O conector CSV do Cloud Search funciona com qualquer arquivo CSV, ou seja, um arquivo de texto delimitado que usa uma vírgula para separar os valores. 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 da API Query ou dos clientes do Cloud Search. O conector CSV também pode controlar o acesso dos usuários ao conteúdo nos resultados de pesquisa usando as 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 G Suite necessárias para estabelecer relações entre o Google Cloud Search e a origem de dados:

    Normalmente, o administrador do G Suite no 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. Instale o software do conector CSV do Google Cloud Search.
  2. Especifique a configuração do conector CSV.
  3. Configure o acesso à fonte de dados do Google Cloud Search.
  4. Configure o acesso ao arquivo CSV.
  5. Especifique os nomes das colunas a serem indexadas, de chave exclusiva e de data e hora.
  6. Especifique as colunas a serem usadas nos URLs clicáveis de resultados de pesquisa.
  7. Especifique as informações de metadados e os formatos das colunas.
  8. Programe a traversal dos dados.
  9. Especifique as opções da lista de controle de acesso (ACL, na sigla em inglês).

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. Especifique a configuração do conector CSV

Como administrador do conector, você controla o comportamento do conector CSV e os atributos que definem os parâmetros no arquivo de configuração do conector. 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, execute estas ações:

  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 ter um local de 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 do conector.

Para garantir que o conector reconheça o arquivo de configuração, especifique o caminho desse arquivo 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. Configure o acesso à origem de dados do Google Cloud Search

Os primeiros parâmetros que cada arquivo de configuração precisa especificar são os necessários para acessar a origem de dados do Cloud Search, conforme mostrado na tabela a seguir. Normalmente, serão necessários os IDs de origem de dados e de conta de serviço, além do caminho para o arquivo de chave privada da conta de serviço, para configurar o acesso do conector ao Cloud Search. As etapas necessárias para configurar uma origem de dados são descritas em Gerenciar origem de dados de terceiros.

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

Obrigatório. O código da fonte do Google Cloud Search configurado pelo administrador do G Suite, conforme descrito em Gerenciar fontes 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 se você estiver usando usuários e grupos externos. O código da origem de identidade do Cloud Search configurado pelo administrador do G Suite.

4. Configure parâmetros de um arquivo CSV

Antes que o conector possa fazer a travessia em um arquivo CSV e extrair dados dele para indexação, é necessário identificar o caminho para o 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 essa configuração não for especificada, 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 um 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 essa configuração não for especificada, 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 indexar e as colunas-chave exclusivas, os valores padrão serão utilizados.

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 terá precedência sobre a primeira linha do CSV. Se csv.csvColumns tiver sido definido e a primeira linha do arquivo CSV for uma lista de nomes de colunas, defina csv.skipHeaderRecord=true para evitar a indexação da 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 do CSV contendo os valores que serão usados para gerar o código exclusivo de cada registro. Se não especificadas, o hash do registro CSV precisará ser usado como chave exclusiva. O valor padrão é o código hash do registro.

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

Quando uma pesquisa é feita 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, serão usados os valores padrão. 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 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.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 adicionais 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.

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, serão usados os valores padrão. 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 csv.csvColumns tiver sido definido 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 os define no início da execução do conector. Depois, ele usa um modelo de conteúdo para formatar cada registro de dados 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 de pesquisa para todos os outros campos de conteúdo como alta, média ou baixa. 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 de pesquisa para campos de conteúdo contentTemplate.csv.quality.low=genre

Campos de conteúdo com um valor baixo de qualidade de 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: corrige campos de conteúdo não especificados no modelo
  • IGNORE: ignora campos de conteúdo não especificados

    O valor padrão é APPEND.

8. Programe a travessia dos dados

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

A travessia 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 travessias incrementais.

Os parâmetros de programação determinam a frequência com que o conector aguarda entre travessias. 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 (quantidade de segundos em um dia).

Traversal total 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. Especifique as opções de ACL

O conector CSV do Google Cloud Search oferece suporte a permissões por meio de listas de controle de acesso (ACLs, na sigla em inglês) 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 de 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 fornecer as informações padrão de ACL 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 é falso.

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 sejam acessíveis publicamente por todos os usuários no domínio, defina ambas as 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 seguintes valores de parâmetro:
  • 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 apenas se defaultAcl.public for 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 origem 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 origem 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": "Documentry"
                  },
                  {
                    "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 key=value do parâmetro 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 "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 registro em arquivos especificando logging.properties.