Voltar para o site

SQL Server

Esta página detalha como funciona e como instalar a integração do Power Omni com o SQL Server

O Power Omni consegue se conectar com seu banco de dados através de Stored Procedures que você ou o seu time pode definir, permitindo que você tenha uma IA que consiga extrair ou inserir dados direto no seu banco de dados, através de uma lógica controlada e que une o melhor dos dois mundos: a inteligência artificial, decidindo o que executar e quando executar, e a segurança, onde você mantém o controle sobre o que ela vai ler ou modificar.

Para que isso funcione, você precisa subir uma API HTTP que fica entre o Power Omni e a sua instância SQL Server. Esta API é um serviço exclusivo fornecido gratuitamente aos clientes do Power Omni. Esta documentação vai te guiar as diferentes maneiras como você pode configurar esta API, seja com o seu SQL Server on-premises ou em nuvem.

Fazer o Power Omni conversar com o seu SQL Server, envolve basicamente as seguintes etapas:

  1. Criar o acesso na sua instância SQL Server

  2. Deploy da API da integração

  3. Conectar o Power Omni com a API

  4. Criar e documentar as procedures

O diagrama abaixo fornece um resumo do fluxo de dados de como esta integração funciona:

Se você quiser entender toda a arquitetura dessa integração, veja a página Arquitetura, onde há mais detalhes técnicos.

Criar o Acesso no SQL Server

O primeiro passo é você preparar a sua instância SQL Server. Basicamente, você vai precisar criar um banco de dados (ou pode usar algum já existente) e um Login e Senha.

Recomendamos criar um banco de dados novo, para que você separe e tenha mais controle onde as procedures que o Power Omni vai invocar estão.

Aqui está um exemplo de um script SQL que cria um banco e usuário chamados PowerOmni (copie e cole no Management Studio, por exemplo):

-- Execute com um usuário que tenha permissões e/ou converse com o DBA para seguir as melhores práticas para o seu ambiente
USE master
GO
CREATE LOGIN PowerOmni WITH PASSWORD = 'AlgumaSenhaMuitoForte';
GO
CREATE DATABASE PowerOmni; -- Cria um banco onde o PowerOmni vai se conectar
GO
USE PowerOmni --> Muda o contexto pro banco PowerOmni
GO
CREATE USER PowerOmni FROM LOGIN PowerOmni; --> cria o user PowerOmni (mapeado para o login PowerOMni)
GRANT EXECUTE, VIEW DEFINITION TO PowerOmni; --> permissoes minimas necessarias
GO

O script acima cria tudo o que o PowerOmni vai precisar para que você faça um teste mínimo de integração. Lembre-se que você pode ajustar ou mudar os nomes, conforme preferência ou padrões da sua empresa. A única exigência são as permissões acima.

A APÍ da integração suporta apenas conexão SQL Authentication. Futuras versões poderão adicionar outras formas.

O último passo é garantir que sua instância SQL Server estará acessível para a API que você irá subir. Identifique o nome ou a porta pelos quais a API irá acessar a sua instância. Pode ser que seja necessário envolver o seu time de rede para ajustar regras de firewall, NAT, VPN, etc.

Se você for subir em uma VM ou container na sua própria infraestrutura, o SQL Server deve estar acessível para esse host. Se você for usar algum serviço em cloud, como o App Service do Azure, a sua instância precisa ser liberada para o range de IPs. Veja o próximo passo baixo para determinar o que se encaixa melhor para o seu cenário;

Deploy da API da Integração

O PowerOmni não se conecta diretamente com a sua instância SQL. Ele precisa de um serviço intermediário, que é uma API criada pela Power Tuning que faz todo o trabalho de identificar as procedures e transformar em um formato que o PowerOmni consiga usar.

Você pode subir esta API de várias formas. Aqui neste repositório GitHub, você tem alguns exemplos prontos com docker compose, que você pode usar para subir a API na sua própria infraestrutura (como em uma VM ou contêiner, por exemplo).

Nesta documentação, os seguintes guias podem te ajudar:

Você pode adaptar os exemplos, se quiser usar outros serviços, como nginx, kubernetes, etc.

