O Oracle Digital Assistant fornece um componente de Serviço REST de Chamada incorporado que você pode usar nas habilidades da Caixa de Diálogo Visual para enviar uma solicitação ao ponto final de um serviço REST. Para poder fazer a solicitação de um componente de Serviço REST de Chamada, primeiro configure o ponto final na guia Serviços REST.

Para adicionar um Serviço REST:

1. No Oracle Digital Assistant, clique em para abrir o menu lateral, selecione Definições, selecione Serviços de API e clique na guia Serviços REST.

2. Forneça estas informações gerais:

   Campo	Descrição
   Nome	Um nome exclusivo que permite identificar facilmente o ponto final que você está configurando. Por exemplo, para uma API de compromissos, você pode nomear os serviços REST "appointmentsUser" e "appointmentsUserEntry".
   Ponto final	O ponto final para acessar a operação REST. Use chaves para delinear parâmetros de caminho. Por exemplo: https://example.com/appointments/{userId}. Para pontos finais do Oracle Cloud Infrastructure, certifique-se de usar o ponto final para a região da sua tenancy. Nota: não use parâmetros de consulta neste campo. Se quiser especificar um parâmetro de consulta para testar a API, você poderá usar a propriedade Parâmetros (conforme descrito na tabela abaixo) para cada método definido para o ponto final.
   Descrição	Uma descrição opcional que explica a finalidade do ponto final. Por exemplo: "Adiciona e recupera compromissos de um usuário".
   Tipo de Autenticação	Selecione como autenticar a chamada REST. Nenhuma Autenticação Necessária: Selecione esta opção quando o serviço não exigir autenticação. Autenticação Básica: Selecione essa opção quando o serviço usar uma autenticação Básica. Em seguida, você precisará fornecer um nome de usuário e uma senha. Chave de API: Selecione essa opção quando o serviço usar uma Chave de API para autenticação. Em seguida, você precisará indicar se a chave deve ser passada como um parâmetro de caminho ou um parâmetro de consulta e precisará especificar o nome e o valor da chave. Token do Portador: Selecione esta opção quando o serviço usar um token do Portador para autenticação. Em seguida, você precisará especificar o token. Controlador de Recursos do OCI: Selecione esta opção quando estiver acessando uma API do Oracle Cloud Infrastructure.
   Ponto Final Privado	Se você tiver um ponto final privado configurado para o serviço que precisa acessar, gire essa chave para a posição Ativado e selecione o ponto final privado que está usando. Observação: Você pode configurar pontos finais privados para serviços que não são expostos publicamente na internet. Consulte Ponto Final Privado.

3. Para cada método que você deseja configurar para o ponto final, clique em + Adicionar Método, selecione o método e forneça estas informações:

   Campo	Descrição
   Tipo de Conteúdo	O tipo de conteúdo incluído no corpo da solicitação. application/json e text/plain são suportados.
   Corpo	Para solicitações POST, PUT e PATCH, o corpo da solicitação a ser enviado com a solicitação. Você pode substituir esse valor no componente Serviço REST de Chamada. Para corpos de solicitação grandes, clique em Usar Caixa de Diálogo Editar para abrir um editor.
   Parâmetros	Você pode adicionar parâmetros de caminho e consulta para testar a solicitação. Você também pode adicionar parâmetros de caminho e consulta para configurar valores padrão. Observe que os desenvolvedores de habilidades podem substituir esses valores de parâmetro do componente Serviço REST de Chamada. Ou seja, eles podem adicionar parâmetros no componente para substituir os valores configurados no serviço REST e não adicionar os parâmetros nos quais desejam usar os valores definidos na configuração do serviço REST. Para os parâmetros de caminho que estão no ponto final, adicione um parâmetro do tipo Caminho, defina a chave para corresponder ao parâmetro de caminho e defina o valor desejado. Para parâmetros de consulta que você deseja transmitir na solicitação REST, adicione um parâmetro do tipo Consulta, defina a chave para corresponder ao parâmetro de consulta e defina o valor desejado. Se o tipo de autenticação for Chave de API e a chave for transmitida como um parâmetro de consulta, não adicione um parâmetro de consulta para esse valor de chave aqui, pois ele já está configurado. Depois de editar o parâmetro, clique em para adicionar o parâmetro à lista. Observação: O valor do parâmetro de consulta deve ser uma string (as expressões Freemarker não são suportadas). Esse valor é apenas para testar a API. O valor real que sua habilidade usa precisa ser configurado no componente Chamar Serviço REST.
   Cabeçalhos	Adicione os cabeçalhos que você deseja passar na solicitação. Se o tipo de autenticação for Chave de API e a chave for passada em um cabeçalho, não adicione um cabeçalho para esse valor de chave aqui, pois ele já está configurado.
   Resposta Estática	Você pode usar a configuração de resposta estática para casos em que você precisa de uma resposta de fallback sempre que houver um erro. Você também pode usá-lo para configurar dados simulados para fins de desenvolvimento ou teste. Para configurar uma resposta estática, selecione um código de status de retorno e defina o corpo da resposta. Como alternativa, defina os parâmetros e cabeçalhos desejados, clique em Solicitação de Teste e, em seguida, clique em Salvar como Resposta Estática para salvar valores para a resposta estática.

