Integrações de REST

Uma API RESTFUL é uma API (Application Program Interface - Interface de Programa de Aplicativo) que usa solicitações HTTP para dados GET, PUT, POST e  DELETE  em vários aplicativos. Cada URL é chamado de solicitação, enquanto os dados enviados a você são chamados de resposta.

A Luma oferece suporte a APIs REST para  conexão/interface com outros aplicativos de terceiros.

Criar aplicativo 

Para criar um aplicativo:

1. No menu Tenant , clique em Integrações.
   A página Aplicativos conectados é exibida, como mostrado abaixo. 
   Aqui, podemos configurar uma integração entre a Luma e um sistema de terceiros, que é válida no nível do tenant. Depois que o aplicativo conectado for criado, a próxima etapa será criar a instância do aplicativo e as respectivas operações de serviço web.
   
   
   
2. Clique em Criar aplicativo para criar um novo aplicativo.
   A página Criar aplicativo é exibida, como mostrado abaixo.
   
3. Digite o Nome do aplicativo.
4. Selecione o Tipo de integração.
5. Clique em Criar para concluir a criação do aplicativo.
   O aplicativo criado é disponibilizado na lista Aplicativos conectados . A próxima etapa é criar uma instância.  

Criar instância

Depois de criar o aplicativo, é necessário criar a instância do aplicativo. No caso do tipo de integração REST do aplicativo conectado, você pode fornecer a configuração de solicitação (caminho, consulta, cabeçalhos) no nível de instância do aplicativo que é comum a todas as operações de serviço web.  

Para criar uma instância:

1. Na página Aplicativos conectados , clique em Criar instância , como mostrado abaixo.
   
   
   A página Criar instância é exibida, como mostrado abaixo.
   
2. Digite o Nome e a Descrição da instância. A próxima etapa é definir as credenciais e os detalhes de conexão dessa instância.

3. Insira o URL base ao qual a Luma deve se conectar.

4. O Tipo de autorização é usado pela Luma para efetuar logon e executar as operações especificadas como parte da operação do serviço web.

   A Luma oferece suporte aos seguintes tipos de autorização:

   1. Nenhuma autenticação: use essa opção se não precisar de autenticação para efetuar logon em sistemas de terceiros.
   2. Autenticação básica: use essa opção para autenticar aplicativos externos para interação com o tenant da Luma. A autenticação básica consiste nos seguintes campos:
      
      1. Nome de usuário: especifique o nome de usuário. A Luma o usa como um nome de usuário de autenticação para efetuar logon em sistemas de terceiros.
      2. Senha: especifique a senha. A Luma usa essa senha ao se autenticar no sistema de terceiros.
      3. Nome do cabeçalho de autorização: por padrão, o Nome do cabeçalho de autorização é especificado como Autorização pela Luma.
   3. Token do portador: esse é o token de autenticação exclusivo necessário para aplicativos externos se comunicarem com a API da Luma. 
      
      O token do portador consiste nos seguintes campos:
      
      1. Nome do cabeçalho de autorização: por padrão, o Nome do cabeçalho de autorização é especificado como Autorização pela Luma.
      2. Token: informe o token de autenticação exclusivo necessário para aplicativos externos se comunicarem com a API da Luma.
5. Parâmetro de caminho: o parâmetro de caminho faz parte de um segmento de caminho que ocorre após seu nome. Os parâmetros de caminho oferecem uma oportunidade única de substituir dinamicamente os valores e passá-los no URL. Por exemplo, http://myserver.com/some-path/{parameter1}/path-continued/{parameter2}.
   1. Insira o Campo externo e o Valor.
6. Parâmetro de consulta: os parâmetros de consulta, às vezes, são chamados de parâmetros opcionais. Os parâmetros de consulta são separados dos parâmetros hierárquicos pelo ponto de interrogação. Os parâmetros de consulta são exibidos no URL após o ponto de interrogação (?) depois do nome do recurso. Por exemplo, https://myserver.com/resource-name?param1=value1&param2=value2. 
   1. Insira o Campo externo e o Valor.
