No artigo anterior, apresentei o serviço do Azure Search e como construir um índice. Porém, é preciso ter em mente que a qualidade das pesquisas vai depender – em grande parte – do quão completa e bem estruturada é a base de conhecimento associada ao índice.
A escolha do conteúdo a ser indexado obviamente é essencial, mas é importante gerenciar e dar manutenção nesta base ao longo da vida útil do serviço. Este é o tema deste artigo.
Gerenciando a base de conhecimento
Como vimos, cada índice tem sua própria base de conhecimento, que nada mais é do que uma coleção de arquivos. O Azure Search pode ser usado gratuitamente com até três índices, num total de 50 Mb.
É importante conhecer o conteúdo de cada base. Por exemplo, posso facilmente verificar quantos documentos foram carregados. Novamente usarei a API de REST para essa operação, que vai usar o operador “$count”:
Endpoint completo para contagem de documentos:
https://wcrivelini-test1.search.windows.net/indexes/publications/docs/$count?api-version=2016-09-01
Verbo | GET |
Headers | Content-type: application/JSON Api-Key: [chave de segurança do seu serviço] |
Authorization | “No Auth” |
Body (raw) | vazio |
Esta consulta me informa que existem 209 documentos cadastrados na base. Resolvo, então, pedir uma listagem de quem são estes documentos. Como a base que cadastrei traz informações sobre as minhas publicações (artigos, podcasts, etc), é suficiente para eu identificar apenas o título dos artigos cadastrados na base. Então usarei o operador “$select” para exibir o conteúdo do campo “Título”.
Observação: lembre-se que as ações, endpoints e os nomes de campo são todos sensíveis a maiúsculas.
Endpoint completo para contagem de documentos:
https://wcrivelini-test1.search.windows.net/indexes/publications/docs?$select=TITULO&api-version=2016-09-01
Verbo | GET |
Headers | Content-type: application/JSON Api-Key: [chave de segurança do seu serviço] |
Authorization | “No Auth” |
Body (raw) | vazio |
O resultado é um JSON com a listagem de artigos. Clique aqui para ver este documento. O leitor mais observador vai perceber que este documento traz apenas 50 títulos, mas perceberá também que existe um link no final do documento para retornar os próximos 50 títulos (observe o parâmetro SKIP no final do endpoint).
“@odata.nextLink”: “https://wcrivelini-test1.search.windows.net/indexes(‘publications’)/docs?$select=TITULO&api-version=2016-09-01&$skip=50” |
Alterando a base de conhecimento
O Azure Search oferece também quatro ações para gerenciamento dos documentos:
Ação 1 – Upload
Serve para acrescentar novos documentos. Use o verbo POST e inclua o documento desejado no campo Body.
Veja um exemplo.
Endpoint:
https://wcrivelini-test1.search.windows.net/indexes/publications/docs/index?api-version=2016-09-01
Verbo | POST |
Headers | Content-type: application/JSON Api-Key: [chave de segurança do seu serviço] |
Authorization | “No Auth” |
Body (raw) | { “value” : [ {“@search.action”: “upload”, “id” : “210”, “MIDIA” : “iMasters”, “LINGUA” : “Português” , “AUTOR” : “Wagner Crivelini”, “TITULO” : “Melhorando a Experiência do Usuário com AZURE Search – Parte 1 – Criando o Serviço”, “TEMA” : “Recentemente participei de um projeto envolvendo a criação de um bot em que usaríamos diversos serviços cognitivos do AZURE, incluindo o LUIS, que trata da compreensão de linguagem. Ocorre que decidimos incluir uma espécie de “tratamento de erro” no nosso bot. Caso o LUIS não entendesse o que usuário pedia (isto é: se ele não estivesse treinado para compreender determinado tipo de solicitação), nós iríamos pesquisar nossa base de conhecimento para verificar se existia algum tópico que pudesse servir para “desambiguação” deste pedido. Foi então que decidimos usar AZURE SEARCH, que eu apresento a seguir.”, “DATA” : “43215”, “LINK” : “https://bit.ly/azsearch1”, “TAGS” : “mecanismo de busca” } ] } |
Resultado
{ "@odata.context": "https://wcrivelini-test1.search.windows.net/indexes('publications')/$metadata#Collection(Microsoft.Azure.Search.V2016_09_01.IndexResult)", "value": [ { "key": "210", "status": true, "errorMessage": null, "statusCode": 201 } ] }
Ação 2 – Delete
Para excluir documentos específicos, existe a ação Delete. O exemplo a seguir mostra como executá-la.
Endpoint:
https://wcrivelini-test1.search.windows.net/indexes/publications/docs/index?api-version=2016-09-01
Verbo | POST |
Headers | Content-type: application/JSON Api-Key: [chave de segurança do seu serviço] |
Authorization | “No Auth” |
Body (raw) | { “value” : [ { “@search.action”: “delete”, “id” : “210” } ] } |
Resultado
{ "@odata.context": "https://wcrivelini-test1.search.windows.net/indexes('publications')/$metadata#Collection(Microsoft.Azure.Search.V2016_09_01.IndexResult)", "value": [ { "key": "210", "status": true, "errorMessage": null, "statusCode": 200 } ] }
Ação 3 – Merge
Quando é necessário alterar campos específicos, se usa esta operação. O próximo exemplo altera o link do documento.
Endpoint:
https://wcrivelini-test1.search.windows.net/indexes/publications/docs/index?api-version=2016-09-01
Verbo | POST |
Headers | Content-type: application/JSON Api-Key: [chave de segurança do seu serviço] |
Authorization | “No Auth” |
Body (raw) | { “value” : [ { “@search.action”: “merge”, “id” : “128” , “TAGS” : “data science” } ] } |
Resultado
{ "@odata.context": "https://wcrivelini-test1.search.windows.net/indexes('publications')/$metadata#Collection(Microsoft.Azure.Search.V2016_09_01.IndexResult)", "value": [ { "key": "128", "status": true, "errorMessage": null, "statusCode": 200 } ] }
Ação 4 – MergeOrUpload
Quando se faz uma carga de vários documentos e não se tem certeza quais já existem na base de conhecimento, é necessário usar a ação “mergeOrUpload” para evitar erros de execução. Veja um exemplo em que são tratados dois documentos. Um que existe (id 129) e outro não (id 210, que foi excluído anteriormente).
Endpoint:
https://wcrivelini-test1.search.windows.net/indexes/publications/docs/index?api-version=2016-09-01
Verbo | POST |
Headers | Content-type: application/JSON Api-Key: [chave de segurança do seu serviço] |
Authorization | “No Auth” |
Body (raw) | { “value” : [ { “@search.action”: “mergeOrUpload”, “id” : “129” , “TAGS” : “engenharia, funcionalidades, inteligência artificial, AI, machine learning, aprendizado de máquina” }, {“@search.action”: “mergeOrUpload”, “id” : “210”, “MIDIA” : “iMasters”, “LINGUA” : “Português” , “AUTOR” : “Wagner Crivelini”, “TITULO” : “Melhorando a Experiência do Usuário com AZURE Search – Parte 1 – Criando o Serviço”, “TEMA” : “Recentemente participei de um projeto envolvendo a criação de um bot em que usaríamos diversos serviços cognitivos do AZURE, incluindo o LUIS, que trata da compreensão de linguagem. Ocorre que decidimos incluir uma espécie de “tratamento de erro” no nosso bot. Caso o LUIS não entendesse o que usuário pedia (isto é: se ele não estivesse treinado para compreender determinado tipo de solicitação), nós iríamos pesquisar nossa base de conhecimento para verificar se existia algum tópico que pudesse servir para “desambiguação” deste pedido. Foi então que decidimos usar AZURE SEARCH, que eu apresento a seguir.”, “DATA” : “43215”, “LINK” : “https://bit.ly/azsearch1”, “TAGS” : “mecanismo de busca” } ] } |
Resultado
{ "@odata.context": "https://wcrivelini-test1.search.windows.net/indexes('publications')/$metadata#Collection(Microsoft.Azure.Search.V2016_09_01.IndexResult)", "value": [ { "key": "129", "status": true, "errorMessage": null, "statusCode": 200 }, { "key": "210", "status": true, "errorMessage": null, "statusCode": 201 } ] }
Note que, para todas as ações, usamos os mesmos endpoints, verbos e cabeçalhos. A única coisa que mudou foi o valor do campo “@search.action” em cada um dos casos.
No próximo artigo da série, o tema são os diversos recursos disponíveis para buscas nas bases de conhecimento.
Leituras sugeridas
- Azure Search Documentation, MICROSOFT.
- Adding Search Abilities to Your Apps with Azure Search por Chad Campbell, PLURALSIGHT.