Solução de problemas do SQL Server

Soluções para problemas comuns de conectividade, autenticação e configuração de entidade do SQL Server no construtor de API de Dados.

Perguntas comuns

O que é o suporte do SQL Server no DAB?

O Construtor de API de Dados dá suporte ao Microsoft SQL Server e ao SQL do Azure como back-ends de banco de dados relacionais. O DAB se conecta usando o driver Microsoft.Data.SqlClient e converte solicitações REST e GraphQL em consultas T-SQL. Há suporte para instâncias locais do SQL Server e do Banco de Dados SQL do Azure.

Qual formato de cadeia de conexão o SQL Server usa?

O DAB usa cadeias de conexão no estilo ADO.NET para SQL Server. Uma cadeia de caracteres típica se parece com Server=localhost,1433;Database=mydb;User Id=sa;Password=yourpassword;TrustServerCertificate=True;. Defina a cadeia de conexão no campo data-source.connection-string de dab-config.json ou passe-a por meio da opção --connection-string em dab init.

Quais modos de autenticação têm suporte?

O DAB dá suporte à autenticação SQL (nome de usuário e senha), Autenticação Integrada do Windows e autenticação do Microsoft Entra (antigo Azure Active Directory) para SQL do Azure. Para usar a autenticação do Entra, defina Authentication=Active Directory Default ou Active Directory Managed Identity na cadeia de conexão e verifique se a identidade gerenciada ou a entidade de serviço recebeu acesso ao banco de dados.

Problemas comuns

Não é possível se conectar ao contêiner do SQL Server

Sintoma: O DAB falha ao iniciar com um erro de conexão, como A network-related or instance-specific error occurred.

Causa: A porta de contêiner do SQL Server não está mapeada corretamente, o nome do host está errado ou o contêiner ainda não está pronto para aceitar conexões.

Resolução: Verifique se o contêiner está em execução com docker ps. Confirme o mapeamento de porta (padrão 1433) e use localhost,1433 na cadeia de conexão. Adicione TrustServerCertificate=True se estiver usando um certificado autoassinado. Se o contêiner tiver começado, aguarde alguns segundos para que o SQL Server seja inicializado antes de iniciar o DAB.

Falha no logon do usuário

Sintoma: Os logs do DAB mostram Login failed for user 'sa' ou um erro de autenticação semelhante.

Causa: O nome de usuário, senha ou modo de autenticação na cadeia de conexão não corresponde à configuração do SQL Server. O SQL Server também pode estar em execução no modo somente autenticação do Windows.

Resolução: Confirme se as credenciais correspondem às definidas quando o contêiner ou o servidor foi criado. Se estiver usando um contêiner, verifique a variável de SA_PASSWORD ambiente. Para habilitar a autenticação do SQL em uma instância existente, defina o modo de autenticação do servidor para o MODO de Autenticação do SQL Server e do Windows no SQL Server Management Studio em Segurança de Propriedades > do Servidor.

Erro de entidade não encontrada

Sintoma: Solicitações REST ou GraphQL retornam um 404 erro de esquema ou indicando que a tabela de origem da entidade não existe.

Causa: O nome da tabela ou o prefixo de esquema no campo da source entidade não corresponde ao objeto de banco de dados real. Os nomes de tabela do SQL Server não diferenciam maiúsculas de minúsculas por padrão, mas o prefixo de esquema (por exemplo, dbo) deve estar presente se o esquema padrão não for usado.

Resolução: Verifique o source valor em dab-config.json. Use um nome totalmente qualificado, como dbo.Products. Execute SELECT * FROM INFORMATION_SCHEMA.TABLES no banco de dados de destino para confirmar o nome da tabela e o esquema.

Erro de firewall ou rede ao se conectar ao SQL do Azure

Sintoma: Conexões com o Banco de Dados SQL do Azure expiram ou retornam Cannot open server ... requested by the login.

Causa: O endereço IP do cliente não é permitido pelas regras de firewall do SQL Server do Azure ou a configuração de acesso ao serviço do Azure está desabilitada.

Resolução: No portal do Azure, navegue até o recurso do SQL Server e selecione Rede. Adicione o endereço IP do cliente à lista de permissões de firewall ou habilite permitir que os serviços e recursos do Azure acessem esse servidor se o DAB estiver em execução no Azure. Para autenticação de identidade gerenciada, verifique se a identidade foi adicionada como um usuário de banco de dados com CREATE USER [identity-name] FROM EXTERNAL PROVIDER.

As colunas JSON não são detectadas automaticamente

Sintoma: Uma coluna com um tipo JSON ou NVARCHAR(MAX) que armazena dados JSON não é exposta como um objeto estruturado no esquema de API.

Causa: O Construtor de API de Dados ainda não detecta e mapeia automaticamente colunas JSON no SQL do Azure. Essa é uma limitação conhecida rastreada no problema do GitHub nº 444.

Resolução: Não há nenhuma solução alternativa no momento. A coluna será exposta como um valor de texto sem formatação. Siga o problema do GitHub para atualizações sobre quando o suporte de coluna JSON nativo é adicionado.