Este guia é destinado aos administradores do conector CSV (valores separados por vírgula) do Google Cloud Search responsáveis por fazer o download, configurar, executar e monitorar o conector.
Este guia inclui instruções para estas tarefas principais:
- Faça o download do software do conector CSV do Cloud Search.
- Configure o conector para uma fonte de dados CSV específica.
- Implante e execute o conector.
Para entender os conceitos deste documento, é preciso estar familiarizado com o Google Workspace, arquivos CSV e listas de controle de acesso (ACLs, na sigla em inglês).
Visão geral do conector CSV do 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, em que cada linha é um registro de dados.
O conector extrai linhas de um arquivo CSV e as indexa no Cloud Search usando a API Indexing. Depois de indexadas, as linhas podem ser pesquisadas usando os clientes do Cloud Search ou a API Query. O conector também é compatível com ACLs para controlar o acesso dos usuários ao conteúdo.
É possível instalar o conector no Linux ou no Windows. Antes da implantação, verifique se você tem os seguintes componentes:
- Java JRE 1.8 instalado no computador que executa o conector.
- Informações do Google Workspace para estabelecer conexões:
- 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 fornece essas credenciais.
Etapas da implantação
Siga estas etapas para implantar o conector CSV do Cloud Search:
- Instalar o software do conector
- Especificar a configuração do conector
- Configurar o acesso à origem de dados do Cloud Search
- Configurar o acesso ao arquivo CSV
- Especificar nomes de colunas, chaves exclusivas e colunas de data e hora
- Especificar colunas para URLs clicáveis de resultados da pesquisa
- Especificar metadados e formatos de coluna
- Programar a travessia de dados
- Especificar opções de 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 a versão selecionada:
$ git checkout tags/v1-0.0.3
Crie o conector:
$ mvn package
Extraia e instale o conector:
$ 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
Você controla o comportamento do conector usando parâmetros no arquivo de configuração. Os parâmetros configuráveis incluem:
- Acesso à fonte de dados.
- Local e definições do arquivo CSV.
- Colunas de ID exclusivo.
- Opções de traversal e ACL.
Para criar um arquivo de configuração, execute estas ações:
- Abra um editor de texto e nomeie o arquivo como
connector-config.properties. - Adicione parâmetros de configuração como pares
key=value, com cada par em uma nova linha. Para um exemplo de arquivo de configuração, consulte Exemplo de arquivo de configuração.
Mantenha o arquivo de configuração no mesmo diretório do conector para simplificar o rastreamento. Para garantir que o conector reconheça o arquivo, especifique o caminho dele na linha de comando. Caso contrário, o conector usará connector-config.properties no diretório local. Consulte
Executar o conector.
3. Configurar o acesso à origem de dados do Cloud Search
O arquivo de configuração precisa especificar parâmetros para acessar a origem de dados do Cloud Search. Você precisa do ID da origem de dados, do ID da conta de serviço e do caminho para o arquivo de chave privada da conta de serviço.
| Configuração | Parâmetro |
| ID da origem de dados | api.sourceId=1234567890abcdef
Obrigatório. O ID da origem do Cloud Search configurado pelo administrador do Google Workspace. |
| Caminho para a chave privada da conta de serviço | api.serviceAccountPrivateKeyFile=./PrivateKey.json
Obrigatório. O arquivo de chave da conta de serviço para acessibilidade do conector. |
| 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 configurado pelo administrador do Google Workspace. |
4. Configure parâmetros de um arquivo CSV
Identifique o caminho, o formato e a codificação do arquivo.
| Configuração | Parâmetro |
| Caminho para o arquivo CSV | csv.filePath=./movie_content.csv
Obrigatório. O caminho para o arquivo de 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. O padrão é o conjunto de caracteres da plataforma. |
5. Especifique nomes de colunas para índice e colunas-chave exclusivas
Forneça informações de coluna no arquivo de configuração.
| 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. Por padrão, a primeira linha do CSV é usada como cabeçalho. Se |
| Colunas de chave exclusiva | csv.uniqueKeyColumns=movieId
Colunas usadas para gerar um ID exclusivo. O padrão é o código hash do registro. |
6. Especifique as colunas para URLs clicáveis de resultados da pesquisa
Ative os URLs clicáveis para resultados da pesquisa.
| Configuração | Parâmetro |
| Formato do URL de resultados de pesquisa | url.format=https://mymoviesite.com/movies/{0}
Obrigatório. O formato usado para criar o URL de visualização. |
| Parâmetros de URL | 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 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
Esses parâmetros descrevem colunas para preencher metadados do item.
| Configuração | Parâmetro |
| Título | itemMetadata.title.field=movieTitle
itemMetadata.title.defaultValue=Gone with the Wind
O atributo de metadados para o título do documento. O padrão é uma string vazia. |
| URL | itemMetadata.sourceRepositoryUrl.field=url
itemMetadata.sourceRepositoryUrl.defaultValue=https://www.imdb.com/title/tt0031381/
O atributo de metadados do URL do documento nos resultados da pesquisa. |
| Carimbo de data/hora criado | itemMetadata.createTime.field=releaseDate
itemMetadata.createTime.defaultValue=1940-01-17
O atributo de metadados para o 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 do carimbo de data/hora da última modificação 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
Esse parâmetro especifica outros formatos de data/hora para analisar valores de string em campos de data ou data/hora.
| 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
Esses parâmetros especificam como analisar colunas no arquivo CSV.
| Configuração | Parâmetro |
| Ignorar cabeçalho | csv.skipHeaderRecord=true
Ignore a primeira linha. O padrão é false |
| Colunas com vários valores | csv.multiValueColumns=genre,actors
Nomes de colunas com vários valores. |
| Delimitador para colunas com vários valores | csv.multiValue.genre=;
Delimitador para colunas com vários valores. O delimitador padrão é uma vírgula. |
Qualidade da pesquisa
O conector usa um modelo de conteúdo para formatar registros. O campo de título tem a prioridade mais alta. É possível atribuir níveis de prioridade (alta, média, baixa) a outros campos.
| 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:
O valor padrão é APPEND. |
8. Programe a travessia dos dados
Traversal é o processo de descoberta de conteúdo. O conector percorre as linhas CSV e as indexa usando a API Indexing. O conector CSV executa somente traversais completas.
| Configuração | Parâmetro |
| Intervalo de análise | schedule.traversalIntervalSecs=7200
Intervalo entre travessias completas em segundos. O padrão é 86400 (um dia). |
| Travessia na inicialização | schedule.performTraversalOnStart=false
O conector executa uma traversal na inicialização, em vez de
esperar que o primeiro intervalo expire. O padrão é |
9. Especificar opções de ACL
O conector usa ACLs para controlar o acesso. Se o repositório fornecer ACLs, faça upload delas. Caso contrário, configure as ACLs padrão. Defina defaultAcl.mode como um valor
diferente de none.
| Configuração | Parâmetro |
| Modo da ACL | defaultAcl.mode=fallback
Obrigatório. O conector aceita apenas o modo de fallback. |
| Nome padrão da ACL | defaultAcl.name=VIRTUAL_CONTAINER_FOR_CONNECTOR_1
Opcional. Substitui o nome do contêiner virtual usado pelo conector para
ACLs padrão. O valor padrão é |
| ACL pública padrão | defaultAcl.public=true
Define todo o repositório como acesso de domínio público. O 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 definir uma ACL comum para cada registro, defina os seguintes parâmetros:
Os usuários e grupos são considerados definidos pelo domínio local, a menos que tenham o prefixo " O usuário ou grupo padrão é uma string vazia. Forneça opções de usuário e grupo apenas se Se |
Definição do esquema
Para fazer consultas de dados estruturados, configure um esquema para sua fonte de dados.
Por exemplo, considere um arquivo CSV com as seguintes informações sobre filmes:
- movieId
- Título do filme
- Descrição
- Ano
- Data de lançamento
- Atores (valores múltiplos separados por vírgula (,))
- Gênero (múltiplos valores)
- classificações
Com base nessa estrutura, é possível definir o seguinte esquema para sua fonte de dados:
{
"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â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
Executar o conector.
Para executar o conector na linha de 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.