7. Cabeçalhos: cabeçalhos são, em sua maioria, classificados como cabeçalhos de solicitação. Será necessário definir os cabeçalhos de solicitação quando você estiver enviando a solicitação.
   1. Insira o Campo externo e o Valor.
      Os cabeçalhos de amostra a seguir são os mais encontrados.
      • Autorização: inclui credenciais contendo as informações de autenticação do cliente para o recurso que está sendo solicitado. 

      • Accept-Charset: esse é um cabeçalho que é definido com a solicitação e informa o servidor sobre quais conjuntos de caracteres são aceitáveis pelo cliente. 

      • Content-Type: indica o tipo de mídia (texto/HTML ou texto/JSON, XML/personalizado) da resposta enviada ao cliente pelo servidor. Isso ajudará o cliente a processar o corpo da resposta corretamente.

8. Clique em Criar para criar a instância do aplicativo.

   A primeira instância que você adicionar será considerada como a instância padrão.

Criar operações

Depois que o aplicativo e a instância são criados, você pode criar as operações necessárias para serem executadas com o sistema de integração. Uma operação define a tarefa que você precisa executar como parte da habilidade. 

Para criar uma operação:

1. Na página Aplicativos conectados , clique em Criar operação , como mostrado abaixo.
   
   
   
   A página Criar operação é exibida, como mostrado abaixo.
   
2. Na guia Detalhes da operação , informe o Nome da operação.
3. O sistema exibe automaticamente o Domínio da habilidade padrão do tenant. 
4. O URI (Uniform Resource Identifier - Identificador de Recurso Uniforme) é usado para se referir ao recurso de informações. Insira o URI.
5. Selecione o método da operação. Ele usa uma estrutura de encadeamento de solicitação de API para que os bots enviem ou solicitem dados dos sites, sistemas e aplicativos web usando serviços web.
   Os seguintes métodos de operação estão disponíveis:
   • Get: para recuperar dados
   • Post: para criar dados
   • Put: para editar os dados
   • Delete: para excluir os dados
   • Patch:  para fazer atualizações parciais no recurso
6. O sistema exibe automaticamente a operação suportada conforme invoca a API REST.
7. Especifique o Tempo limite (em milissegundos), isto é, por quanto tempo esperar por uma resposta do serviço web ao invocar uma solicitação de saída.  O valor padrão é 10000 milissegundos, 10 segundos, e o valor máximo permitido é de 3 minutos, 180000 milissegundos.
8. Clique em Avançar para especificar os detalhes da Configuração da solicitação .
   A página Configuração da solicitação é exibida, como mostrado abaixo.
9. 
10. Parâmetros de caminho: o parâmetro de caminho faz parte de um segmento de caminho que ocorre após seu nome. Os parâmetros de caminho oferecem uma oportunidade única de substituir dinamicamente os valores e passá-los no URL. Por exemplo, http://myserver.com/some-path/{parameter1}/path-continued/{parameter2}. É possível substituir a configuração definida no nível de instância ou continuar usando a mesma e talvez seja necessário adicionar valores e variáveis específicos da operação. 
    1. Insira o Campo externo e o Valor.
11. Parâmetros de consulta: os parâmetros de consulta, às vezes, são chamados de parâmetros opcionais. Os parâmetros de consulta são separados dos parâmetros hierárquicos pelo ponto de interrogação. Os parâmetros de consulta são exibidos no URL após o ponto de interrogação (?) depois do nome do recurso. Por exemplo, https://myserver.com/resource-name?param1=value1&param2=value2. É possível substituir a configuração definida no nível de instância ou continuar usando a mesma e talvez seja necessário adicionar valores e variáveis específicos da operação. 
    1. Insira o Campo externo e o Valor.
