Conectores do Microsoft Graph e SQL do Azure SQL Server

O conector Microsoft SQL Server ou Microsoft Graph do SQL do Azure permite que a sua organização detete e indexe dados a partir de uma base de dados do SQL Server no local ou de uma base de dados alojada na sua instância do SQL do Azure na cloud. Os índices de conectores especificaram conteúdo no Microsoft Search. Para manter o índice atualizado com os dados de origem, suporta pesquisas periódicas completas e incrementais. Com estes conectores SQL, também pode restringir o acesso aos resultados da pesquisa para determinados utilizadores.

Este artigo destina-se a qualquer pessoa que configure, execute e monitorize um SQL do Azure ou um conector do Microsoft SQL Server. Complementa o processo de configuraçã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 do conector do Microsoft Graph (necessário apenas para o conector do Microsoft SQL Server no local)

Para aceder aos seus dados de terceiros no local, tem de instalar e configurar o agente do conector. Consulte Instalar o agente do conector do Microsoft Graph para saber mais.

Passo 1: adicionar um conector no centro de administração do Microsoft 365

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

Passo 2: atribuir um nome à ligação

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

Passo 3: Configurar as definições de ligação

Registar uma aplicação (apenas para o conector SQL do Azure)

Para o conector SQL do Azure, tem de registar uma aplicação no Microsoft Entra ID para permitir que a aplicação Microsoft Search aceda aos dados de indexação. Para saber mais sobre como registar uma aplicação, consulte a documentação do Microsoft Graph sobre como registar uma aplicação.

Depois de concluir o registo da aplicação e anotar o nome da aplicação, o ID da aplicação (cliente) e o ID do inquilino, tem de gerar um novo segredo do cliente. O segredo do cliente só será apresentado uma vez. Lembre-se de anotar & armazenar o segredo do cliente de forma segura. Utilize o ID de cliente e o segredo do cliente ao configurar uma nova ligação no Microsoft Search.

Para adicionar a aplicação registada à Base de Dados SQL do Azure, tem de:

• Iniciar sessão na BD SQL do Azure
• Abrir uma nova janela de consulta
• Crie um novo utilizador ao executar o comando "CREATE USER [nome da aplicação] FROM EXTERNAL PROVIDER"
• Adicione o utilizador à função ao executar o comando "exec sp_addrolemember "db_datareader", [nome da aplicação]" ou "ALTER ROLE db_datareader ADD MEMBER [nome da aplicação]"

Definições de ligação

Para ligar o conector do Microsoft SQL Server a uma origem de dados, tem de configurar o servidor de bases de dados que pretende pesquisar e o agente no local. Em seguida, pode ligar à base de dados com o método de autenticação necessário.

Para o conector SQL do Azure, só tem de especificar o nome do servidor ou endereço IP ao qual pretende ligar. O conector SQL do Azure só suporta a autenticação OIDC (Microsoft Entra ID OpenID Connect) para ligar à base de dados.

Para maior segurança, pode configurar regras de firewall de IP para o Azure SQL Server ou base de dados. Para saber mais sobre como configurar regras de firewall de IP, veja a documentação sobre as regras de firewall de IP. Adicione os seguintes intervalos de IP de cliente nas definições da firewall.

Para procurar o conteúdo da base de dados, tem de especificar consultas SQL quando configurar o conector. Estas consultas SQL têm de atribuir um nome a todas as colunas da base de dados que pretende indexar (ou seja, propriedades de origem), incluindo todas as associações SQL que precisam de ser executadas para obter todas as colunas. Para restringir o acesso aos resultados da pesquisa, tem de especificar Listas de Controlo de Acesso (ACLs) em consultas SQL quando configurar o conector.

Passo 3a: Pesquisa completa (Necessário)

Neste passo, vai configurar a consulta SQL que executa uma pesquisa completa da base de dados. A pesquisa completa seleciona todas as colunas ou propriedades onde pretende selecionar as opções Consulta, Pesquisa ou Obter. Também pode especificar colunas ACL para restringir o acesso dos resultados da pesquisa a utilizadores ou grupos específicos.

Selecionar colunas de dados (Obrigatório) e colunas 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 visualização para cada linha de dados, opcionalmente, pode selecionar estas colunas da ACL: AllowedUsers, AllowedGroups, DeniedUsers e DeniedGroups. Todas estas colunas de dados também têm as opções para Consulta, Pesquisa ou Obter.

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

