Configurar uma Fonte de dados REST

Cadastro de Fonte de dados (REST)

Para incluir uma nova fonte de dados REST, acione o botão da barra de ferramentas da tela principal. Já para editar uma fonte de dados, selecione-a na lista de registros e acione o botão .

A inclusão e edição de uma fonte de dados REST é realizada por meio de um assistente. Nele, estão disponíveis as seguintes etapas:

dica

A fonte de dados REST pode ser configurada também, para utilizar a APIs de do SoftExpert Suite. Para cada interface REST disponibilizada pelo SoftExpert Suite, é necessário configurar uma fonte de dados REST. Por exemplo: para utilizar a interface RIS_RISK_INTERFACE, é necessário criar uma fonte de dados REST que será utilizada para realizar a conexão e terá os parâmetros necessários para esta interface. Se além desta interface, se deseja utilizar a interface RIS_CONTROL_INTERFACE, será necessário criar outra fonte de dados.

1. Dados do serviço REST

Campo	Descrição
Clique para adicionar uma imagem	Clique neste quadro para incluir uma figura que representará a fonte de dados REST.
Identificador	Informe um número ou sigla para identificar a fonte de dados REST. O identificador deve conter letras e pode conter número, porém, não pode iniciar com números.
Habilitado	Utilize esta opção para habilitar/desabilitar a fonte de dados.
Nome	Informe um nome para a fonte de dados REST.
URL do serviço	Informe a URL do API REST que será utilizada para realizar a integração. Se o serviço for utilizar parâmetros do tipo PATH estes devem ser informados na própria URL (basta adicionar um endpoint, como, por exemplo: https://exampleservice.com/user/{path}). Note que o parâmetro PATH que for informado na URL será adicionado pelo sistema na etapa Parâmetro de entrada, sendo que este deve ter um valor durante o consumo para que a operação seja realizada com sucesso.

Opção	Marcada	Desmarcada
Web Service interno do SoftExpert Suite	Permite selecionar um API REST interna disponibilizada pelo SoftExpert Suite. Com isso, não será necessário criar uma fonte, caso as configurações de domínio do ambiente sejam alteradas.	Não será possível selecionar um API interna do SoftExpert Suite.

Autenticação

Campo da Lista	**Descrição **	Desmarcada
Nenhuma	Selecione esta opção se o serviço não necessitar de autenticação.	Não será possível selecionar um Web Service interno do SoftExpert Suite.
Autenticação básica	Selecione esta opção se o serviço irá requerer apenas o login de usuário e sua senha. Neste caso, serão apresentados os campos onde devem ser informados o usuário e a senha que serão utilizados para esta operação.
Autenticação interna	Selecione esta opção se o serviço for um serviço interno. Neste caso, a autenticação leva em consideração o usuário do SoftExpert Suite que está conectado no momento do consumo.
Autenticação OAuth Client Credentials	Selecione esta opção se o serviço utiliza a autenticação OAuth com o fluxo Client Credentials. Neste caso, serão apresentados os campos onde devem ser informados o Client ID, Client Secret e o Scope. Estas informações provêm do serviço que será consumido. O recurso para obter o token do serviço deve estar de acordo com o padrão especificado pela OKTA. Clique aqui, para mais informações. Consulte a seção Exemplo de uso para obter um exemplo de cadastro de fonte de dados com autenticação OAuth.
Autenticação OAuth Password Grant New	Selecione esta opção se o serviço utiliza a autenticação OAuth com o fluxo Passsword Grant Type. Neste caso, serão apresentados os campos onde devem ser informados os campos Usuario, Senha, Client ID, Client Secret e o Scope. Estas informações provêm do serviço que será consumido. O recurso para obter o token do serviço deve estar de acordo com o padrão especificado pela OKTA. Clique aqui, para mais informações.
API key	Selecione esta opção se o serviço for um serviço interno. Neste caso, será apresentado o campo API Key, no qual deve ser informado o token do usuário que será utilizado para a operação. O token utilizado pode ser gerado por meio da seção API Gateway, da tela de dados do usuário, quando acessada pelo painel de usuário.

cuidado

Ao configurar uma interface REST disponibilizada pelo SoftExpert Suite:

• É possível obter a URL do serviço na seção Reference.
• Para utilizar o usuário conectado, pode-se selecionar a opção "Autenticação interna". Para definir um usuário específico, pode-se selecionar a opção "API key".

Utilize o botão Próximo, da parte inferior do assistente, para acessar a próxima etapa da qual se encontra.

2. Parâmetros de entrada

Nesta etapa, devem ser realizadas as parametrizações necessárias para consumir o serviço REST:

1. No campo Método, selecione o método HTTP que será utilizado para realizar a requisição do serviço:

Campo Lista	Descrição
GET	Realiza a operação de recuperação de dados do serviço adicionado.
POST	Realiza a operação de envio de dados do serviço adicionado.
PUT	Realiza a operação de atualização de dados do serviço adicionado.
DELETE	Realiza a operação de remoção de dados do serviço adicionado.

2. Em seguida, preencha os seguintes campos que serão apresentados:

Campo	Descrição
Identificador	Informe o identificador do parâmetro que será adicionado.
Valor constante	Este campo deve ser preenchido se o parâmetro tiver um valor fixo. Desta forma, quando o serviço for executado, o parâmetro sempre terá o valor constante definido.
Parâmetro	Selecione uma das seguintes opções, para definir o tipo do parâmetro: - QUERY: Indica que o parâmetro será uma Query string. - HEADER: Indica que o parâmetro será um Header necessário para a requisição. - PATH: Esta opção não estará disponível para seleção. Ela será apresentada, já selecionada, quando o parâmetro listado for um endpoint na URL de serviço informada na etapa anterior.
Tipo	Selecione uma das seguintes opções para definir o tipo de dado que será utilizado ao informar o valor do parâmetro: - STRING: O valor do parâmetro será do tipo texto. - NUMERIC: O valor do parâmetro será do tipo numérico. - DECIMAL: O valor do parâmetro será do tipo numérico com casas decimais. - BOOLEAN: O valor do parâmetro será do tipo lógico: true or false. - DATE: O valor do parâmetro será do tipo data. Ao selecionar esta opção, será apresentado o campo Máscara de data. Nele, selecione o formato de data no qual se deverá informar o valor do parâmetro. Veja, a seguir, exemplos de uso.

3. Se o método selecionado anteriormente for POST ou PUT, será apresentado um campo onde deverá ser adicionado um exemplo para o corpo da requisição no formato JSON. O corpo de exemplo será utilizado pelo SoftExpert Suite para mapear os atributos que serão enviados pela requisição. Veja um exemplo de corpo da requisição que poderá ser informado no campo apresentado:

{
  "id": 1,
  "name": "New example name"
}

É possível também, enviar exemplos com tipo de data:

{
  "id": 10,
  "name": "example",
  "admission Date": "MM/dd/yyyy"
}

O parâmetro de data deve estar utilizando o valor de formatação corretamente. Veja a seguir alguns exemplos de formatos de datas:

Formatação	Descrição	Exemplo
MM/dd/yyyy	Padrão americano de data	06/22/2023
dd/MM/yyyy	Padrão europeu de data	15/03/2023
HH:mm:ss	Horas, minutos e segundos	18:37:05
KK:mm:ss a	Horas, minutos e segundos (AM/PM)	07:44:23 PM
dd/MM/yyyy HH:mm:ss	Data, horas, minutos e segundos	26/12/2023 12:30:55
dd/MM/yyyy KK:mm:ss a	Data, horas, minutos e segundos (AM/PM)	12/07/2023 11:50:02 AM
EE MMM dd hh:mm:ss Z yyyy	Data descritiva, dia, horário (AM/PM), fuso horário e ano	Ter ago 16 12:00:00 BRT 2023

4. Para adicionar outro parâmetro, basta clicar novamente no botão Adicionar e repetir o procedimento descrito anteriormente. Para excluir um parâmetro, clique no botão Remover, ao lado do parâmetro desejado.

cuidado

Ao configurar uma interface REST disponibilizada pelo SoftExpert Suite:

• Deve-se selecionar o método POST.
• Pode-se obter o corpo da requisição na seção Reference.

Utilize o botão Próximo, da parte inferior do assistente, para acessar a próxima etapa da qual se encontra.

3. Parâmetros de saída

Nesta etapa, é possível inserir um exemplo do corpo da resposta que será retornada através do formato JSON. Esse exemplo será utilizado pelo SoftExpert Suite para mapear os atributos que serão obtidos na resposta do serviço. Consulte o passo 3 da descrição da etapa Parâmetros de entrada, para obter exemplos do corpo da resposta que pode ser informado nesta etapa.

cuidado

• Ao informar o corpo da requisição/resposta nas seções "Parâmetros de entrada" e "Parâmetros de saída", podem ocorrer problemas que impossibilitam seu avanço para a próxima etapa. Consulte a seção Troubleshooting, para ver os possíveis problemas e suas soluções.
• Ao configurar uma interface REST disponibilizada pelo SoftExpert Suite, pode-se obter o corpo da resposta no documento Guia de integração.

Utilize o botão Próximo, da parte inferior do assistente, para acessar a próxima etapa da qual se encontra.

4. Segurança

Nesta etapa, é possível definir uma lista de segurança para a fonte de dados REST. Habilite a opção desejada:

1. Privado

Se esta opção for habilitada, apenas os usuários definidos nesta aba poderão editar ou visualizar a fonte de dados REST. Para isso, utilize as seguintes colunas:

• Editar: Defina os usuários, equipes, áreas e/ou funções que terão permissão para editar a fonte de dados.
• Visualizar: Defina os usuários, equipes, áreas e/ou funções que terão permissão para visualizar a fonte de dados.

2. Público

Se esta opção estiver habilitada, então todos os usuários do sistema poderão visualizar a fonte de dados REST, porém, apenas os usuários definidos na respectiva coluna poderão editá-la. Por isso, a coluna Visualizar estará desabilitada (visto que a fonte de dados poderá ser visualizada por qualquer usuário). Na coluna Editar, defina os usuários, equipes, áreas e/ou funções que terão permissão para alterar os dados da fonte de dados.

info

Para adicionar um usuário/equipe/área/função à lista de segurança, basta digitar o nome desejado no campo disponível e selecionar a opção correspondente na lista que será apresentada ou pressionar a tecla "Enter" do teclado. Para excluir um usuário/equipe/área/função da lista de segurança, acione o botão localizado ao lado do registro desejado.

Utilize o botão Próximo, da parte inferior do assistente, para acessar a próxima etapa da qual se encontra.

5. Resumo

Nesta etapa, é apresentada uma visão geral das configurações da fonte de dados REST. Utilize o botão Teste de consumo para testar o serviço que está sendo registrado. Veja mais detalhes sobre esta operação na seção "Testar serviço", a seguir.

Seções

• Parâmetros de entrada: Apresenta as informações referentes aos parâmetros identificados na etapa "Parâmetros de entrada".
• Requisição: Apresenta os atributos da requisição definidos na etapa "Parâmetros de entrada", se o método definido for POST ou PUT. Veja como identificar os atributos no tópico "Tipo de dados suportados", a seguir.
• Retorno: Apresenta os atributos do corpo da resposta, definidos na etapa "Parâmetros de saída". Veja como identificar os atributos no tópico "Tipo de dados suportados", a seguir.

Testar Serviço

Para testar o serviço configurado, acione o botão Teste de consumo. Na tela que será aberta, devem ser preenchidas as informações de acordo com as especificações do serviço que está sendo consumido. Entre os parâmetros disponíveis no teste de consumo, podem ser preenchidas as seguintes informações:

Parâmetros	Descrição
Caminho (Path)	Parâmetros do tipo PATH definidos na URL do serviço.
Consulta (Query)	Parâmetros do tipo QUERY definidos na etapa "Parâmetros de entrada".
Cabeçalho (Header)	Parâmetros do tipo HEADER definidos na etapa "Parâmetros de entrada".
Corpo de requisição (Request body)	Parâmetros do corpo de requisição utilizado para consumir os serviços.

Para consumir o serviço, acione o botão Executar, da parte inferior da tela. Podem ser apresentados dois tipos de resposta:

Resposta - Teste de consumo
Sucesso	O consumo foi realizado com sucesso. Neste caso, será possível visualizar um JSON contendo o retorno do serviço via SoftExpert Suite.
Algo deu errado	Ocorreu um problema ao consumir o serviço. Consulte a seção Troubleshooting, para ver as possíveis respostas e seus significados.

Tipo de dados suportados

Acione o botão Finalizar para encerrar a configuração da fonte de dados REST. Com isso, a tela do assistente será fechada. Consulte a seção Exemplo de uso para obter um exemplo de cadastro de fonte de dados com métodos GET e POST e de serviços que poderão ser consumidos com sucesso.

dica

• Utilize o botão Anterior na parte inferior da tela, para retornar para uma etapa anterior da configuração da fonte de dados REST, para realizar as edições necessárias.
• Utilize o botão Fechar na parte inferior da tela, para sair do assistente de configuração da fonte de dados REST. Note que todos os dados informados até o momento atual serão perdidos. Para realizar esta operação efetivamente é necessário confirmar a pergunta feita pelo sistema.