Oracle Digital Assistant proporciona un componente de servicio REST de llamada incorporado que puede utilizar en las aptitudes de diálogo visual para enviar una solicitud al punto final de un servicio REST. Para poder realizar la solicitud desde un componente Llamar a servicio REST, primero debe configurar el punto final en el separador Servicios REST.

Para agregar un servicio REST:

1. En Oracle Digital Assistant, haga clic en para abrir el menú lateral, seleccione Configuración, seleccione Servicios de API y, a continuación, haga clic en el separador Servicios REST.

2. Proporcione esta información general:

   Campo	Descripción
   Nombre	Nombre único que permite identificar fácilmente el punto final que está configurando. Por ejemplo, para una API de citas, puede asignar a los servicios REST el nombre "appointmentsUser" y "appointmentsUserEntry".
   Punto final	Punto final para acceder a la operación REST. Utilice llaves para delimitar los parámetros de ruta. Por ejemplo: https://example.com/appointments/{userId}. Para los puntos finales de Oracle Cloud Infrastructure, asegúrese de utilizar el punto final para la región de su arrendamiento. Nota: No utilice parámetros de consulta en este campo. Si desea especificar un parámetro de consulta para probar la API, puede utilizar la propiedad Parámetros (como se describe en la siguiente tabla) para cada método que defina para el punto final.
   Descripción	Descripción opcional que explica la finalidad del punto final. Por ejemplo: "Añade y recupera las citas de un usuario".
   Tipo de autenticación	Seleccione cómo autenticar la llamada REST. No se necesita autenticación: seleccione esta opción cuando el servicio no necesite autenticación. Autenticación básica: seleccione esta opción cuando el servicio utilice una autenticación básica. A continuación, deberá indicar un nombre de usuario y una contraseña. Clave de API: seleccione esta opción cuando el servicio utilice una clave de API para la autenticación. A continuación, deberá indicar si la clave se debe transferir como parámetro de ruta o como parámetro de consulta, y deberá especificar el nombre y el valor de la clave. Token de portador: seleccione esta opción cuando el servicio utilice un token de portador para la autenticación. A continuación, deberá especificar el token. Entidad de recurso de OCI: seleccione esta opción cuando acceda a una API de Oracle Cloud Infrastructure.
   Punto final privado	Si tiene un punto final privado configurado para el servicio al que necesita acceder, active este conmutador en la posición Activado y seleccione el punto final privado que está utilizando. Nota: Puede configurar puntos finales privados para servicios que no se exponen públicamente en Internet. Consulte Punto final privado.

3. Para cada método que desee configurar para el punto final, haga clic en + Agregar método, seleccione el método y, a continuación, proporcione esta información:

   Campo	Descripción
   Tipo de contenido	Tipo de contenido que se incluye en el cuerpo de la solicitud. Están soportados application/json y text/plain.
   Cuerpo	Para las solicitudes POST, PUT y PATCH, el cuerpo de la solicitud que se enviará con la solicitud. Puede sustituir este valor en el componente Servicio REST de llamadas. Para cuerpos de solicitud grandes, haga clic en Usar cuadro de diálogo Editar para abrir un editor.
   Parámetros	Puede agregar parámetros de ruta y consulta para probar la solicitud. También puede agregar parámetros de ruta y consulta para configurar los valores por defecto. Tenga en cuenta que los desarrolladores de aptitudes pueden sustituir estos valores de parámetros desde el componente Servicio REST de llamada. Es decir, pueden agregar parámetros en el componente para sustituir los valores configurados en el servicio REST y no agregar los parámetros en los que desean utilizar los valores definidos en la configuración del servicio REST. Para los parámetros de ruta de acceso que están en el punto final, agregue un parámetro de tipo Ruta, defina la clave para que coincida con el parámetro de ruta de acceso y defina el valor deseado. Para los parámetros de consulta que desea transferir en la solicitud REST, agregue un parámetro de tipo Consulta, defina la clave para que coincida con el parámetro de consulta y defina el valor deseado. Si el tipo de autenticación es Clave de API y la clave se transfiere como parámetro de consulta, no agregue un parámetro de consulta para ese valor de clave aquí, ya que ya está configurado. Después de editar el parámetro, haga clic en para agregar el parámetro a la lista. Nota: el valor del parámetro de consulta debe ser una cadena (las expresiones de Freemarker no están soportadas). Este valor solo se utiliza para probar la API. El valor real que utiliza la aptitud debe configurarse en el componente Servicio REST de llamadas.
   Cabeceras	Agregue las cabeceras que desea transferir en la solicitud. Si el tipo de autenticación es Clave de API y la clave se transfiere en una cabecera, no agregue una cabecera para ese valor de clave aquí, ya que ya está configurado.
   Respuesta estática	Puede utilizar la configuración de respuesta estática para los casos en los que necesite una respuesta de reserva siempre que haya un error. También puede utilizarla para configurar datos ficticios con fines de desarrollo o prueba. Para configurar una respuesta estática, seleccione un código de estado de devolución y, a continuación, defina el cuerpo de la respuesta. También puede definir los parámetros y las cabeceras deseados, hacer clic en Solicitud de prueba y, a continuación, en Guardar como respuesta estática para guardar los valores de la respuesta estática.