Tenha em atenção que os conectores SQL não permitem nomes de colunas com carateres não alfanuméricos na cláusula SELECT. Remova quaisquer carateres não alfanuméricos dos nomes de colunas com um alias. Exemplo - SELECT column_name AS columnName

Para gerir o acesso aos resultados da pesquisa, pode especificar uma ou mais colunas da ACL na consulta. O conector SQL permite-lhe controlar o acesso ao nível por registo. Pode optar por ter o mesmo controlo de acesso para todos os registos numa tabela. Se as informações da ACL estiverem armazenadas numa tabela separada, poderá ter de fazer uma associação com essas tabelas na consulta.

A utilização de cada uma das colunas da ACL na consulta acima é descrita abaixo. A lista seguinte explica os quatro mecanismos de controlo de acesso.

• AllowedUsers: esta coluna especifica a lista de IDs de utilizador que podem aceder aos resultados da pesquisa. No exemplo seguinte, a lista de utilizadores: john@contoso.com, keith@contoso.come lisa@contoso.com só teria acesso a um registo com OrderId = 12.
• AllowedGroups: esta coluna especifica o grupo de utilizadores que poderão aceder aos resultados da pesquisa. No exemplo seguinte, o grupo sales-team@contoso.com só teria acesso ao registo com OrderId = 12.
• DeniedUsers: esta coluna especifica a lista de utilizadores que não têm acesso aos resultados da pesquisa. No exemplo seguinte, os utilizadores john@contoso.com e keith@contoso.com não têm acesso ao registo com OrderId = 13, enquanto todos os outros têm acesso a este registo.
• DeniedGroups: esta coluna especifica o grupo de utilizadores que não têm acesso aos resultados da pesquisa. No exemplo seguinte, agrupa engg-team@contoso.com e pm-team@contoso.com não tem acesso ao registo com OrderId = 15, enquanto todos os outros têm acesso a este registo.

Tipos de dados suportados

A tabela abaixo resume os tipos de dados SQL suportados nos conectores SQL do MS e SQL do Azure. A tabela também resume o tipo de dados de indexação para o tipo de dados SQL suportado. Para saber mais sobre os conectores do Microsoft Graph que suportam tipos de dados para indexação, veja a documentação sobre tipos de recursos de propriedade.

*Para indexar uma coluna como StringCollection, tem de converter uma cadeia no tipo de coleção de cadeias. Isto pode ser feito ao clicar na ligação "Editar tipos de dados" em Definições de pesquisa completa e selecionar as colunas adequadas como StringCollection juntamente com a especificação de um delimitador para dividir a cadeia.

Para qualquer outro tipo de dados atualmente não suportado diretamente, a coluna tem de ser explicitamente convertida num tipo de dados suportado.

Marca d'água (Obrigatório)

Para evitar sobrecarregar a base de dados, o conector cria lotes e retoma as consultas de pesquisa completa com uma coluna de marca d'água de pesquisa completa. Ao utilizar o valor da coluna de marca d'água, cada lote subsequente é obtido e a consulta é retomada a partir do último ponto de verificação. Essencialmente, estes mecanismos controlam a atualização de dados para pesquisas completas.

Crie fragmentos de consulta para marcas d'água, conforme mostrado nestes exemplos:

• WHERE (CreatedDateTime > @watermark). Cite o nome da coluna de marca d'água com a palavra-chave @watermarkreservada . Se a sequência de ordenação da coluna de marca d'água for ascendente, utilize >; caso contrário, utilize <.
• ORDER BY CreatedDateTime ASC. Ordene na coluna de marca d'água por ordem ascendente ou descendente.

Na configuração apresentada na imagem seguinte, CreatedDateTime encontra-se a coluna de marca d'água selecionada. Para obter o primeiro lote de linhas, especifique o tipo de dados da coluna de marca d'água. Neste caso, o tipo de dados é DateTime.

