Testando o Conversation pelo API Explorer

Este é o segundo post sobre o serviço Watson Conversation. Nele irei explicar uma forma muito útil (e que poucas pessoas conhecem) de testar o seu workspace do conversation, simulando uma aplicação real utilizando o serviço e sem a necessidade de escrever uma linha de código.

Quem nunca precisou verificar o retorno de uma API e para isso precisou debugar a aplicação ou colocar aquele velho famoso print() com a resposta do serviço? Pois o API Explorer isto resolverá esses problemas!

O que é o Conversation API Explorer

O Conversation API Explorer é um site que permite ao usuário testar todos os endpoints disponíveis pelo conversation sem necessidade de escrever código. Ele é baseado no Swagger API (recomendadíssimo Framework para expor APIs).

No caso do Conversation ele oferece endpoints para manipulação de workspaces, contra-exemplos, intenções, exemplos e também o envio de mensagem para o serviço. Neste post iremos focar no endpoint de envio de mensagens (/v1/workspaces/{workspace_id}/message).

Motivação

Por que utilizar o API Explorer não a tela de teste do chat apresentada no post anterior? Simples! O Conversation retorna diversos parâmetros e também permite manipular esses parâmetros. Porém, quando utilizamos a tela de teste do chat nós não vemos de fato este retorno por completo, mas sim apenas o que a tela de teste do chat implementou para que fosse mostrado nela.

Quer um exemplo? Na tela de teste, quando enviamos um texto para o Conversation, é mostrado em verde a intenção que foi reconhecida com confiança mais alta. No entanto, é possível solicitar que o Conversation retorne até as 10 confianças reconhecidas, em ordem decrescente de confiança, e a partir disso aplicar algumas metodologias de engajamento com o usuário, como oferecer a segunda intenção reconhecida caso ele não ache que a primeira tenha sido boa o suficiente (Esta técnica eu mostrarei em um post futuro pois exige um conhecimento mais avançado).

Uma outra motivação de utilizar o API Explorer, é que nele é possível saber todos os detalhes dos parâmetros necessários/opcionais dos endpoints (como por exemplo se o parâmetro deve ser passado na query ou path, se ele deve ser string ou inteiro, etc.) e também saber qual o retorno (e também os detalhes de cada propriedade retornada) esperado para determinado endpoint.

Dito isto, vamos aprender a usar o API Explorer!

Utilização

Obter credenciais do serviço e workspace ID

Para podermos testar o nosso workspace do Conversation, é necessário obter as credenciais do serviço do Conversation, e também o workspace ID que desejamos testar (estes itens são explicados com detalhes no primeiro post da série).

Para isto acesse a tool do Conversation clicando aqui. Faça o login com o seu IBM ID caso seja solicitado. Em seguida clique na caixa correspondente ao seu workspace (no exemplo deste post irei usar o mesmo workspace criado anteriormente).

Na tela seguinte clique no ícone

(localizado no canto superior esquerdo da tela) para abrir o menu, e em seguida clique em Credentials, localizado na parte inferior do menu.

Na tela seguinte serão mostrados as credenciais do serviço (username e password) e também o workspace ID. Iremos utilizá-los no API Explorer em seguida.

Inserção das credenciais no API Explorer

Você deve inicialmente inserir o username e o password obtidos nas credencias do serviço nos respectivos campos do canto superior direito da tela do API Explorer.

Inserção do workspace ID

Em seguida, clique no endpoint POST — /v1/workspaces/{workspace_id}/message. No campo workspace_id, coloque o workspace ID obtido anteriormente.

Obs: Caso você não insira os dados do seu serviço e workspace, você ainda conseguirá testar utilizando o API Explorer, porém o API Explorer irá utilizar o workspace ID de demonstração do Conversation, ou seja, você não estará testando o que você desenvolveu.

Chamando o Conversation

A primeira chamada do conversation deve ser um objeto vazio. Motivo: o Conversation é um serviço stateless, ou seja, ele não guarda o estado do lado dele. Então, como que ele sabe de qual nó ele deve continuar ou como ele diferencia uma conversa de outra? Para resolver isto, o Conversation mantém o estado da conversa na própria chamada, dentro de um parâmetro chamado context (no próximo post eu irei explicar com detalhes todos os parâmetros de envio/retorno do Conversation). A primeira chamada vazia serve basicamente para obter este context, em outras palavras, para dizer ao Conversation que queremos iniciar uma nova conversa.

