Design & UX

2 mai, 2018

Melhorando a Experiência do Usuário com Azure Search – Parte 02: gerenciando os documentos

Publicidade

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