A primeira consulta obtém o primeiro N número de linhas com: "CreatedDateTime > 1 de janeiro de 1753 00:00:00" (valor mínimo do tipo de dados DateTime). Depois de o primeiro lote ser obtido, o valor mais alto devolvido CreatedDateTime no lote é guardado como ponto de verificação se as linhas estiverem ordenadas por ordem ascendente. Um exemplo é 1 de março de 2019 03:00:00. Em seguida, o próximo lote de N linhas é obtido com "CreatedDateTime > 1 de março de 2019 03:00:00" na consulta.

Ignorar linhas eliminadas de forma recuperável (Opcional)

Para excluir as linhas eliminadas de forma recuperável na base de dados de serem indexadas, especifique o nome e o valor da coluna de eliminação recuperável que indica que a linha foi eliminada.

Pesquisa completa: Gerir permissões de pesquisa

Selecione Gerir permissões para escolher as várias colunas de controlo de acesso (ACL) que especificam o mecanismo de controlo de acesso. Selecione o nome da coluna que especificou na consulta SQL de pesquisa completa.

Espera-se que cada uma das colunas da ACL seja uma coluna de valores múltiplos. Estes múltiplos valores de ID podem ser separados por separadores como ponto e vírgula (;), vírgula (,) e assim sucessivamente. Tem de especificar este separador no campo separador de valor .

Os seguintes tipos de ID são suportados para utilização como ACLs:

• Nome Principal de Utilizador (UPN): Um Nome Principal de Utilizador (UPN) é o nome de um utilizador do sistema num formato de endereço de e-mail. Um UPN (por exemplo: john.doe@domain.com) consiste no nome de utilizador (nome de início de sessão), separador (o símbolo @) e nome de domínio (sufixo UPN).
• Microsoft Entra ID: no Microsoft Entra ID, cada utilizador ou grupo tem um ID de objeto semelhante a "e0d3ad3d-0000-1111-2222-3c5f5c52ab9b".
• ID de Segurança do Active Directory (AD): numa configuração do AD no local, todos os utilizadores e grupos têm um identificador de segurança exclusivo imutável que se assemelha a "S-1-5-21-3878594291-2115959936-132693609-65242".

Passo 3b: Pesquisa incremental (Opcional)

Neste passo opcional, forneça uma consulta SQL para executar uma pesquisa incremental da base de dados. Com esta consulta, o conector SQL determina quaisquer alterações aos dados desde a última pesquisa incremental. Tal como na pesquisa completa, selecione todas as colunas onde pretende selecionar as opções Consulta, Pesquisa ou Obter. Especifique o mesmo conjunto de colunas da ACL que especificou na consulta de pesquisa completa.

Os componentes na imagem seguinte assemelham-se aos componentes de pesquisa completos com uma exceção. Neste caso, "ModifiedDateTime" é a coluna de marca d'água selecionada. Reveja os passos de pesquisa completos para saber como escrever a consulta de pesquisa incremental e veja a imagem seguinte como um exemplo.

Passo 4: Atribuir etiquetas de propriedade

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

Passo 5: Gerir o esquema

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

Passo 6: Gerir permissões de pesquisa

Pode optar por utilizar as ACLs especificadas no ecrã de pesquisa completa ou pode substitui-las para tornar os seus conteúdos visíveis para todos.

Passo 7: escolher as definições de atualização

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

Passo 8: rever a ligação

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

Limitações

Os conectores SQL têm estas limitações na versão de pré-visualização:

• Conector do Microsoft SQL Server: a base de dados no local tem de executar a versão 2008 ou posterior do SQL Server.
• A subscrição do Microsoft 365 e a subscrição do Azure (que aloja a base de dados SQL do Azure) têm de estar dentro do mesmo ID do Microsoft Entra.
• As ACLs só são suportadas com um Nome Principal de Utilizador (UPN), o Microsoft Entra ID ou o Active Directory Security.
• A indexação de conteúdo avançado dentro de colunas de base de dados não é suportada. Exemplos desses conteúdos são HTML, JSON, XML, blobs e análises de documentos que existem como ligações dentro das colunas da base de dados.

Solução de problemas

Depois de publicar a ligação, pode rever o estado no separador Origens de Dados no centro de administração. Para saber como fazer atualizações e eliminações, consulte Gerir o conector. Pode encontrar passos de resolução de problemas frequentemente vistos aqui.

Se tiver outros problemas ou quiser fornecer feedback, escreva-nos aka.ms/TalkToGraphConnectors.