No parâmetro body digite apenas {} (representando um objeto vazio em JSON).

Em seguida clique no botão Try it out! (um pouco mais abaixo na página, porém dentro do mesmo endpoint)

No campo do Responde Body, você verá o retorno abaixo:

{
"intents": [],
"entities": [],
"input": {},
"output": {
"log_messages": [],
"text": [
"Bem vindo ao conversation!"
],
"nodes_visited": [
"node_1_1490746459235"
]
},
"context": {
"conversation_id": "939d7fe8-7a89-4a42-8689-6e37b5a3121e",
"system": {
"dialog_stack": [
{
"dialog_node": "root"
}
],
"dialog_turn_counter": 1,
"dialog_request_counter": 1,
"_node_output_map": {
"node_1_1490746459235": [
0
]
},
"branch_exited": true,
"branch_exited_reason": "completed"
}
}
}

Perceba que o retorno possui o parâmetro context, o que manterá a manter a sessão da conversa. Perceba também que dentro do output há a propriedade “text”, a qual possui exatamente a frase de boas vindas do Conversation criado no post anterior.

Enviando uma mensagem

Agora que já avisamos ao Conversation que queríamos iniciar uma nova conversa e ele nos devolveu o context, podemos então enviar uma mensagem para o serviço, simulando um usuário. Iremos fazer o mesmo teste inicial do post anterior, enviando a mensagem “Ola, bom dia!”.

É necessário devolver todo o context que recebemos para o serviço, para que assim ele saiba de onde ele deve continuar no fluxo. Além do context, devemos enviar o input, com a propriedade text, a qual contém a mensagem do usuário que desejamos enviar para o serviço.

Colei abaixo o JSON de envio da próxima chamada para facilitar. Copie e cole ele no body do request (onde no item anterior enviamos com {}), e clique novamente em Try it out!

Obs: Não esqueça de substituir o context do JSON abaixo pelo retornado no passo anterior, quando você enviou a primeira mensagem de início de chat. Caso você não faça a substituição, o retorno não será conforme esperado.

{
"input": {
"text": "Ola, bom dia!"
},
"context": {
"conversation_id": "939d7fe8-7a89-4a42-8689-6e37b5a3121e",
"system": {
"dialog_stack": [
{
"dialog_node": "root"
}
],
"dialog_turn_counter": 1,
"dialog_request_counter": 1,
"_node_output_map": {
"node_1_1490746459235": [
0
]
},
"branch_exited": true,
"branch_exited_reason": "completed"
}
}
}

O retorno obtido será:

{
"intents": [
{
"intent": "saudacao",
"confidence": 0.9836409091949463
}
],
"entities": [],
"input": {
"text": "Ola, bom dia!"
},
"output": {
"log_messages": [],
"text": [
"Olá para você também."
],
"nodes_visited": [
"node_3_1490748585377"
]
},
"context": {
"conversation_id": "939d7fe8-7a89-4a42-8689-6e37b5a3121e",
"system": {
"dialog_stack": [
{
"dialog_node": "root"
}
],
"dialog_turn_counter": 2,
"dialog_request_counter": 2,
"_node_output_map": {
"node_1_1490746459235": [
0
],
"node_3_1490748585377": [
0
]
},
"branch_exited": true,
"branch_exited_reason": "completed"
}
}
}

Perceba que agora o text dentro do output possui a frase “Olá para você também.”, exatamente o mesmo retorno obtido no teste do post anterior.

O que fazer em seguida

Para continuar o aprendizado, você pode simular todas as conversas realizadas no post anterior, sempre lembrando-se de pegar o context recebido na resposta atual e enviá-lo na chamada seguinte.

A prática deste exercício irá facilitar bastante quando formos desenvolver uma aplicação que se integra com o Conversation.

Posts relacionados

Introdução ao Serviço Watson Conversation.

Originally published at franklinlindemberg.wordpress.com on April 1, 2017.

Senior Software Engineer @ LogMeIn

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store