conectores SQL do Azure e Microsoft SQL Server Microsoft Graph

  • Artigo

O conector microsoft SQL Server ou SQL do Azure Microsoft Graph permite que sua organização descubra e indexe dados de um banco de dados SQL Server local ou um banco de dados hospedado em sua instância SQL do Azure na nuvem. Os índices do conector especificaram o conteúdo no Microsoft Search. Para manter o índice atualizado com dados de origem, ele dá suporte a rastreamentos periódicos completos e incrementais. Com esses conectores SQL, você também pode restringir o acesso aos resultados da pesquisa para determinados usuários.

Observação

Leia o artigo Configurar seu conector do Microsoft Graph para entender as instruções gerais de instalação dos conectores do Graph.

Este artigo é para qualquer pessoa que configure, execute e monitore um SQL do Azure ou um conector do Microsoft SQL Server. Ele complementa o processo de instalação geral e mostra instruções que se aplicam apenas aos conectores do SQL do Azure e do Microsoft SQL Server. Este artigo também inclui informações sobre limitações para ambos os conectores.

Antes de começar

Instalar o agente conector do Microsoft Graph (necessário apenas para o conector do Microsoft SQL Server local)

Para acessar seus dados locais de terceiros, você deve instalar e configurar o agente do conector. Consulte Instalar o agente conector do Microsoft Graph para saber mais.

Observação

Se você usar autenticação do Windows ao configurar o conector do Microsoft SQL Server, o usuário com o qual você está tentando entrar precisa ter direitos interativos de logon no computador em que o agente conector está instalado. Consulte a documentação sobre o gerenciamento de política de logon para marcar direitos de logon.

Etapa 1: Adicionar um conector no Centro de administração do Microsoft 365

Siga as instruções de configuração geral.

Etapa 2: nomear a conexão

Siga as instruções de configuração geral.

Etapa 3: configurar as configurações de conexão

Registrar um aplicativo (somente para SQL do Azure conector)

Para SQL do Azure conector, você deve registrar um aplicativo no Microsoft Entra ID para permitir que o aplicativo Microsoft Search acesse dados para indexação. Para saber mais sobre como registrar um aplicativo, consulte a documentação do Microsoft Graph sobre como registrar um aplicativo.

Depois de concluir o registro do aplicativo e tomar nota do nome do aplicativo, ID do aplicativo (cliente) e ID do locatário, você precisa gerar um novo segredo do cliente. O segredo do cliente só será exibido uma vez. Lembre-se de observar & armazenar o segredo do cliente com segurança. Use a ID do cliente e o segredo do cliente ao configurar uma nova conexão no Microsoft Search.

Para adicionar o aplicativo registrado ao banco de dados SQL do Azure, você precisa:

  • Faça logon no SQL do Azure DB
  • Abrir uma nova janela de consulta
  • Criar um novo usuário executando o comando 'CREATE USER [nome do aplicativo] DO PROVEDOR EXTERNO'
  • Adicione o usuário à função executando o comando 'exec sp_addrolemember 'db_datareader', [nome do aplicativo]' ou 'ALTER ROLE db_datareader ADD MEMBER [nome do aplicativo]'

Observação

Para revogar o acesso a qualquer aplicativo registrado em Microsoft Entra ID, consulte a documentação do Azure sobre como remover um aplicativo registrado.

Configurações de conexão

Para conectar o conector do Microsoft SQL Server a uma fonte de dados, você deve configurar o servidor de banco de dados desejado e o agente local. Em seguida, você pode se conectar ao banco de dados com o método de autenticação necessário.

Observação

  • Seu banco de dados deve executar SQL Server versão 2008 ou posterior para que o conector do Microsoft SQL Server possa se conectar.
  • O conector SQL do Azure só permite a ingestão de uma instância de SQL do Azure no mesmo locatário do Microsoft 365. Não há suporte para o fluxo de dados entre locatários.

Para o conector SQL do Azure, você só precisa especificar o nome do servidor ou o endereço IP ao qual deseja se conectar. SQL do Azure conector só Microsoft Entra dá suporte à autenticação do OIDC (ID OpenID Connect) para se conectar ao banco de dados.

