Creación de una extensión personalizada
Si necesita integrar el asistente con un servicio externo que tiene una API REST, puede crear una extensión personalizada importando un documento de OpenAPI.
Después de crear una extensión personalizada, puede conectarla a un asistente como una integración. En las acciones, puede definir pasos que interactúen con el servicio externo llamando a la extensión.
El repositorio Kit de inicio de extensión de watsonx Assistant en GitHub proporciona archivos y Sugerencias de uso avanzado que puede utilizar para crear rápidamente una extensión de trabajo. Cada kit de inicio incluye una definición probada de OpenAPI que puede utilizar para crear una extensión que acceda a una API de terceros, junto con un archivo JSON descargable que puede importar para crear un asistente que acceda a la extensión.
Visión general
OpenAPI (antes denominado Swagger) es un estándar abierto para describir y documentar las API REST. Un documento OpenAPI define los recursos y operaciones que admite una API, incluidos los parámetros de solicitud y los datos de respuesta, junto con detalles como las URL del servidor y los métodos de autenticación.
Un documento de OpenAPI describe una API REST en términos de rutas y operaciones. Una vía de acceso identifica un recurso determinado al que se puede acceder utilizando la API (por ejemplo, una reserva de hotel o un registro de cliente). Una operación define una acción determinada que se puede realizar en ese recurso (como, por ejemplo, crearlo, recuperarlo, actualizarlo o suprimirlo).
El documento OpenAPI especifica todos los detalles de cada operación, incluido el método HTTP que se utiliza, los parámetros de la solicitud, los datos incluidos en el cuerpo de la solicitud y la estructura del cuerpo de la respuesta.
Para más información sobre la especificación OpenAPI, consulte OpenAPI Specification.
Cuando se crea una extensión personalizada, se importa un documento OpenAPI que describe la API REST de un servicio externo. IBM® watsonx™ Assistant analiza el documento OpenAPI para identificar las operaciones admitidas por el servicio externo, junto con información sobre los parámetros de entrada y respuesta para cada operación y los métodos de autenticación admitidos.
Una vez completado este proceso, la extensión personalizada pasa a estar disponible como una nueva integración que puede conectar al asistente. El asistente podrá utilizar la extensión para enviar solicitudes al servicio externo en función de las conversaciones con los clientes. Los valores que se incluyen en la respuesta del servicio se asignan a variables de acción, a las que se puede acceder mediante pasos de acción posteriores.
(Para obtener más información sobre cómo conectar una extensión personalizada a un asistente, consulte Añadir una extensión personalizada).
Preparación de la definición de API
Para crear una extensión personalizada, necesita acceso a un documento de OpenAPI que describa la API REST con la que desea realizar la integración. Muchos servicios de terceros publican documentos de OpenAPI que describen sus API, que puede descargar e importar. Para una API que mantenga su empresa, puede utilizar herramientas estándar para crear un documento OpenAPI que la describa.
El sitio web SwaggerHub ofrece una OpenAPI 3.0 Guía de aprendizajey herramientas para ayudarle a desarrollar y validar el documento OpenAPI. Puede utilizar el editor Swagger en línea para convertir su documento OpenAPI al formato y la versión OpenAPI correctos.
El documento de OpenAPI debe cumplir los siguientes requisitos y restricciones:
-
El documento debe ser compatible con la especificación OpenAPI 3.0. Si tiene un documento de OpenAPI (o Swagger) que utiliza una versión anterior de la especificación, puede utilizar el editor de Swagger en línea para convertirlo a OpenAPI 3.0.
-
El documento debe estar en formato JSON (no se da soporte a YAML). Si tiene un documento YAML, puede utilizar el editor de Swagger en línea para convertirlo a JSON.
-
El cuerpo de solicitud en el script JSON debe presentarse como un objeto. Por ejemplo:
{ name: "Bob", hobbies: ["sleeping", "eating", "walking"] }
-
El tamaño del documento no debe ser superior a
4 MB
si tiene un plan Plus o superior de watsonx Assistant. Sin embargo, si tiene un plan Enteprise con aislamiento de datos, el tamaño del documento no debe ser mayor que8 MB
. -
El
content-type
debe serapplication/json
. -
Para transmitir desde una extensión, el tipo de contenido de la respuesta debe ser
text/event-stream
. -
Cada operación debe tener un
summary
claro y conciso. El texto de resumen se utiliza en la interfaz de usuario para describir las operaciones que están disponibles desde una acción, por lo que debe ser corto y significativo para alguien que está construyendo un asistente. -
Los URL relativos no están soportados actualmente.
-
Solo se da soporte a la autenticación Basic, Bearer, OAuth 2.0y de clave de API.
-
Para la autenticación OAuth 2.0, se da soporte a los tipos de autorización, código de autorización, credenciales de cliente, contraseña y otorgamiento personalizado que empiezan por
x-
. Note thatx-
es utilizado por el mecanismo de autenticación de IBM IAM y por watsonx. -
Los esquemas definidos mediante
anyOf
,oneOf
yallOf
no están soportados actualmente.
Cumplimiento del límite de tiempo de espera de respuesta
Debe respetar el límite de tiempo de espera de respuesta, que es de 48 segundos, cuando llame a una API externa. El valor de tiempo de espera para una extensión personalizada no es configurable.
Creación de la extensión personalizada
Para crear una extensión personalizada basada en la definición de API, siga estos pasos:
-
Vaya a la página
Integraciones.
-
Desplácese a la sección Extensiones y pulse Crear extensión personalizada.
-
Lea la información de Cómo empezar y pulse Siguiente para continuar.
-
En el paso Información básica, especifique la siguiente información sobre la extensión que va a crear:
- Nombre de extensión: un nombre abreviado y descriptivo para la extensión (por ejemplo,
CRM system
oWeather service
). Este nombre que se muestra en el mosaico de la extensión en la página Integraciones, y en la lista de extensiones disponibles en el editor de acciones. - Descripción de la extensión: un breve resumen de la extensión y su función. La descripción está disponible en la página Integraciones.
Pulse Siguiente.
- Nombre de extensión: un nombre abreviado y descriptivo para la extensión (por ejemplo,
-
En el paso Importar OpenAPI, haga clic o arrastre para añadir el documento OpenAPI que describe la API REST con la que desea integrarse.
Si se produce un error al intentar importar el archivo JSON, asegúrese de que el archivo cumple todos los requisitos enumerados en Preparar la definición de API. Edite el archivo para corregir errores o eliminar características no soportadas. Pulse X para borrar el mensaje de error y vuelva a intentar la importación.
Después de importar el archivo correctamente, haga clic en Siguiente.
-
En el paso Gestionar extensión, puede revisar y sustituir el documento OpenAPI importado si es necesario. Para obtener más información sobre la sustitución del documento OpenAPI, consulte Sustitución del documento OpenAPI.
-
En la pestaña Autenticación, verá información sobre los métodos de autenticación definidos en el documento OpenAPI. Tabla. Los campos de la pestaña Autenticación proporcionan detalles sobre los campos de la pestaña Autenticación:
Nombre de campo Descripción Valores Tipo de autenticación El tipo de autenticación configurado en el script OpenAPI. - OAuth 2.0
-Basic Auth
-API key auth
-Bearer auth
Nombre de usuario La credencial de nombre de usuario en el script OpenAPI. Por ejemplo, user
Contraseña La credencial de contraseña configurada en el script OpenAPI. Por ejemplo, Password@123
Servidores El enlace al servidor que está definido en el documento de Open API para conectarse. a la extensión de API. Por ejemplo, https://custom-extension-server.xyz
-
La tabla Revisar operaciones muestra las operaciones que el asistente puede llamar desde un paso de acción. Una operación es una solicitud mediante el uso de un método concreto de HTTP, como
GET
oPOST
, en un recurso concreto.For each operation, a row in the table shows the following information:
- Operación: descripción de la operación, que se deriva de
summary
(si está presente) o dedescription
en el archivo OpenAPI. - Método: el método HTTP utilizado para enviar la solicitud de API para la operación.
- Recurso: la vía de acceso al recurso sobre el que actúa la operación.
Para ver más información sobre una operación, pulse el icono
situado junto a su fila de la tabla. Se muestran los siguientes detalles:
- Parámetros de solicitud: la lista de parámetros de entrada definidos para la operación, junto con el tipo de cada parámetro y si el parámetro es necesario u opcional.
- Propiedades de la respuesta: Las propiedades del cuerpo de la respuesta que se asignan a variables a las que puede acceder el asistente.
- Operación: descripción de la operación, que se deriva de
-
Si está satisfecho con la extensión, pulse Finalizar.
Si desea cambiar algo, suprima la extensión, edite el archivo JSON para realizar los cambios y repita el proceso de importación.
La nueva extensión estará ahora disponible como recuadro en la sección Extensiones del catálogo de integraciones y podrá añadirla al asistente.
Sustitución del documento OpenAPI
Para reemplazar un documento OpenAPI existente, siga estos pasos:
-
Vaya a Integraciones (
) > Extensiones.
-
Haga clic en el botón Abrir de la tarjeta de extensión personalizada para la que desea cambiar la documentación OpenAPI.
-
En el cuadro de diálogo Abrir extensión personalizada, haga clic en Confirmar para ir a la pestaña Administrar extensión.
-
Haga clic en el botón Reemplazar para seleccionar el nuevo documento OpenAPI de su sistema y haga clic en Abrir.
-
Puede revisar los operadores en la sección Revisar operaciones de la pestaña Gestionar extensión.
-
Revise y actualice la información de Autenticación en la pestaña Autenticación después de sustituir el documento OpenAPI.
-
Vaya a la página Acciones y repare cualquier habilidad de acción rota debido a la sustitución del documento OpenAPI.