Esta página do tutorial do Cloud Search mostra como configurar uma fonte de dados e um conector 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
Mude o 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 painel de navegação à esquerda, clique em Credenciais. A página "Credenciais" vai aparecer.
- Clique na lista suspensa + CRIAR CREDENCIAIS e selecione Conta de serviço. A página "Criar conta de serviço" vai aparecer.
- 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)" é exibida.
- Clique em CONTINUAR. A caixa de diálogo "Conceder aos usuários acesso a esta conta de serviço (opcional)" vai aparecer.
- Clique em CONCLUÍDO. A tela "Credenciais" será exibida.
- Em "Contas de serviço", clique no e-mail da conta de serviço. 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 particular" vai aparecer.
- 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 para configurar o 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 outras APIs do Cloud Search, é necessário inicializar o suporte de terceiros para o Google Cloud Search.
Para inicializar o suporte de terceiros para o Cloud Search:
Seu projeto do Cloud Search Platform contém credenciais da conta de serviço. No entanto, para inicializar o suporte de terceiros, é necessário criar credenciais de aplicativo da Web. Para instruções sobre como criar credenciais de aplicativo da Web, consulte Criar credenciais. Depois de 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 caixa 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 "Escopos", digite
https://www.googleapis.com/auth/cloud_search.settings
e clique em Autorizar. O playground do OAuth 2 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
. Por exemplo:{ name: "operations/customers/01b3fqdm/lro/AOIL6eBv7fEfiZ_hUSpm8KQDt1Mnd6dj5Ru3MXf-jri4xK6Pyb2-Lwfn8vQKg74pgxlxjrY" }
Se não funcionar, 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 é concluída, ela contém 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 origem 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 de apps" vai aparecer.
- Clique em Google Workspace. A página "Apps Administração do Google Workspace" vai aparecer.
- Role para baixo e clique em Cloud Search. A página "Configurações do Google Workspace" aparece.
- 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 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 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 "A origem de dados foi criada" é 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 usa tokens de acesso pessoais 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 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. 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, mude 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 que você criou anteriormente. - Salve o arquivo.
Atualizar o esquema
O conector indexa conteúdo estruturado e não estruturado. Antes de indexar os dados, atualize o esquema da origem 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 começar 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 a detectar mudanças 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 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 a GithubRepository
,
implementada pelo conector de exemplo, para acessar conteúdo do GitHub.
Como percorrer os repositórios do GitHub
Durante as travessias completas, o método getIds()
é chamado para enviar itens que podem precisar 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 por vez. Um ponto de verificação
é retornado com os resultados da travessia que contêm a lista de
repositórios a serem indexados em chamadas subsequentes para getIds()
. Se um erro
ocorrer, 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 do hash é usado em transições 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 de forma cega. 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 não modificado.
Processando a fila
Depois que a traversal completa é concluída, o conector começa a consultar a
fila para encontrar itens que precisam ser indexados. O método getDoc()
é chamado para cada item retirado da fila. O método lê
o item do GitHub e o converte na representação adequada
para indexação.
Como o conector é executado com dados em tempo real que podem ser alterados a qualquer
momento, getDoc()
também verifica se o item na fila ainda é válido
e exclui os itens do índice que não existem mais.
Para cada um dos objetos do GitHub indexados pelo conector, o método
indexItem()
correspondente lida com a criação da representação do item para
o Cloud Search. Por exemplo, para criar a representação de itens de conteúdo:
Em seguida, implante a interface de pesquisa.