Para obter mais segurança, você pode configurar regras de firewall IP para o servidor ou banco de dados SQL do Azure. Para saber mais sobre como configurar regras de firewall ip, consulte documentação sobre regras de firewall IP. Adicione os seguintes intervalos de IP do cliente nas configurações de firewall.

Região M365 Enterprise Governo M365
NAM 52.250.92.252/30, 52.224.250.216/30 52.245.230.216/30, 20.141.117.64/30
EUR 20.54.41.208/30, 51.105.159.88/30 NA
APC 52.139.188.212/30, 20.43.146.44/30 NA

Para pesquisar o conteúdo do banco de dados, você deve especificar consultas SQL ao configurar o conector. Essas consultas SQL precisam nomear todas as colunas de banco de dados que você deseja indexar (ou seja, propriedades de origem), incluindo todas as junções SQL que precisam ser executadas para obter todas as colunas. Para restringir o acesso aos resultados da pesquisa, você deve especificar Controle de Acesso Listas (ACLs) em consultas SQL ao configurar o conector.

Etapa 3a: Rastreamento completo (Obrigatório)

Nesta etapa, você configura a consulta SQL que executa um rastreamento completo do banco de dados. O rastreamento completo seleciona todas as colunas ou propriedades em que você deseja selecionar as opções Consulta, Pesquisa ou Recuperação. Você também pode especificar colunas ACL para restringir o acesso dos resultados da pesquisa a usuários ou grupos específicos.

Dica

Para obter todas as colunas necessárias, você pode ingressar em várias tabelas.

Script mostrando a OrderTable e AclTable com propriedades de exemplo.

Selecione colunas de dados (Obrigatório) e ACL (Opcional)

O exemplo demonstra uma seleção de cinco colunas de dados que contêm os dados da pesquisa: OrderId, OrderTitle, OrderDesc, CreatedDateTime e IsDeleted. Para definir permissões de exibição para cada linha de dados, você pode opcionalmente selecionar estas colunas ACL: AllowedUsers, AllowedGroups, DeniedUsers e DeniedGroups. Todas essas colunas de dados também têm as opções para Consultar, Pesquisar ou Recuperar.

Selecione colunas de dados conforme mostrado nesta consulta de exemplo: SELECT OrderId, OrderTitle, OrderDesc, AllowedUsers, AllowedGroups, DeniedUsers, DeniedGroups, CreatedDateTime, IsDeleted

Observe que os conectores SQL não permitem nomes de coluna com caracteres não alfanuméricos na cláusula SELECT. Remova todos os caracteres não alfanuméricos de nomes de coluna usando um alias. Exemplo – SELECT column_nameas columnName

Para gerenciar o acesso aos resultados da pesquisa, você pode especificar uma ou mais colunas ACL na consulta. O conector SQL permite controlar o acesso por nível de registro. Você pode optar por ter o mesmo controle de acesso para todos os registros em uma tabela. Se as informações de ACL forem armazenadas em uma tabela separada, talvez seja necessário fazer uma junção com essas tabelas em sua consulta.

O uso de cada uma das colunas ACL na consulta acima é descrito abaixo. A lista a seguir explica os quatro mecanismos de controle de acesso.

  • AllowedUsers: esta coluna especifica a lista de IDs de usuário que podem acessar os resultados da pesquisa. No exemplo a seguir, lista de usuários: john@contoso.com, keith@contoso.come lisa@contoso.com só teria acesso a um registro com OrderId = 12.
  • AllowedGroups: esta coluna especifica o grupo de usuários que poderão acessar os resultados da pesquisa. No exemplo a seguir, o grupo sales-team@contoso.com só teria acesso ao registro com OrderId = 12.
  • DeniedUsers: esta coluna especifica a lista de usuários que não têm acesso aos resultados da pesquisa. No exemplo a seguir, os usuários john@contoso.com e keith@contoso.com não têm acesso ao registro com OrderId = 13, enquanto todos os outros têm acesso a esse registro.
  • Grupos negados: esta coluna especifica o grupo de usuários que não têm acesso aos resultados da pesquisa. No exemplo a seguir, os grupos engg-team@contoso.com e pm-team@contoso.com não têm acesso ao registro com OrderId = 15, enquanto todos os outros têm acesso a esse registro.