12. Cabeçalhos: cabeçalhos são, em sua maioria, classificados como cabeçalhos de solicitação. Será necessário definir os cabeçalhos de solicitação quando você estiver enviando a solicitação. É possível substituir a configuração definida no nível de instância ou continuar usando a mesma e talvez seja necessário adicionar valores e variáveis específicos da operação. 
    1. Insira o Campo externo e o Valor.
       Os cabeçalhos de amostra a seguir são os mais encontrados.
       • Autorização: inclui credenciais contendo as informações de autenticação do cliente para o recurso que está sendo solicitado. 

       • Accept-Charset: esse é um cabeçalho que é definido com a solicitação e informa o servidor sobre quais conjuntos de caracteres são aceitáveis pelo cliente. 

       • Content-Type: indica o tipo de mídia (texto/HTML, texto/JSON, XML/personalizado ou multipart/form-data) da resposta enviada ao cliente pelo servidor. Isso ajudará o cliente a processar o corpo da resposta corretamente.

         • Use multipart/form-data como Content-Type para enviar um arquivo de anexo ao servidor do cliente.
         • Se você deseja substituir as configurações do cabeçalho global definidas no nível da instância, selecione Ignorar cabeçalhos globais. Assim, o sistema vai considerar as configurações definidas no nível de operação. Da mesma forma, você também pode substituir o parâmetro de caminho e o parâmetro de consulta.
13. Carga de saída: a carga de solicitação precisa ser transmitida para conclusão da solicitação. FormData é a codificação padrão que um formulário da web usa para transferir dados. A área da caixa de texto aceita pares de chave-valor simples e JSON complexo/aninhado. 
    

    

14. Para enviar um anexo como carga de saída, use Mapeamento de anexo. Insira um campo externo e selecione um atributo com o tipo de dado Arquivo como Valor.
    
    
    
    

15. Clique em Avançar para criar a Configuração de resposta.

Configuração de resposta

Essa seção é usada para processar os dados ou a resposta recebidos do serviço web externo.

Mapeamento de entrada

Nessa seção, você pode transformar os dados recebidos como uma resposta e atribuí-los aos atributos de usuário Local, Global e Personalizado. Esses dados, por sua vez, podem ser usados em operações de terceiros, conjuntos de regras, execução de habilidades, respostas de bot e no aplicativo Criador de bot da Luma.

 Existem duas maneiras de configurar os atributos. 

Definir atributo:  usado para armazenar informações em um atributo. Selecione Definir Atributo .

Transformar:  as funções de transformação são usadas quando as informações recebidas da entrada ou integração do usuário devem passar por uma transformação para que possam ser usadas na habilidade

Por exemplo, extrair o número do ticket do identificador de ticket recebido de um sistema ITSM e fornecê-lo a um cliente.  A Luma fornece uma variedade de funções de transformação para permitir que os desenvolvedores de habilidades manipulem os dados conforme necessário, como dividir, cortar, subsequência de caracteres, substituir, data e hora personalizadas e muito mais.\

Para definir o mapeamento de entrada, siga as etapas abaixo: 

1. Clique em Adicionar Atributo 
2. Para definir um atributo, adicione os detalhes abaixo.
   1. Tipo de expressão e Expressão: representam o tipo (valor ou JSON) e o caminho do local do valor a ser atribuído ao atributo.
      1. Use Tipo de expressão → Valor quando um valor tiver que ser atribuído ao atributo por ex.: @{response.body}, @{response.code}.
      2. Use Tipo de expressão → JSONPath quando um valor da resposta JSON recebida tiver que ser atribuído ao atributo, isto é,  quando Expressão apontar para um caminho JSON, por exemplo, $.data.TicketIdentifier, $.data.items[*].Priority.
      3. Use Tipo de expressão → JSONPath indireto quando um valor de um atributo do tipo JSON tiver que ser atribuído ao atributo, por exemplo, quando Expressão apontar para um atributo que mantém um caminho JSON, como @{local.items}→$.[*].TicketIdentifier
      4. Use Tipo de expressão → Xpath quando um valor tiver que ser atribuído ao atributo, isto é, quando Expressão apontar para um caminho, por exemplo, //AddResponse/Description
   2. Escopo: representa o escopo do atributo a ser usado para manter os valores de entrada
      1. Use Global para atribuir valor a um atributo global a ser usado na habilidade. Embora os atributos sejam disponibilizados para uso de outras habilidades, o valor fica retido durante a execução da habilidade.
      2. Use Local para criar e definir o valor para um atributo local. Esses atributos são válidos e estão disponíveis somente durante a execução da habilidade. O valor da variável local é retido entre os prompts e é usado para passar dados entre várias integrações, mensagens de usuário ou regras.  Se usado após uma resposta do bot, o valor no atributo Local será perdido.
      3. Use Personalizado do usuário para atribuir valor a um atributo personalizado do usuário. Esses atributos retêm os valores atribuídos, a não ser que sejam substituídos.
   3. Atributo: nome do atributo
   4. Tipo de dado: representa o tipo de dado do valor
