O cliente escreve o nome do produto com um erro de digitação e obtém uma lista vazia de resultados, apesar do produto estar na loja. Um problema semelhante acontece com documentação e catálogos extensos de conteúdos. O Meilisearch permite adicionar à tua aplicação uma pesquisa que aceita erros de digitação. Neste guia, vamos mostrar-te como instalar o Meilisearch na Saplo, enviar os primeiros dados e realizar uma consulta no motor de busca.
O que é o Meilisearch e para quem é indicado
Meilisearch é um motor de pesquisa que disponibiliza uma API REST. Envias-lhe os dados selecionados e o teu site obtém os resultados através da API. É ideal para catálogos de produtos, bases de conhecimento ou sites com artigos. Podes encontrar uma descrição das utilizações na página de hosting do Meilisearch na Saplo.
A própria instalação não liga automaticamente a loja nem cria um formulário de pesquisa no site. Precisarás de uma integração que transfira os dados e apresente os resultados. Para começar, planifica um conjunto público pequeno, por exemplo, nomes e descrições de alguns produtos.
Requisitos e custo do alojamento
O plano mais barato que cumpre os requisitos de instalação é o Box S por 27 € por ano. Este é o ponto de partida para colocar o serviço em funcionamento; a dimensão do índice final, a frequência de importação e as outras aplicações no Box influenciam a necessidade de recursos. Antes de importar todo o catálogo, verifica o espaço disponível e a memória.
Prepara um Box ativo, o nome da aplicação e um domínio ou subdomínio disponível *.saploapp.pl. Para os exemplos abaixo precisas do terminal Bash e do programa curl no teu computador. Não precisas de SSH para o Box: a instalação é feita no painel, o ficheiro inicial é descarregado por SFTP e os pedidos são enviados via HTTPS.
Instalação passo a passo
- Inicia sessão no Painel Saplo e abre o Catálogo de aplicações.
- Escolhe Meilisearch e inicia a criação da aplicação.
- Dá-lhe um nome, por exemplo
wyszukiwarka, e seleciona o Box com recursos disponíveis. - Seleciona um domínio ou subdomínio. Anota o endereço HTTPS exato que é mostrado no painel.
- Confirma a instalação. Aguarda que termine e verifica o Estado da aplicação e possíveis mensagens.
- Liga-te via SFTP, usando os dados de acesso do teu Box. No diretório da aplicação, procura e descarrega o ficheiro
MEILISEARCH-SETUP.txt.
O instalador Saplo inicia o Meilisearch em modo de produção e gera uma chave administrativa. O ficheiro de arranque contém o endereço API e essa chave. A pré-visualização integrada do motor de pesquisa, conhecida do modo de desenvolvimento, está desativada, portanto a ausência de um painel de login no endereço principal não indica uma falha.
Primeira ligação e chave administrativa
No terminal Bash do teu computador, define o endereço a partir do ficheiro inicial, sem a barra final:
MEILI_URL='https://YOUR-APP-ADDRESS'
curl -sS "$MEILI_URL/health"
A resposta correta é {"status":"available"}. Este endpoint verifica a disponibilidade do motor, como descrito na documentação do health check. Ainda não confirma a importação correta dos dados.
Carrega a chave administrativa sem a mostrar no ecrã e sem registar o seu valor no histórico de comandos:
read -r -s -p 'Meilisearch admin key: ' MEILI_ADMIN_KEY
printf '\n'
Cola o valor do ficheiro inicial e pressiona Enter. Esta é a chave Meilisearch, não a password do Saplo. Usa-a apenas num ambiente administrativo de confiança. Não a incluas em JavaScript do site, repositórios ou capturas de ecrã. As regras para separação de permissões estão explicadas na documentação das chaves Meilisearch.
Adicionar os primeiros documentos
Cria no teu computador um ficheiro products-demo.json em UTF-8:
[
{"id": 1, "name": "Ceramic mug", "description": "White coffee mug"},
{"id": 2, "name": "Glass jug", "description": "Tea jug"}
]
No mesmo terminal, na pasta onde está o ficheiro, executa:
curl -sS -X POST "$MEILI_URL/indexes/products-demo/documents?primaryKey=id" \
-H "Authorization: Bearer $MEILI_ADMIN_KEY" \
-H 'Content-Type: application/json' \
--data-binary @products-demo.json
O campo id identifica o documento. A primeira importação vai criar o índice products-demo. A resposta inclui taskUid, que é o número da tarefa de indexação. O esquema de importação está descrito no guia oficial de início rápido do Meilisearch.
Verificação da indexação
Aceitar a consulta não significa que o trabalho terminou. Introduz o número recebido no campo taskUid e verifica a tarefa:
MEILI_TASK_ID='WPISZ_NUMER_TASKUID'
curl -sS "$MEILI_URL/tasks/$MEILI_TASK_ID" \
-H "Authorization: Bearer $MEILI_ADMIN_KEY"
Espera por status: succeeded. Em caso de enqueued ou processing, repete a verificação passados alguns instantes. No caso de failed, lê o campo error e corrige os dados antes de voltar a importar. Podes consultar informações sobre a fila na documentação de tarefas da API.
Chave separada para pesquisa
Cria uma chave com permissão de pesquisa apenas no índice de exemplo:
curl -sS -X POST "$MEILI_URL/keys" \
-H "Authorization: Bearer $MEILI_ADMIN_KEY" \
-H 'Content-Type: application/json' \
--data-binary '{"description":"Search in the public demo catalog","actions":["search"],"indexes":["products-demo"],"expiresAt":null}'
Guarda o valor key da resposta. A limitação para products-demo é intencional: a chave destinada a um único catálogo não deve dar acesso a todos os índices. Esta chave permite ler os resultados da pesquisa, por isso, num frontend público, usa-a apenas para dados que são para publicação. Não coloques neste índice dados de clientes nem notas internas.
Carrega a chave recebida e envia uma consulta:
read -r -s -p 'Meilisearch search key: ' MEILI_SEARCH_KEY
printf '\n'
curl -sS -X POST "$MEILI_URL/indexes/products-demo/search" \
-H "Authorization: Bearer $MEILI_SEARCH_KEY" \
-H 'Content-Type: application/json' \
--data-binary '{"q":"mug"}'
Na tabela hits deverá aparecer o documento "Caneca de cerâmica". Repete a tentativa com a consulta kubke para verificar a tolerância a erros ortográficos com as definições padrão. Depois do trabalho, remove as variáveis do terminal:
unset MEILI_ADMIN_KEY MEILI_SEARCH_KEY
Ligação do teu próprio site
Depois de um teste bem-sucedido, escolhe os dados que devem ir para o índice correto. Define quando a integração adiciona novos registos, atualiza os que foram modificados e remove os que foram retirados. Testa todo o ciclo com um único produto antes da importação completa. Planeia também como vais reconstruir o índice a partir da fonte de dados.
O formulário de pesquisa deve usar uma chave separada com permissões limitadas. Para conteúdos que exigem login, cria um controlo de acesso no lado da tua aplicação. Apenas esconder o campo na interface não limita o acesso via API.
Perguntas mais frequentes
Quanto custa o Meilisearch na Saplo?
O plano mais económico que cumpre os requisitos de instalação é o Box S por 27 € anuais. Para bases de dados maiores, verifica o consumo de recursos durante a importação e a pesquisa.
Porque não vejo o motor de busca no meu domínio?
A instalação Saplo funciona em modo de produção como uma API. Começa por /health, depois faz a importação e a consulta conforme o guia. O formulário para os utilizadores adicionas no teu próprio site.
O que verificar em caso de erro de autorização?
Compara o endereço da API e a chave com a instalação correta. O cabeçalho tem o formato Authorization: Bearer .... A chave apenas com permissão search não serve para importar documentos nem para gerir chaves.
Porque não aparecem resultados após a importação?
Verifica primeiro o estado da tarefa. Depois compara o nome do índice no endereço da consulta com o nome usado na importação. Confirma também se o documento contém o conteúdo procurado.
O Meilisearch puxa automaticamente os produtos da loja?
Não. A instalação activa o motor de pesquisa. A sincronização de dados e o formulário de resultados são garantidos pela integração com a tua loja ou aplicação.
Abre a oferta do Meilisearch na Saplo, inicia o serviço e começa com dois documentos de exemplo. Quando a importação e a pesquisa funcionarem, liga o teu próprio catálogo.
- #Meilisearch
- #Self-hosting
- #Guia
- #Motor de pesquisa