Dados de exemplo mostrando a OrderTable e AclTable com propriedades de exemplo.

Tipos de dados com suporte

A tabela abaixo resume os tipos de dados SQL com suporte nos conectores SQL e SQL do Azure MS. A tabela também resume o tipo de dados de indexação para o tipo de dados SQL com suporte. Para saber mais sobre os conectores do Microsoft Graph com suporte para tipos de dados para indexação, consulte documentação sobre tipos de recursos de propriedade.

Categoria Tipo de dados de origem Tipo de dados de indexação
Data e hora data
datetime
datetime2
Smalldatetime		 datetime
Numérico exato Bigint
int
Smallint
Tinyint		 int64
Numérico exato Pouco booliano
Numérico aproximado flutuação
Real		 double
Conjunto de caracteres Char
Varchar
texto		 string
Cadeias de caracteres unicode Nchar
Nvarchar
Ntext		 cadeia de caracteres
Coleção String Char
Varchar
texto		 Stringcollection*
Outros tipos de dados Uniqueidentifier cadeia de caracteres

*Para indexar uma coluna como StringCollection, você precisa lançar uma cadeia de caracteres para o tipo de coleção de cadeias de caracteres. Isso pode ser feito clicando no link 'Editar tipos de dados' em Configurações de rastreamento completo e selecionando as colunas apropriadas como StringCollection, além de especificar um delimitador para dividir a cadeia de caracteres.

Para qualquer outro tipo de dados atualmente não com suporte direto, a coluna precisa ser explicitamente lançada para um tipo de dados com suporte.

Marca d'água (Obrigatório)

Para evitar sobrecarregar o banco de dados, o conector lota e retoma consultas de rastreamento completo com uma coluna de marca d'água de rastreamento completo. Usando o valor da coluna de marca d'água, cada lote subsequente é buscado e a consulta é retomada do último ponto de verificação. Essencialmente, esses mecanismos controlam a atualização de dados para rastreamentos completos.

Criar snippets de consulta para marcas d'água, conforme mostrado nestes exemplos:

  • WHERE (CreatedDateTime > @watermark). Cite o nome da coluna de marca d'água com o palavra-chave @watermarkreservado . Se a ordem de classificação da coluna de marca d'água estiver crescente, use >; caso contrário, use <.
  • ORDER BY CreatedDateTime ASC. Classifique a coluna de marca d'água em ordem crescente ou decrescente.

Na configuração mostrada na imagem a seguir, CreatedDateTime está a coluna de marca d'água selecionada. Para buscar o primeiro lote de linhas, especifique o tipo de dados da coluna de marca d'água. Nesse caso, o tipo de dados é DateTime.

Configuração de coluna de marca d'água.

A primeira consulta busca o primeiro número N de linhas usando: "CreatedDateTime > 1 de janeiro de 1753 00:00:00" (valor mínimo do tipo de dados DateTime). Depois que o primeiro lote for buscado, o valor mais alto do CreatedDateTime retornado no lote será salvo como o ponto de verificação se as linhas forem classificadas em ordem crescente. Um exemplo é 1º de março de 2019 03:00:00. Em seguida, o próximo lote de linhas N é buscado usando "CreatedDateTime > 1, 2019 03:00:00" na consulta.

Ignorar linhas excluídas suavemente (opcional)

Para excluir as linhas excluídas em seu banco de dados de serem indexadas, especifique o nome e o valor da coluna de exclusão suave que indica que a linha foi excluída.

Configurações de exclusão suave:

Rastreamento completo: gerenciar permissões de pesquisa

Selecione Gerenciar permissões para escolher as várias colunas ACL (controle de acesso) que especificam o mecanismo de controle de acesso. Selecione o nome da coluna especificado na consulta SQL de rastreamento completo.