4. Se você quiser testar o método, defina o caminho e os parâmetros de consulta a serem usados para o caminho, defina os cabeçalhos necessários, forneça um corpo de solicitação, se necessário, e clique em Solicitação de Teste. Uma caixa de diálogo Status da Resposta é exibida com o status e o corpo da resposta.

   Dica:

   Você pode clicar em Salvar como Resposta Estática para salvar o código de status e o corpo nos campos de resposta estática.

Quando uma habilidade precisar recuperar ou atualizar alguns dados por meio de um serviço de backend, adicione um estado que use o componente Serviço REST de Chamada. Veja aqui como usar esse componente.

1. Configure o ponto final na página Definições > Serviços de API > Serviços REST, conforme descrito em Adicionar um Serviço REST para um Ponto Final. É aqui que você define o ponto final, o tipo de autenticação, os métodos suportados, o corpo da solicitação, o caminho e os parâmetros de consulta, os cabeçalhos e uma resposta estática opcional.

2. No fluxo desejado no designer de fluxo da habilidade, adicione o estado, escolha Integração de Serviço > Chamar Serviço Rest, forneça um nome e clique em Inserir.

3. Selecione o serviço REST que você configurou na página Serviços REST.

4. Selecione o método.

5. Para solicitações POST, PUT e PATCH, normalmente você precisará fornecer um corpo de solicitação.

   Dica:

   Se o corpo contiver expressões FreeMarker, você poderá alternar Expressão para Ativado para ver a coloração da sintaxe FreeMarker. No entanto, se você fizer isso, a validação da sintaxe JSON será desativada.

6. Na seção Parâmetros, configure o caminho e os parâmetros de consulta que você deseja enviar com a solicitação.

   Os parâmetros definidos no componente substituem os parâmetros definidos na configuração do serviço REST. Por outro lado, se você não definir um parâmetro no componente, a solicitação usará o valor do parâmetro da configuração do serviço REST.

   Para parâmetros de consulta definidos na configuração do serviço REST, se você não quiser informar esse parâmetro de consulta, defina seu valor como ${r""}.

7. Defina os cabeçalhos que deseja enviar com a solicitação.

   Os cabeçalhos definidos no componente substituem os cabeçalhos definidos na configuração do serviço REST. Por outro lado, se você não definir um cabeçalho no componente, a solicitação usará o valor do cabeçalho da configuração do serviço REST.

8. Especifique qual resposta você deseja retornar após a conclusão da chamada:

   • Usar Resposta Real da API REST: Retorna a resposta real do serviço REST.

   • Sempre Usar Resposta REST Estática: Retorna a resposta estática configurada na guia Serviços REST. Essa resposta é útil durante as fases de desenvolvimento e teste, entre outros usos.

   • Fallback Usando Resposta Estática: Se a solicitação REST for bem-sucedida, a resposta REST será retornada. Caso contrário, a resposta estática configurada na guia Serviços REST será retornada.

   Observe que, se a configuração do serviço REST não tiver uma resposta estática, a única opção será Usar Resposta Real.

9. Para a variável de resultado, selecione a variável de mapa para armazenar os dados de resposta. Se ele ainda não existir, clique em Criar para criar um.

   Depois que a solicitação for concluída, o mapa conterá uma propriedade responsePayload para o corpo da resposta e uma propriedade statusCode para o código de status. A forma como o corpo da resposta é armazenado na variável depende se a resposta é um objeto JSON, um Array JSON ou um texto simples (string):

   • Objeto JSON: O objeto é armazenado na propriedade responsePayload.

   • Array JSON: O array é armazenado na propriedade responsePayload.responseItems.

   • Texto Simples: O texto é armazenado na propriedade responsePayload.message.

10. Na guia Transições, especifique a transição próxima e as transições para as ações de sucesso e falha.

    • A ação sucesso ocorre quando statusCode está entre 100 e 299.

    • A ação falha ocorre quando statusCode é 300 e acima.

Para obter mais detalhes sobre esse componente, consulte Chamar Serviço REST.