Nesta página do tutorial do Cloud Search, você aprende a configurar um conector de origem de dados e de conteúdo para indexação de dados. Para começar deste tutorial, consulte o Tutorial de primeiros passos do Cloud Search.
Criar o conector
Altere seu diretório de trabalho para o diretório cloud-search-samples/end-to-end/connector
e execute este comando:
mvn package -DskipTests
O comando faz o download das dependências necessárias para criar o conector de conteúdo e compila o código.
Criar credenciais de conta de serviço
O conector requer credenciais de conta de serviço para chamar as APIs do Cloud Search. Para criar as credenciais:
- Volte para o console do Google Cloud.
- No painel de navegação à esquerda, clique em Credenciais. A página "Credencial" é exibida.
- Clique na lista suspensa + CRIAR CREDENCIAIS e selecione Conta de serviço. A página "Criar conta de serviço" é exibida.
- No campo Nome da conta de serviço, digite "tutorial".
- Anote o valor do ID da conta de serviço (logo após o nome da conta de serviço). Esse valor será usado mais tarde.
- Clique em CRIAR. A caixa de diálogo "Permissões da conta de serviço (opcional)" vai aparecer.
- Clique em CONTINUAR. A caixa de diálogo "Conceder aos usuários acesso a essa conta de serviço (opcional)" será exibida.
- Clique em CONCLUÍDO. A tela "Credenciais" será exibida.
- Em "Contas de serviço", clique no e-mail da conta. A página "Detalhes da conta de serviço" será exibida.
- Em "Chaves", clique na lista suspensa ADICIONAR CHAVE e selecione Criar nova chave. A caixa de diálogo "Criar chave privada" será exibida.
- Clique em CRIAR.
- (Opcional) Se a caixa de diálogo "Do you want to allow downloads on console.cloud.google.com?" for exibida, clique em Allow.
- Um arquivo de chave privada é salvo no seu computador. Anote o local do arquivo salvo. Esse arquivo é usado na configuração do conector de conteúdo para que ele possa se autenticar ao chamar as APIs do Google Cloud Search.
Inicializar o suporte de terceiros
Antes de chamar qualquer outra API do Cloud Search, você precisa inicializar o suporte de terceiros para o Google Cloud Search.
Para inicializar o suporte de terceiros para o Cloud Search:
Seu projeto de plataforma do Cloud Search contém as credenciais da conta de serviço. No entanto, para inicializar o suporte de terceiros, é necessário criar credenciais de aplicativos da Web. Para instruções sobre como fazer isso, consulte Criar credenciais. Ao concluir esta etapa, você terá um ID e um arquivo de chave secreta do cliente.
Use o OAuth 2 Playground do Google para receber um token de acesso:
- Clique em "Configurações" e marque a opção Usar suas próprias credenciais de autenticação.
- Insira o ID e a chave secreta do cliente da etapa 1.
- Clique em Fechar.
- No campo de escopos, digite
https://www.googleapis.com/auth/cloud_search.settings
e clique em Autorizar. O OAuth 2 Playground retorna um código de autorização. - Clique em Trocar código de autorização dos tokens. Um token é retornado.
Para inicializar o suporte de terceiros para o Cloud Search, use o seguinte comando curl. Substitua
[YOUR_ACCESS_TOKEN]
pelo token recebido na etapa 2.curl --request POST \ 'https://cloudsearch.googleapis.com/v1:initializeCustomer' \ --header 'Authorization: Bearer [YOUR_ACCESS_TOKEN]' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{}' \ --compressed
Se funcionar, o corpo da resposta vai ter uma instância de
operation
. Exemplo:{ name: "operations/customers/01b3fqdm/lro/AOIL6eBv7fEfiZ_hUSpm8KQDt1Mnd6dj5Ru3MXf-jri4xK6Pyb2-Lwfn8vQKg74pgxlxjrY" }
Se não conseguir, entre em contato com o suporte do Cloud Search.
Use operations.get para verificar se o suporte de terceiros foi inicializado:
curl \ 'https://cloudsearch.googleapis.com/v1/operations/customers/01b3fqdm/lro/AOIL6eBv7fEfiZ_hUSpm8KQDt1Mnd6dj5Ru3MXf-jri4xK6Pyb2-Lwfn8vQKg74pgxlxjrY?key= [YOUR_API_KEY]' \ --header 'Authorization: Bearer [YOUR_ACCESS_TOKEN]' \ --header 'Accept: application/json' \ --compressed
Quando a inicialização de terceiros estiver concluída, ela conterá o campo
done
definido comotrue
. Exemplo:{ name: "operations/customers/01b3fqdm/lro/AOIL6eBv7fEfiZ_hUSpm8KQDt1Mnd6dj5Ru3MXf-jri4xK6Pyb2-Lwfn8vQKg74pgxlxjrY" done: true }
Criar a fonte de dados
Em seguida, crie uma fonte de dados no Admin Console. A fonte de dados fornece um namespace para indexar o conteúdo usando o conector.
- Abra o Google Admin Console.
- Clique no ícone "Apps". A página "Administração de apps" é exibida.
- Clique em Google Workspace. A página "Apps Administração do Google Workspace" é exibida.
- Role para baixo e clique em Cloud Search. A página "Configurações do Google Workspace" é exibida.
- Clique em Origens de dados de terceiros. A página "Fontes de dados" é exibida.
- Clique no + amarelo redondo. A caixa de diálogo "Adicionar nova fonte de dados" será exibida.
- No campo Display name, digite "tutorial".
- No campo Endereços de e-mail da conta de serviço, insira o endereço de e-mail da conta de serviço que você criou na seção anterior. Se você não souber o endereço de e-mail da conta de serviço, procure o valor na página contas de serviço.
- Clique em ADICIONAR. A caixa de diálogo "Fonte de dados criada com sucesso" é exibida.
- Clique em *OK. Anote o ID da fonte recém-criada. O ID da fonte é usado para configurar o conector de conteúdo.
Gerar um token de acesso pessoal para a API GitHub
O conector requer acesso autenticado à API do GitHub para ter cota suficiente. Para simplificar, o conector usa tokens de acesso pessoais em vez do OAuth. Com os tokens pessoais, é possível fazer a autenticação como um usuário com um conjunto limitado de permissões, semelhante ao OAuth.
- Faça login no GitHub.
- No canto superior direito, clique na sua foto do perfil. Será exibido um menu suspenso.
- Clique em Configurações.
- Clique em Configurações do desenvolvedor.
- Clique em Tokens de acesso pessoal.
- Clique em Generate personal access token.
- No campo Observação, digite "Tutorial do Cloud Search".
- Verifique o escopo public_repo.
- Clique em Gerar token.
- Anote o token gerado. Ela é usada pelo conector para chamar as APIs do GitHub e fornece uma cota de API para realizar a indexação.
Configurar o conector
Depois de criar as credenciais e a fonte de dados, atualize a configuração do conector para incluir estes valores:
- Na linha de comando, altere o diretório para
cloud-search-samples/end-to-end/connector/
. - Abra o arquivo
sample-config.properties
com um editor de texto. - Defina o parâmetro
api.serviceAccountPrivateKeyFile
como o caminho do arquivo das credenciais de serviço que você fez o download anteriormente. - Defina o parâmetro
api.sourceId
como o ID da fonte de dados que você criou anteriormente. - Defina o parâmetro
github.user
como seu nome de usuário do GitHub. - Defina o parâmetro
github.token
como o token de acesso criado anteriormente. - Salve o arquivo.
Atualizar o esquema
O conector indexa conteúdo estruturado e não estruturado. Antes de indexar os dados, é necessário atualizar o esquema da fonte de dados. Execute o seguinte comando para atualizar o esquema:
mvn exec:java -Dexec.mainClass=com.google.cloudsearch.tutorial.SchemaTool \
-Dexec.args="-Dconfig=sample-config.properties"
Executar o conector.
Para executar o conector e iniciar a indexação, execute o comando:
mvn exec:java -Dexec.mainClass=com.google.cloudsearch.tutorial.GithubConnector \
-Dexec.args="-Dconfig=sample-config.properties"
A configuração padrão do conector é indexar um único repositório na organização googleworkspace
. A indexação do repositório leva cerca de um minuto.
Após a indexação inicial, o conector continua pesquisando alterações no repositório que precisam ser refletidas no índice do Cloud Search.
Como revisar o código
As seções restantes examinam como o conector foi criado.
Como iniciar o aplicativo
O ponto de entrada para o conector é a classe GithubConnector
. O
método main
instancia e inicia o IndexingApplication
do SDK.
O ListingConnector
fornecido pelo SDK implementa uma estratégia de travessia que usa filas do Cloud Search para rastrear o estado dos itens no índice. Ele delega para GithubRepository
, implementado pelo conector de amostra, para acessar o conteúdo do GitHub.
Como percorrer os repositórios do GitHub
Durante as travessias completas, o método getIds()
é chamado para enviar itens que talvez precisem ser indexados para a fila.
O conector pode indexar vários repositórios ou organizações. Para minimizar o
impacto de uma falha, um repositório do GitHub é transferido por vez. Um checkpoint
é retornado com os resultados da travessia que contém a lista de
repositórios a serem indexados nas chamadas seguintes para getIds()
. Se ocorrer um erro,
a indexação será retomada no repositório atual, em vez de começar
do início.
O método collectRepositoryItems()
processa a travessia de um único
repositório do GitHub. Esse método retorna uma coleção de ApiOperations
,
que representa os itens a serem enviados para a fila. Os itens são enviados como um nome de recurso e um valor de hash que representa o estado atual do item.
O valor de hash é usado em travessias subsequentes dos repositórios do GitHub. Esse valor fornece uma verificação leve para determinar se o conteúdo foi alterado sem precisar fazer upload de outros conteúdos. O conector enfileira todos os itens às cegas. Se o item for novo ou o valor de hash tiver sido alterado, ele será disponibilizado para pesquisa na fila. Caso contrário, o item é considerado inalterado.
Como processar a fila
Após a conclusão da travessia completa, o conector começa a pesquisar na fila os itens que precisam ser indexados. O método getDoc()
é chamado para cada item extraído da fila. O método lê
o item do GitHub e o converte na representação adequada
para indexação.
Como o conector está sendo executado em dados ativos que podem ser alterados a qualquer momento, getDoc()
também verifica se o item na fila ainda é válido e exclui todos os itens do índice que não existem mais.
Para cada um dos objetos do GitHub que o conector indexa, o método indexItem()
correspondente cuida da criação da representação do item para o Cloud Search. Por exemplo, para construir a representação de itens de conteúdo:
Em seguida, implante a interface de pesquisa.