Espera-se que cada uma das colunas ACL seja uma coluna com vários valores. Esses vários valores de ID podem ser separados por separadores como ponto e vírgula (;), vírgula (,) e assim por diante. Você precisa especificar esse separador no campo separador de valor .

Há suporte para os seguintes tipos de ID para usar como ACLs:

  • Nome da entidade de usuário (UPN): Um UPN (nome de entidade de usuário) é o nome de um usuário do sistema em um formato de endereço de email. Um UPN (por exemplo: john.doe@domain.com) consiste no nome de usuário (nome de logon), separador (o símbolo @) e nome de domínio (sufixo UPN).
  • Microsoft Entra ID: em Microsoft Entra ID, cada usuário ou grupo tem uma ID de objeto que se parece com 'e0d3ad3d-0000-1111-2222-3c5f5c52ab9b'.
  • ID de segurança do Active Directory (AD): em uma configuração local do AD, cada usuário e grupo tem um identificador de segurança imutável e exclusivo que se parece com 'S-1-5-21-3878594291-2115959936-132693609-65242.'

Configurações de permissão de pesquisa para configurar listas de controle de acesso.

Etapa 3b: rastreamento incremental (opcional)

Nesta etapa opcional, forneça uma consulta SQL para executar um rastreamento incremental do banco de dados. Com essa consulta, o conector SQL determina quaisquer alterações nos dados desde o último rastreamento incremental. Como no rastreamento completo, selecione todas as colunas em que você deseja selecionar as opções Consulta, Pesquisa ou Recuperação. Especifique o mesmo conjunto de colunas ACL especificadas na consulta de rastreamento completo.

Os componentes na imagem a seguir se assemelham aos componentes de rastreamento completos com uma exceção. Nesse caso, "ModifiedDateTime" é a coluna de marca d'água selecionada. Examine as etapas completas de rastreamento para saber como escrever sua consulta de rastreamento incremental e veja a imagem a seguir como um exemplo.

Script de rastreamento incremental mostrando propriedades OrderTable, AclTable e exemplo que podem ser usadas.

Etapa 4: Atribuir rótulos de propriedade

Siga as instruções de configuração geral.

Etapa 5: Gerenciar esquema

Siga as instruções de configuração geral.

Etapa 6: Gerenciar permissões de pesquisa

Você pode optar por usar as ACLs especificadas na tela de rastreamento completo ou substituí-las para tornar seu conteúdo visível para todos.

Etapa 7: escolher configurações de atualização

Siga as instruções de configuração geral.

Etapa 8: Revisar conexão

Siga as instruções de configuração geral.

Solução de problemas

Veja a seguir um erro comum observado ao configurar o conector e seu possível motivo.

Etapa de configuração Mensagem de erro Possíveis motivos
Rastreamento completo Error from database server: A transport level error has occurred when receiving results from the server. Esse erro surge devido a problemas de rede. É recomendável marcar logs de rede usando o monitor de rede da Microsoft e entrar em contato com o suporte ao cliente da Microsoft.
Rastreamento completo Column column_name returned from full crawl SQL query contains non-alphanumeric character Caracteres não alfanuméricos (como sublinhados) não são permitidos em nomes de coluna na cláusula SELECT. Use aliases para renomear colunas e remover caracteres não alfanuméricos (Exemplo – SELECT column_name as columnName).

Limitações

Os conectores SQL têm essas limitações na versão prévia:

  • Conector do Microsoft SQL Server: o banco de dados local deve ser executado SQL Server versão 2008 ou posterior.
  • A assinatura do Microsoft 365 e a assinatura do Azure (hospedagem SQL do Azure banco de dados) devem estar no mesmo Microsoft Entra ID.
  • As ACLs só têm suporte usando um UPN (Nome de Entidade de Usuário), Microsoft Entra ID ou Segurança do Active Directory.
  • Não há suporte para indexação de conteúdo avançado dentro de colunas de banco de dados. Exemplos desse conteúdo são análises html, JSON, XML, blobs e documentos que existem como links dentro das colunas de banco de dados.