4. Si desea probar el método, defina la ruta y los parámetros de consulta que se van a utilizar para la ruta, defina las cabeceras necesarias, proporcione un cuerpo de solicitud si es necesario y haga clic en Solicitud de prueba. Aparece un cuadro de diálogo Estado de respuesta con el estado y el cuerpo de la respuesta.

   Consejo:

   Puede hacer clic en Guardar como respuesta estática para guardar el código de estado y el cuerpo en los campos de respuesta estática.

Cuando una aptitud necesite recuperar o actualizar algunos datos a través de un servicio de backend, agregue un estado que utilice el componente de servicio REST de llamada. A continuación se muestra cómo usar ese componente.

1. Configure el punto final en la página Configuración > Servicios de API > Servicios REST, como se describe en Agregar un servicio REST para un punto final. Aquí es donde se definen el punto final, el tipo de autenticación, los métodos soportados, el cuerpo de la solicitud, los parámetros de ruta y consulta, las cabeceras y una respuesta estática opcional.

2. En el flujo deseado del diseñador de flujos de la aptitud, agregue el estado, seleccione Service Integration > Call Rest Service, proporcione un nombre y, a continuación, haga clic en Insertar.

3. Seleccione el servicio REST que configuró en la página Servicios REST.

4. Seleccione el método.

5. Para las solicitudes POST, PUT y PATCH, normalmente deberá proporcionar un cuerpo de solicitud.

   Consejo:

   Si el cuerpo contiene expresiones FreeMarker, puede cambiar Expresión a Activado para ver la coloración de sintaxis FreeMarker. Sin embargo, si lo hace, la validación de sintaxis JSON está desactivada.

6. En la sección Parámetros, configure la ruta y los parámetros de consulta que desea enviar con la solicitud.

   Los parámetros definidos en el componente sustituyen a los parámetros definidos en la configuración del servicio REST. Por el contrario, si no define un parámetro en el componente, la solicitud utiliza el valor del parámetro de la configuración del servicio REST.

   Para los parámetros de consulta definidos en la configuración del servicio REST, si no desea transferir ese parámetro de consulta, defina su valor en ${r""}.

7. Defina las cabeceras que desee enviar con la solicitud.

   Las cabeceras definidas en el componente sustituyen a las cabeceras definidas en la configuración del servicio REST. Por el contrario, si no define una cabecera en el componente, la solicitud utiliza el valor de cabecera de la configuración del servicio REST.

8. Especifique la respuesta que desea devolver una vez finalizada la llamada:

   • Usar respuesta de API de REST real: devuelve la respuesta real del servicio REST.

   • Usar siempre respuesta REST estática: devuelve la respuesta estática configurada en el separador Servicios REST. Esta respuesta es útil durante las fases de desarrollo y prueba, entre otros usos.

   • Devolución mediante respuesta estática: si la solicitud REST se realiza correctamente, se devuelve la respuesta REST. De lo contrario, se devuelve la respuesta estática configurada en el separador Servicios REST.

   Tenga en cuenta que si la configuración del servicio REST no tiene una respuesta estática, la única opción es Usar respuesta real.

9. Para la variable de resultado, seleccione la variable de asignación para almacenar los datos de respuesta. Si aún no existe, haga clic en Crear para crear uno.

   Una vez finalizada la solicitud, la asignación contendrá una propiedad responsePayload para el cuerpo de la respuesta y una propiedad statusCode para el código de estado. El almacenamiento del cuerpo de la respuesta en la variable depende de si la respuesta es un objeto JSON, una matriz JSON o un texto sin formato (cadena):

   • Objeto JSON: el objeto se almacena en la propiedad responsePayload.

   • Matriz JSON: la matriz se almacena en la propiedad responsePayload.responseItems.

   • Texto sin formato: el texto se almacena en la propiedad responsePayload.message.

10. En el separador Transiciones, especifique la transición siguiente y las transiciones de las acciones Correcto y Fallo.

    • La acción correcto se produce cuando statusCode está entre 100 y 299.

    • La acción failure se produce cuando statusCode es 300 y superior.

Para obtener más información sobre este componente, consulte Llamar al servicio REST.