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:
- Instalar o software do conector CSV do Google Cloud Search
- Especificar a configuração do conector CSV
- Configurar o acesso à origem de dados do Google Cloud Search
- Configurar o acesso ao arquivo CSV
- Especificar os nomes das colunas a serem indexadas, de chave exclusiva e de data e hora
- Especificar as colunas a serem usadas nos URLs clicáveis de resultados de pesquisa
- Especificar informações de metadados e formatos de coluna
- Programar a travessia de dados
- Especificar opções de lista de controle de acesso (ACL)
1. Instalar o SDK
Instale o SDK no seu repositório Maven local.
Clone o repositório do SDK que está no GitHub.
$ git clone https://github.com/google-cloudsearch/connector-sdk.git $ cd connector-sdk/csv
Confira se é a versão desejada do SDK:
$ git checkout tags/v1-0.0.3
Crie o conector:
$ mvn package
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:
- 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. - Salve e nomeie o arquivo de configuração.
O Google recomenda que você nomeie o arquivo de configuração comoconnector-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.
| 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: |
| 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 |
| 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 vai 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 as colunas-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 |
| Colunas de chave exclusiva | csv.uniqueKeyColumns=movieId
As colunas do 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=typeitemMetadata.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 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. |
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 |
| 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:
|
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). |
| 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. 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 sejam acessíveis publicamente por todos os usuários no domínio, defina ambas as opções a seguir com valores:
|
| ACL comum definida | Para especificar uma ACL para cada registro do repositório de dados, defina todos os seguintes valores de parâmetro:
|
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.
- Código do filme
- Título do filme
- Descrição
- Ano
- Data de lançamento
- Atores (valores múltiplos separados por vírgula (,))
- Gênero (múltiplos valores)
- 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.