SQL Server

Power Omni puede conectarse a su base de datos mediante Stored Procedures definidos por usted o por su equipo, permitiéndole tener una IA capaz de extraer o insertar datos directamente en su base de datos a través de una lógica controlada que combina lo mejor de dos mundos: inteligencia artificial (decidiendo qué ejecutar y cuándo) y seguridad (usted mantiene el control total sobre lo que puede leer o modificar).

Para que esto funcione, usted necesita desplegar una API HTTP que se sitúa entre Power Omni y su instancia de SQL Server. Esta API es un servicio exclusivo proporcionado sin costo a los clientes de Power Omni. Esta documentación lo guiará por las diferentes formas en que puede configurar esta API, ya sea que su SQL Server esté on-premises o en la nube.

Hacer que Power Omni se comunique con su SQL Server implica básicamente los siguientes pasos:

1. Crear el acceso en su instancia de SQL Server
2. Desplegar la API de integración
3. Conectar Power Omni a la API
4. Crear y documentar los procedures

El diagrama a continuación resume el flujo de datos de cómo funciona esta integración.

sequenceDiagram
    User->>PowerOmni: pregunta
    PowerOmni->>PowerOmni: decide qué procedures usar
    PowerOmni->>IntegrationApi: https post ejecuta procedure {param1,param2,...}
    
    IntegrationApi->>SqlServerInstance: exec proc (conexión con SQL Server)...
    Actor YouOrDevTeam
    YouOrDevTeam->>SqlServerInstance: Crea/altera procedures
    

    
    SqlServerInstance->>IntegrationApi: resultados o errores
    IntegrationApi->>PowerOmni: respuesta JSON
    PowerOmni->>User: usa el resultado del procedure y genera la respuesta
    
    

Crear el acceso en SQL Server

El primer paso es preparar su instancia de SQL Server. Básicamente, necesitará crear una base de datos (o usar una existente) y un Login y una Contraseña.

A continuación se muestra un script SQL de ejemplo que crea una base de datos y un usuario llamados PowerOmni (copie y pegue en Management Studio, por ejemplo):

-- Ejecute con un usuario que tenga permisos y/o hable con el DBA para seguir las mejores prácticas de su entornoUSE masterGOCREATE LOGIN PowerOmni WITH PASSWORD = 'SomeVeryStrongPassword';GOCREATE DATABASE PowerOmni; -- Crea una base de datos a la que se conectará PowerOmniGOUSE PowerOmni --> Cambia el contexto a la base de datos PowerOmniGOCREATE USER PowerOmni FROM LOGIN PowerOmni; --> crea el usuario PowerOmni (mapeado al login PowerOmni)GRANT EXECUTE, VIEW DEFINITION TO PowerOmni; --> permisos mínimos requeridosGO

El script anterior crea todo lo que Power Omni necesita para una prueba mínima de integración. Usted puede ajustar los nombres según los estándares de su empresa. El único requisito son los permisos listados arriba.

Finalmente, asegúrese de que su instancia de SQL Server sea accesible para la API que desplegará. Identifique el nombre de host o el puerto que la API utilizará para acceder a su instancia. Es posible que deba involucrar a su equipo de redes para ajustar reglas de firewall, NAT, VPN, etc.

Si realiza el despliegue en su propia VM o contenedor, SQL Server debe ser accesible para ese host. Si utiliza un servicio en la nube como Azure App Service, su instancia debe permitir el acceso desde el rango de IP correspondiente.

Desplegar la API de integración

Power Omni no se conecta directamente a su instancia SQL. Requiere un servicio intermediario, una API creada por Power Tuning, que identifica los procedures y los transforma a un formato que Power Omni pueda utilizar.

Usted puede desplegar esta API de varias maneras. En el repositorio de GitHub hay ejemplos listos que usan Docker Compose, los cuales puede utilizar en su propia infraestructura (VM o contenedor).

La documentación ofrece guías como:

• Despliegue en Azure App Service (con pocos clics)
• Uso de Docker con Traefik (más avanzado, infraestructura autoalojada)

Usted puede adaptar los ejemplos para usar nginx, Kubernetes, etc.

Este servicio genera logs en la salida estándar, que puede utilizar para depurar errores de conexión.

Después del despliegue, usted tendrá:

