Nesta página do tutorial do Cloud Search, mostramos como configurar um conector de conteúdo e uma origem de dados para indexar dados. Para começar do início deste tutorial, consulte Tutorial de introdução 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 exige credenciais da conta de serviço para chamar as APIs do Cloud Search. Para criar as credenciais:
- Volte para o console do Google Cloud.
- No menu de navegação à esquerda, clique em Credenciais. A página "Credencial" será 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 dessa conta. Esse valor será usado posteriormente.
- Clique em CRIAR. A caixa de diálogo "Permissões da conta de serviço (opcional)" é exibida.
- Clique em CONTINUAR. A caixa de diálogo "Conceda 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 de detalhes da conta de serviço é 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 "Quer permitir downloads em console.cloud.google.com?" aparecer, clique em Permitir.
- Um arquivo de chave privada é salvo no seu computador. Anote o local do arquivo transferido por download. 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, inicialize o suporte de terceiros para o Google Cloud Search.
Para inicializar o suporte de terceiros ao Cloud Search, faça o seguinte:
Seu projeto da plataforma do Cloud Search contém credenciais de conta de serviço. No entanto, para inicializar o suporte de terceiros, é preciso criar credenciais de aplicativos da Web. Consulte Criar credenciais para instruções sobre como criar credenciais de aplicativos da Web. Ao concluir essa 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 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 do Cloud Search, use o seguinte comando curl. Substitua
[YOUR_ACCESS_TOKEN]
pelo token fornecido 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" }
Caso contrário, 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 for concluída, ele 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 conteúdo usando o conector.
- Abra o Google Admin Console.
- Clique no ícone "Apps". A página "Administração dos apps" é exibida.
- Clique em Google Workspace. A página "Apps de administração do Google Workspace" aparece.
- 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 botão amarelo redondo +. A caixa de diálogo "Adicionar nova fonte de dados" será exibida.
- No campo Nome de exibição, 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 criada 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 de 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 origem é usado para configurar o conector de conteúdo.
Gerar um token de acesso pessoal para a API do GitHub
O conector requer acesso autenticado à API do GitHub para ter cota suficiente. Para simplificar, o conector aproveita tokens de acesso pessoal em vez do OAuth. Os tokens pessoais permitem 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 Personal access tokens.
- Clique em Gerar token de acesso pessoal.
- No campo Observação, digite "Tutorial do Cloud Search".
- Confira o escopo public_repo.
- Clique em Gerar token.
- Anote o token gerado. Ele é usado pelo conector para chamar as APIs do GitHub e fornece 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 do serviço que você transferiu por 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
com 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 é criado.
Como iniciar o aplicativo
O ponto de entrada do conector é a classe GithubConnector
. O
método main
instancia o IndexingApplication
do SDK e o inicia.
O ListingConnector
fornecido pelo SDK implementa uma estratégia de travessia
que usa as 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 na 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 de cada vez. Um checkpoint
é retornado com os resultados da travessia que contém a lista de
repositórios a serem indexados nas chamadas subsequentes 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 mais conteúdo. O conector coloca todos os itens na fila sem às vezes. 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 não é considerado modificado.
Como processar a fila
Após a conclusão do traversal completo, 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, o 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 processa a criação da representação de item do Cloud Search. Por exemplo, para criar a representação de itens de conteúdo:
Em seguida, implante a interface de pesquisa.