3. Para usar a função Transformação, use Transformar. Para obter mais informações sobre como usar as funções de transformação, consulte Usando funções de transformação

Tratamento de erros

Essa seção é usada para definir o comportamento e a resposta do bot para o usuário quando a execução da operação resulta em um erro. Você pode criar várias regras de tratamento de erros a partir das operações de serviço web.

Selecione uma das opções a seguir de modo a definir uma regra para enviar a mensagem de erro. A mensagem de erro será enviada apenas se as condições especificadas forem validadas:

• Fazer a correspondência de qualquer condição abaixo: uma das condições especificadas deve corresponder para análise da mensagem de erro.
• Fazer a correspondência de todas as condições abaixo: todas as condições especificadas devem ser validadas para análise da mensagem de erro.
• Definir critérios personalizados: é possível definir critérios personalizados com base em condições determinadas para análise da mensagem de erro, se validada.
  Por exemplo, 1 e 2 ou 3. A primeira e a segunda condição devem corresponder ou apenas a terceira condição deve corresponder. Você pode inserir apenas números, e, ou, (,) (,)

Especifique @response.StatusCode no campo Chave seguido por um operador.  Veja a seguir uma lista de operadores suportados.

• Igual a
• É diferente de
• É superior a
• É superior ou igual a
• É inferior a
• É inferior ou igual a
• Começa com
• Não começa com
• Termina com
• Não termina com
• Contém
• Não contém
• Está vazio
• Não está vazio
• corresponde ao padrão

Sem tratamento dos dados

Essa seção é usada para definir o comportamento e a resposta do bot ao usuário quando a execução da operação não retorna dados. Você pode criar várias regras para tratamento de cenários sem dados a partir das operações do serviço web. Siga os valores de retorno da API dos sistemas externos dos quais você recebe os dados e, proporcionalmente, escreva/avalie os valores na seção Regras/condições.

Tratamento bem-sucedido

Essa seção é usada para definir o comportamento e a resposta do bot ao usuário quando a execução da operação é bem-sucedida. Crie várias regras de tratamento bem-sucedido a partir das operações de serviço web. 

Editar aplicativo

Para editar um aplicativo:

1. No menu Tenant , clique em Integrações.
2. Todos os aplicativos conectados são listados como mostrado abaixo, onde a opção de edição está disponível.
   
3. Clique no botão Editar . A página Aplicativo conectado é exibida. 
   
4. Aqui, podemos editar os detalhes como tipo de integração, instância padrão, operação de logon e operação de logoff.
   As operações de logon e logoff são úteis quando uma funcionalidade/operação exige uma condição de pré-logon e pós-logoff. 
   Por exemplo, as operações de logon e logoff podem ser usadas para controle de sessão. Ao executar uma operação por meio de uma habilidade, a operação de logon geraria um token e reservaria a sessão. Após a conclusão da tarefa, a operação de logoff vai liberar a sessão. Isso garante a utilização ideal das sessões alocadas ao usuário da API.
   

5. Depois que as operações necessárias forem selecionadas, clique no botão Atualizar para salvar as alterações.