• La URL de su API (ejemplo: https://sqlpoweromni.example.com)
• Una o más API Keys

Conectar Power Omni

En este punto, usted ya logró desplegar la API de integración y ya tiene las API KEYS necesarias para acceder al servicio. Ahora es el momento de probar la conexión con su Power Omni. Supongamos que la URL que usted tiene es https://poweromni.exemplo.com y que una de las api keys es Abc123.

Primero, cree un procedure en la base de datos que configuró, por ejemplo:

CREATE PROCEDURE spOmniGetDate --> Creates a procedure to test the integration!ASSELECT DataAtual = GETDATE()

Hagamos que PowerOmni invoque este procedure para obtener la fecha actual de la base de datos.

Confirme que la integración puede listar el procedure, accediendo en su navegador a:

https://poweromni.exemplo.com/openapi?apikey=Abc123

Si configuró correctamente su SQL y creó el procedure, el navegador debería mostrar un JSON y en algún lugar verá el nombre del procedure (use CTRL + F para buscar por el nombre). Si no devolvió un JSON o no devolvió el procedure, revise el log del servicio en busca de errores.

Una vez que confirme que el JSON funciona, vamos a crear un conector de tipo OpenAPI en PowerOmni.

Vaya a: Configuración -> Artefactos -> Conectores. Cree un conector de tipo OpenAPI y complete los campos de la siguiente manera:

Una vez que haya completado todo y el esquema se haya cargado correctamente, guarde el conector. En este punto, su Power Omni ya puede identificar los procedures disponibles.

Ahora, solo falta asociar este conector a un Agente:

• Vaya a Artefactos -> Agentes
• Elija el agente deseado (o cree uno nuevo)
• En las instrucciones, asegúrese de colocar algo como: "Use las herramientas para responder al usuario"
• En relaciones, haga clic en "Conectores" y elija el conector que creó.
• Confirme que usted tiene permiso sobre el agente

Ahora, probemos si el agente puede identificar la lista de procedures. Abra una nueva conversación y pregunte: "¿Qué herramientas están disponibles?". Debería listar el nombre de los procedures (o algo similar).

Luego, pídale que ejecute el procedure, por ejemplo: "Dame la fecha de la base de datos". En ese momento, debería disparar la invocación del procedure de fecha, a través del conector SQL que usted configuró.

¡Listo! Su Power Omni está conectado exitosamente con su SQL Server y usted puede comenzar a probar procedures más avanzados, que reciban parámetros y obtengan datos de otras bases de datos.

Crear y documentar los procedures

Ahora, su Power Omni ya está configurado y puede llegar a su instancia. Los siguientes pasos son crear más procedures para que su Power Omni realmente pueda hacer algo útil con sus datos.

Como habrá notado, usted debe crear sus procedures con el prefijo spOmni. El nombre de su procedure puede contener solo letras mayúsculas o minúsculas y guion bajo. Estas reglas pueden flexibilizarse en versiones futuras.

A continuación se muestra un ejemplo de cómo crear un procedure que accede a otra base de datos y trae información de los pedidos de un cliente:

CREATE PROCEDURE spOmniListOrders (	@customer varchar(100)		,@StartDate datetime = NULL	,@EndDate datetime = NULL)AS /*omnidescription: Lista los pedidos de un cliente y de un mes específicoparams:  customer: El nombre del cliente  StartDate: "La fecha de inicio del pedido, en el formato YYYYMMDD HH:mm:ss. Si no se informa, recupera las últimas 24 h"  EndDate: "La fecha de fin del pedido, en el formato YYYYMMDD HH:mm:ss. Si no se informa, usa la fecha actual"*/IF @StartDate IS NULL 	SET @StartDate = DATEADD(HH,-24,GETDATE())IF @EndDate IS NULL 	SET @EndDate = GETDATE()SELECT	 OrderId	,TotalValue	,DeliveryDateFROM	Sales.dbo.Orders P	JOIN	Sales.dbo.Customers C		ON C.id = P.customer_idWHERE	C.name = @customer

El procedure anterior presenta algunos elementos nuevos que no se habían mostrado hasta ahora:

• Ahora hay una lista de parámetros. El modelo de IA que usted eligió en Power Omni podrá enviar el valor del parámetro según el contexto de la conversación y las instrucciones del agente. Y el conector SQL es responsable de construir el código SQL seguro que será invocado, pasando los parámetros con el tipo de dato apropiado
• Se agregó un comentario justo al inicio del cuerpo del procedure. Este comentario es utilizado por el conector SQL para generar la documentación que Power Omni necesita. Esta documentación ayuda a su agente a tener más información sobre el procedure y cómo debe usarlo. Este comentario es código YAML (no use tabulaciones para la indentación).

Si intenta invocar este procedure en su agente, no podrá, por 2 motivos:

1. Debe actualizar el esquema yendo a Configuración -> Artefactos -> Conectores -> Elija el conector, haga clic en el ícono de editar y, al final de la página, haga clic en 'Obtener especificación'.
2. Debe otorgar permisos al Login. En este caso, ahora necesitará acceder a la base de datos Sales, a las tablas Orders y Customers. Usted debe otorgar los permisos (o solicitarlos al equipo responsable de la base de datos)

Ahora que actualizó los metadatos y los permisos, solo vaya al agente. En este caso, si pregunto "Dame los pedidos del cliente ContosoCorp", invocará pasando estos filtros. Para más detalles sobre el uso de Procedures, incluidos consejos y ejemplos, consulte la guia-de-procedures.md