Esse serviço gera logs na saída padrão, que você pode usar para debugar possíveis erros de conexão com o banco ou outros que possam ocorrer.

Quando você fizer o deploy da API, você terá:

  • A URL da sua API (exemplo: https://sqlpoweromni.exemplo.com)

  • Uma ou mais API KEYS para acessr a API

SEGURANÇA DA API

Quando você configura a API, você está fazendo o deploy dela na porta https 443, e protegida através de APIKEYS que foram configuradas por você ou geradas automaticamente.

É de suma importância que você garanta que nenhuma porta além da 443 ou 80 estejam liberadas.

Também, faça um controle rígido sobre as API KEYS geradas, guardando em cofre de senhas e evite compartilhar em vídeos, prints, etc. Você deve tratá-las como um dado sensível.

Caso você precise aplicar proteções adicionais, procure o suporte do Power Omni para dúvidas

Conectar o Power Omni

Neste ponto, você já conseguiu subir a API da integração, e já possui as API KEYS necessárias para acessar o serviço. Agora chegou a hora de testar a conexão com o seu Power Omni. Vamos assumir que a URL que você possui é https://poweromni.exemplo.com e que uma das apis keys é Abc123.

Primeiro, crie uma procedure no banco que você configurou, exemplo:

CREATE PROCEDURE spOmniGetDate --> Cria uma procedure para testar a integracao!
AS
SELECT DataAtual = GETDATE()

Vamos fazer o PowerOmni invocar essa procedure para obter a data atual do banco de dados.

Confirme que a integração consegue listar a procedure, acessando no seu navegador:

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

Se você configurou o seu SQL corretamente e criou a procedure, o browser deverá exibir um JSON e em algum lugar você verá o nome da procedure (utilize o CTRL + F para buscar pelo nome). Se ele não retornou um JSON ou não retornou a procedure, verifique o log do serviço por erros.

Uma vez que você confirmou que o JSON está funcionando, vamos criar um conector do Tipo OpenAPI no PowerOmni.

Esta integração usa um recurso nativo do Power Omni: Conector de OpenAPI.

Leia mais na doc do conector de OpenAPI se quiser aprender mais sobre ele e as configurações

Vá em: Configurações -> Artefatos -> Conectores. Crie um conector do tipo OpenAPI, e preencha os campos conforme a seguir:

Campo
Como Preencher

Projeto

Escolha em qual projeto criar

Nome

Dê um nome ao conector. Só aceita letras maiúsculas ou minúsculas

Descrição

Breve descrição. Exemplo: Execute procedures em um banco de dados SQL

Tipo de Autenticação

Escolha API Key, e em configuração da conexão, escolha "Criar Nova Conexão"

Nome da Conexão

Em "nome da conexão", escolha um nome de sua preferência. Exemplo: SqlConector1 Depois clique em "Adicionar Chaves de API"

Nome Chave

Digite "apikey", sem as aspas

Valor Chave

Cole o valor de umas das chaves de api key que você tem. No nosso exemplo, seria o Abc123

Em Especificação OpenAPI

Escolha a opção "Automático"

URL Base

Coloque apenas o domínio da API https://poweromni.exemplo.com

Endpoint da Especificação

Coloque o seguinte valor, trocando a apikey: /openapi?reload=1&apikey=Abc123 Clique em "Buscar especificação" e o PowerOmni vai tentar ler aquele mesmo JSON que você leu acima Se não houve erros, ele vai retornar o json e você pode conferir clicando no botão "Ver Schema"

Uma vez que você preencheu tudo e o Schema foi carregado com sucesso, salve o conector. Neste ponto, o seu Power Omni já consegue identificar as procedures disponíveis.

Agora, basta associar esse conector com um Agente:

  • Vá em Artefatos -> Agentes

  • Escolha o agente desejado (ou crie um novo)

  • Nas instruções, certifique de colocar algo como: "Utilize as ferramentas para responder ao usuário"

  • Em relacionamentos, clique em "Conectores" e escolha o conector que você criou.

  • Confirme que você tem permissão no agente

Agora, vamos testar se o agente consegue identificar a lista de procedures. Abra uma nova conversa e pergunte: "Quais ferramentas estão disponíveis?". Ele deverá listar o nome das procedures (ou algo semelhante).

Então, peça para ele executar a procedure, por exemplo: "Me de a data do banco". Neste momento, ele deve disparar a invocação da procedure de data, através do conector de SQL que você configurou.

Pronto! Seu Power Omni está conectado com sucesso com o seu SQL Server, e você pode começar a testar procedures mais avançadas, que recebem parâmetros, e obtem dados de outros bancos.

Se houve qualquer erro na execução da procedure, seja por falta de permissão, seja por lógica, a integração vai capturar o erro e logar na saída padrão. E vai enviar uma resposta pro omni, genérica, indicando que houve erro na execução. Então, o Power Omni vai gerar a resposta de algo relacionado ao erro.

Se o Power Omni gerar um alerta de erro (com um id), significa que houve outro erro no processamento e deve ser investigado.

Você pode contatar o time de suporte do Power Omni para te ajudar.

Criar e Documentar as Procedures

Agora, seu Power Omni já está configurado e consegue chegar na sua instância. Os próximos passos são criar mais procedures para que seu Power Omni consiga realmente fazer algo de útil com os seus dados.

Como você deve ter notado, você deve criar as suas procedures com o prefixo spOmni. O nome da sua procedure pode conter apenas letras maiúsculas ou minúsculas e underline. Essas regras podem ser flexibilizadas em versões futuras.

Aqui está um exemplo de como você criar uma procedure que acessa um outro banco e traz informações de pedidos de um cliente:

CREATE PROCEDURE spOmniListarPedidos (
	@cliente varchar(100)	
	,@StartDate datetime = NULL
	,@EndDate datetime = NULL
)
AS 
/*omni
description: Lista os pedidos de um dado cliente e um mes específico
params:
  cliente: O nome do cliente
  StartDate: "A data de inicio do pedido, no formato YYYYMMDD HH:mm:ss. Se não informado obtem as ultimas 24h"
  EndDate: "A data de fim do pedido, no formato YYYYMMDD HH:mm:ss. Se não informado, usa a data atual"
*/

IF @StartDate IS NULL 
	SET @StartDate = DATEADD(HH,-24,GETDATE())

IF @EndDate IS NULL 
	SET @EndDate = GETDATE()

SELECT
	 IdPedido
	,ValorTotal
	,DataEntrega
FROM
	Vendas.dbo.Pedidos P
	JOIN
	Vendas.dbo.Clientes C
		ON C.id = P.id_cliente
WHERE
	C.nome = @cliente

A procedure acima apresenta alguns elementos novos que não foram mostrados até agora:

  • Agora há uma lista de parâmetros. O modelo de IA que você escolheu no Power Omni vai conseguir enviar o valor dos parâmetros conforme o contexto da conversa e as instruções do agente. E o conector de SQL é o responsável por montar o código SQL seguro que vai ser invocado, passando os parâmetros com o tipo de dados adequado

  • Um comentário foi adicionado, logo início do corpo da procedure. Esse comentário é usado pelo conector de SQL para gerar a documentação que o Power Omni precisa. Essa documentação ajuda o seu agente a ter mais informações sobre a procedure, e como deve usá-la. Esse comentário é um código YAML (não use tabs para identação).

Se você tentar invocar essa procedure no seu agente, ele não vai conseguir, por 2 motivos:

  1. Você precisa atualizar o schema indo em Configurações -> Artefatos -> Conectores -> Escolher o conector, clicar no ícone de edição, e no final da página, clicar em 'Buscar especificação'.

  2. Você precisa conceder as permissões para o Login. No caso, agora ele vai precisar acessar o banco Vendas, tabelas Pedidos e Clientes. Você precisa conceder as permissões (ou solicitar ao time responsável pelo banco)

Agora que você atualizou o metadado e permissões, basta ir ao agente. Neste caso, se eu perguntar "Me de os pedidos do cliente ContosoCorp", ele vai invocar passando esses filtros. Para mais detalhes sobre o uso de Procedures, incluindo dicas e exemplos, veja oGuia de Procedures

AnteriorSuportePróximoDeploys da API

Atualizado