Referência técnica genérica do SQL Connector

Este artigo descreve o Generic SQL Connector. O artigo aplica-se aos seguintes produtos:

• Microsoft Identity Manager 2016 (MIM2016)
• Microsoft Entra ID

Por MIM2016, o Conector está disponível como um download no Centro de Download da Microsoft.

Para ver esse Conector em ação, consulte o artigo passo a passo do Conector SQL Genérico.

Nota

O Microsoft Entra ID agora fornece uma solução leve baseada em agente para provisionar usuários em um banco de dados SQL, sem precisar de uma implantação de sincronização do MIM. Recomendamos usá-lo para provisionamento de usuários de saída. Mais informações.

Visão geral do SQL Connector genérico

O SQL Connector Genérico permite integrar o serviço de sincronização com um sistema de banco de dados que oferece conectividade ODBC.

De uma perspetiva de alto nível, os seguintes recursos são suportados pela versão atual do conector:

Caraterística	Suporte
Fonte de dados conectada	O conector é suportado com todos os drivers ODBC de 64 bits*. Foi testado com o seguinte: Microsoft SQL Server & SQL Azure IBM DB2 11.5.8 Oráculo 11g Oracle 12c e 18c Oracle 21c e 23c MySQL 5.x MySQL 8,x Postgres
Cenários	Gerenciamento do ciclo de vida do objeto Gestão de palavra-passe
Operações	Importação Completa e Importação Delta, Exportação Para exportação: adicionar, excluir, atualizar e substituir Definir palavra-passe, alterar palavra-passe
Esquema	Descoberta dinâmica de objetos e atributos

Pré-requisitos

Antes de usar o conector, verifique se você tem o seguinte no servidor de sincronização:

• Microsoft .NET 4.6.2 Framework ou posterior
• Drivers de cliente ODBC de 64 bits
• Se você estiver usando o conector para se comunicar com o Oracle 12c, isso exigirá o Oracle Instant Client 12.2.0.1 ou mais recente com o pacote ODBC.
• Se você estiver usando o conector para se comunicar com o Oracle 18c-23c, isso exigirá que o Oracle Instant Client 18-23 ou mais recente com o pacote ODBC e a variável de sistema NLS_LANG seja definida para suportar caracteres UTF8, por exemplo, NLS_LANG=AMERICAN_AMERICA. AL32UTF8.
• Esse conector usa instruções preparadas para SQL e várias instruções por transação. Alguns sistemas RDBM podem ter problemas em seus drivers ODBC relacionados ao tratamento de transações, instruções SQL preparadas do lado do servidor e várias instruções dentro da mesma transação. Configure suas opções de conexão DSN de acordo para garantir que essas instruções sejam enviadas corretamente para seu banco de dados., Por exemplo, MySQL ODBC Driver versão 8.0.32 precisa de opções NO_SSPS=1 e MULTI_STATEMENTS=1. Outras opções como 'autocommit' ou 'commit on successful operations only' podem afetar a forma como as exportações em lote são tratadas; Consulte o administrador do banco de dados para obter detalhes. Para solucionar problemas durante a exportação, defina o tamanho do lote de exportação como 1 e habilite o registro detalhado do conector.

A implantação desse conector pode exigir alterações na configuração do banco de dados, bem como alterações na configuração do MIM. Para implantações que envolvem a integração do MIM com um servidor de banco de dados de terceiros em um ambiente de produção, recomendamos que os clientes trabalhem com seu fornecedor de banco de dados ou com um parceiro de implantação para obter ajuda, orientação e suporte para essa integração.

Permissões na fonte de dados conectada

Para criar ou executar qualquer uma das tarefas suportadas no conector SQL genérico, você deve ter:

• db_datareader
• db_datawriter

Portas e protocolos

Para obter as portas necessárias para o driver ODBC funcionar, consulte a documentação do fornecedor do banco de dados.

Criar um novo conector

Para criar um conector SQL genérico, em Serviço de Sincronização, selecione Agente de Gerenciamento e Criar. Selecione o Conector SQL (Microsoft) Genérico.

Conectividade

O conector usa um arquivo DSN ODBC para conectividade. Crie o arquivo DSN usando fontes de dados ODBC encontradas no menu Iniciar em Ferramentas administrativas. Na ferramenta administrativa, crie um DSN de arquivo para que ele possa ser fornecido ao conector.

A tela Conectividade é a primeira quando você cria um novo Conector SQL Genérico. Primeiro, tem de fornecer as seguintes informações:

• Caminho do arquivo DSN
• Autenticação
  • Nome de Utilizador
  • Palavra-passe

O banco de dados deve oferecer suporte a um destes métodos de autenticação:

• Autenticação do Windows: o banco de dados de autenticação usa as credenciais do Windows para verificar o usuário. O nome de usuário/senha especificado é usado para autenticar com o banco de dados. Essa conta precisa de permissões para o banco de dados.
• Autenticação SQL: O banco de dados de autenticação usa o nome de usuário/senha definido na tela Conectividade para se conectar ao banco de dados. Se você armazenar o nome de usuário/pasword no arquivo DSN, as credenciais fornecidas na tela Conectividade terão precedência.
• Autenticação do Banco de Dados SQL do Azure: para obter mais informações, consulte Conectar-se ao Banco de Dados SQL por meio da autenticação do Microsoft Entra.

DN é Âncora: Se você selecionar essa opção, o DN também será usado como o atributo de âncora. Ele pode ser usado para uma implementação simples, mas também tem a seguinte limitação:

• O conector suporta apenas um tipo de objeto. Portanto, quaisquer atributos de referência só podem fazer referência ao mesmo tipo de objeto.

Tipo de exportação: Substituição de objeto: Durante a exportação, quando apenas alguns atributos foram alterados, o objeto inteiro com todos os atributos é exportado e substitui o objeto existente.

Esquema 1 (Detetar tipos de objeto)

Nesta página, você vai configurar como o Conector vai encontrar os diferentes tipos de objeto no banco de dados.

Cada tipo de objeto é apresentado como uma partição e configurado ainda mais em Configurar partições e hierarquias.

Método de deteção de tipo de objeto: O conector suporta esses métodos de deteção de tipo de objeto.

• Valor fixo: você fornece a lista de tipos de objeto com uma lista separada por vírgula. Por exemplo: User,Group,Department.
  
• Tabela/Exibição/Procedimento armazenado: Forneça o nome da tabela/exibição/procedimento armazenado e, em seguida, o nome da coluna que fornece a lista de tipos de objeto. Se você usar um procedimento armazenado, forneça também parâmetros para ele no formato [Name]:[Direction]:[Value]. Forneça cada parâmetro em uma linha separada (use Ctrl+Enter para obter uma nova linha).
  
• Consulta SQL: Esta opção permite fornecer uma consulta SQL que retorna uma única coluna com tipos de objeto, por exemplo SELECT [Column Name] FROM TABLENAME. A coluna retornada deve ser do tipo string (varchar).

Esquema 2 (Detetar tipos de atributos)

Nesta página, você vai configurar como os nomes e tipos de atributos serão detetados. As opções de configuração são listadas para cada tipo de objeto detetado na página anterior.

Método de deteção de tipo de atributo: O conector suporta esses métodos de deteção de tipo de atributo com cada tipo de objeto detetado na tela Esquema 1.

• Tabela/Exibição/Procedimento armazenado: Forneça o nome da tabela/exibição/procedimento armazenado que deve ser usado para localizar os nomes dos atributos. Se você usar um procedimento armazenado, forneça também parâmetros para ele no formato [Name]:[Direction]:[Value]. Forneça cada parâmetro em uma linha separada (use Ctrl+Enter para obter uma nova linha). Para detetar os nomes de atributos em um atributo de vários valores, forneça uma lista separada por vírgulas de Tabelas ou Exibições. Não há suporte para cenários de valores múltiplos quando as tabelas pai e filho têm os mesmos nomes de coluna.
• Consulta SQL: esta opção permite fornecer uma consulta SQL que retorna uma única coluna com nomes de atributos, por exemplo SELECT [Column Name] FROM TABLENAME. A coluna retornada deve ser do tipo string (varchar).

Esquema 3 (Definir âncora e DN)

Esta página permite configurar o atributo anchor e DN para cada tipo de objeto detetado. Você pode selecionar vários atributos para tornar a âncora exclusiva.

• Os atributos multivalorados e booleanos não são listados.

• O mesmo atributo não pode ser usado para DN e âncora, a menos que DN seja Âncora e esteja selecionado na página Conectividade.

• Se DN for Anchor estiver selecionado na página Conectividade, esta página exigirá apenas o atributo DN. Este atributo também seria usado como o atributo âncora.

  

Esquema 4 (Definir tipo de atributo, referência e direção)

Esta página permite configurar o tipo de atributo, como inteiro, binário ou booleano, e a direção para cada atributo. Todos os atributos do esquema de página 2 são listados, incluindo atributos de vários valores.

• DataType: Usado para mapear o tipo de atributo para os tipos conhecidos pelo mecanismo de sincronização. O padrão é usar o mesmo tipo detetado no esquema SQL, mas DateTime e Reference não são facilmente detetáveis. Para esses, você precisa especificar DateTime ou Reference.
• Direção: Você pode definir a direção do atributo como Importar, Exportar ou ImportExport. ImportExport é o padrão.

Notas:

• Se um tipo de atributo não for detetável pelo conector, ele usará o tipo de dados String.
• As tabelas aninhadas podem ser consideradas tabelas de banco de dados de uma coluna. O Oracle armazena as linhas de uma tabela aninhada sem nenhuma ordem específica. No entanto, quando você recupera a tabela aninhada em uma variável PL/SQL, as linhas recebem subscritos consecutivos a partir de 1. Isso lhe dá acesso semelhante a uma matriz a linhas individuais.
• VARRYS não são suportados no conector.

Esquema 5 (Definir partição para atributos de referência)

Nesta página, você configura para todos os atributos de referência a qual partição (tipo de objeto) um atributo está se referindo.

Se você usar DN é âncora, então você deve usar o mesmo tipo de objeto que você está se referindo. Não é possível fazer referência a outro tipo de objeto.

Nota

A partir da atualização de março de 2017, há agora uma opção para "*" Quando esta opção for escolhida, todos os tipos de membros possíveis serão importados.

Importante

A partir de maio de 2017, a opção "*", também conhecida como qualquer opção , foi alterada para suportar o fluxo de importação e exportação. Se você quiser usar essa opção, sua tabela/exibição de valores múltiplos deve ter um atributo que contenha o tipo de objeto.

Se "*" estiver selecionado, o nome da coluna com o tipo de objeto também deve ser especificado.

Após a importação, você verá algo semelhante à imagem abaixo:

Parâmetros de Globais

A página Parâmetros Globais é usada para configurar a Importação Delta, o formato Data/Hora e o método Senha.

O Generic SQL Connector suporta os seguintes métodos para importação delta:

• Trigger: Consulte Gerando visualizações delta usando triggers.
• Marca d'água: uma abordagem genérica que pode ser usada com qualquer banco de dados. A consulta de marca d'água é pré-preenchida com base no fornecedor do banco de dados. Uma coluna de marca d'água deve estar presente em todas as tabelas/visualizações usadas. Esta coluna deve controlar inserções e atualizações para as tabelas como e suas tabelas dependentes (multi-valor ou filho). Os relógios entre o Serviço de Sincronização e o servidor de banco de dados devem ser sincronizados. Caso contrário, algumas entradas na importação delta podem ser omitidas.
  Limitação:
  • A estratégia de marca d'água não suporta objetos excluídos.
• Snapshot: (Funciona somente com o Microsoft SQL Server) Gerando exibições Delta usando instantâneos
• Controle de alterações: (funciona somente com o Microsoft SQL Server) Sobre o controle de alterações
  Limitações:
  • O atributo Anchor & DN deve fazer parte da chave primária do objeto selecionado na tabela.
  • A consulta SQL não é suportada durante a Importação e Exportação com Controlo de Alterações.

Parâmetros adicionais: especifique o fuso horário do servidor de banco de dados indicando onde o servidor de banco de dados está localizado. Esse valor é usado para suportar os vários formatos de atributos de data e hora.

O conector sempre armazena data e data-hora no formato UTC. Para poder converter corretamente a data e as horas, o fuso horário do servidor de banco de dados e o formato usado devem ser especificados. O formato deve ser expresso no formato .NET.

Durante a exportação, cada atributo de data e hora deve ser fornecido ao Conector no formato de hora UTC.

Configuração de senha: O conector fornece recursos de sincronização de senha e suporta definir e alterar senha.

O conector fornece dois métodos para dar suporte à sincronização de senha:

• Procedimento armazenado: Este método requer dois procedimentos armazenados para suportar set & Change password. Digite todos os parâmetros para adicionar e alterar a operação de senha em Definir controladora de armazenamento de senha e Alterar parâmetros da controladora de armazenamento, respectivamente, conforme exemplo abaixo.
• Extensão de senha: Este método requer DLL de extensão de senha (você precisa fornecer o nome da DLL de extensão que está implementando a interface IMAExtensible2Password ). O assembly de extensão de senha deve ser colocado na pasta de extensão para que o conector possa carregar a DLL em tempo de execução.

Você também precisa habilitar o Gerenciamento de Senhas na página Configurar Extensão .

Configurar Partições e Hierarquias

Na página partições e hierarquias, selecione todos os tipos de objeto. Cada tipo de objeto é sua própria partição.

Você também pode substituir os valores definidos na página Conectividade ou Parâmetros Globais .

Configurar Âncoras

Esta página é somente leitura, uma vez que a âncora já foi definida. O atributo de âncora selecionado é sempre anexado com o tipo de objeto para garantir que ele permaneça exclusivo entre os tipos de objeto.

Configurar parâmetro de etapa de execução

Essas etapas são configuradas nos perfis de execução no conector. Essas configurações fazem o trabalho real de importação e exportação de dados.

Importação Completa e Delta

O SQL Connector genérico suporta importação completa e delta usando estes métodos:

• Tabela
• Vista
• Procedimento Armazenado
• Consulta SQL

Tabela/Vista
Para importar atributos de vários valores para um objeto, você precisa fornecer o nome da tabela/exibição em Nome da tabela/exibições com vários valores e respetivas condições de associação na condição Ingressar com a tabela pai. Se houver mais de uma tabela de valores múltiplos na fonte de dados, você poderá usar união para uma única exibição.

Importante

O agente de gerenciamento SQL genérico pode trabalhar apenas com uma tabela de vários valores. Não coloque em Nome da tabela/exibições de vários valores mais de um nome de tabela. É a limitação do SQL Genérico.

Exemplo: você deseja importar o objeto Employee e todos os seus atributos de vários valores. Existem duas tabelas, denominadas Funcionário (tabela principal) e Departamento (com vários valores). Efetue o seguinte procedimento:

• Digite Employee em Table/View/SP.
• Digite Departamento em Nome da tabela/exibições com vários valores.
• Digite a condição de junção entre Employee & Department em Join Condition, por exemplo Employee.DEPTID=Department.DepartmentID.

Procedimentos armazenados

• Se você tiver muitos dados, é recomendável implementar a paginação com seus Procedimentos Armazenados.
• Para que seu Procedimento Armazenado ofereça suporte à paginação, você precisa fornecer Índice de Início e Índice de Fim. Consulte: Paginação eficiente através de grandes quantidades de dados.
• @StartIndex e @EndIndex são substituídos em tempo de execução com o respetivo valor de tamanho de página configurado na página Configurar etapa . Por exemplo, quando o conector recupera a primeira página e o tamanho da página é definido como 500, em tal situação @StartIndex seria 1 e @EndIndex 500. Esses valores aumentam quando o conector recupera páginas subsequentes e altera o @StartIndex valor de Ads @EndIndex .
• Para executar o procedimento armazenado parametrizado, forneça os parâmetros no [Name]:[Direction]:[Value] formato. Insira cada parâmetro em uma linha separada (Use Ctrl + Enter para obter uma nova linha).
• O conector SQL genérico também oferece suporte à operação de importação de servidores vinculados no Microsoft SQL Server. Se as informações devem ser recuperadas de uma tabela no servidor vinculado, então a tabela deve ser fornecida no formato: [ServerName].[Database].[Schema].[TableName]
• O SQL Connector Genérico suporta apenas os objetos que têm estrutura semelhante (nome do alias e tipo de dados) entre as informações das etapas de execução e a deteção de esquema. Se o objeto selecionado do esquema e as informações fornecidas na etapa de execução forem diferentes, o SQL Connector não poderá oferecer suporte a esse tipo de cenário.

Consulta SQL

Importante

CRLF ou novo caractere de linha serve como um separador entre várias instruções.

Consulta SQL de exemplo com paginação - consulta incorreta, não funcionará como o novo caractere de linha é usado:

WITH A AS 
  (select dense_rank() over (order by BusinessEntityID) 
    rownumber, BusinessEntityID, DeptID, NationalIDNumber, LoginID, JobTitle, BirthDate, MaritalStatus, HireDate, ModifiedDate, Password 
    from Employees
  ) select * from A where rownumber between @StartIndex and @EndIndex

Exemplo de consulta SQL com paginação - consulta correta:

WITH A AS (select dense_rank() over (order by BusinessEntityID) rownumber, BusinessEntityID, DeptID, NationalIDNumber, LoginID, JobTitle, BirthDate, MaritalStatus, HireDate, ModifiedDate, Password from Employees) select * from A where rownumber between @StartIndex and @EndIndex

• Não há suporte para consultas de vários conjuntos de resultados.
• A consulta SQL suporta a paginação e fornece o Índice de Início e o Índice de Fim como uma variável para dar suporte à paginação.

Importação Delta

A configuração Delta Import requer um pouco mais de configuração em comparação com a Full Import.

• Se você escolher a abordagem Trigger ou Snapshot para controlar alterações delta, forneça a tabela de histórico ou o banco de dados de instantâneo na tabela de histórico ou na caixa de nome do banco de dados de instantâneo.
• Você também precisa fornecer a condição de junção entre a tabela Histórico e a tabela pai, por exemplo Employee.ID=History.EmployeeID
• Para controlar a transação na tabela pai a partir da tabela de histórico, você deve fornecer o nome da coluna que contém as informações da operação (Adicionar/Atualizar/Excluir).
• Se você escolher Marca d'água para rastrear alterações delta, forneça o nome da coluna que contém as informações da operação em Nome da coluna da marca d'água.
• A coluna do atributo change Type é necessária para o tipo de alteração. Esta coluna mapeia uma alteração que ocorre na tabela primária ou na tabela de vários valores para um tipo de alteração na visualização delta. Esta coluna pode conter o tipo de alteração Modify_Attribute para alteração no nível do atributo ou um tipo de alteração Adicionar, Modificar ou Excluir para um tipo de alteração no nível do objeto. Se for algo diferente do valor padrão Adicionar, Modificar ou Excluir, você poderá definir esses valores usando essa opção.

Exportar

Suporte ao SQL Connector genérico Exporte usando quatro métodos suportados, como:

• Tabela
• Vista
• Procedimento Armazenado
• Consulta SQL

Tabela/Vista
Se você escolher a opção Tabela/Exibição, o conector gerará as respetivas consultas para fazer a Exportação.

Procedimentos armazenados

Se você escolher a opção Procedimento armazenado, Exportar exigirá três procedimentos armazenados diferentes para executar operações de inserção/atualização/exclusão.

• Adicionar nome da controladora de armazenamento: esta controladora de armazenamento é executada se algum objeto chegar ao conector para inserção na respetiva tabela.
• Atualizar nome da controladora de armazenamento: esta controladora de armazenamento é executada se algum objeto chegar ao conector para atualização na respetiva tabela.
• Excluir nome da controladora de armazenamento: esta controladora de armazenamento é executada se algum objeto chegar ao conector para exclusão na respetiva tabela.
• Atributo selecionado do esquema usado como um valor de parâmetro para o procedimento armazenado. Por exemplo, @EmployeeName: INPUT: EmployeeName (EmployeeName é selecionado no esquema do conector e o conector substitui o respetivo valor ao fazer a exportação)
• Para executar o procedimento armazenado parametrizado, forneça parâmetros no [Name]:[Direction]:[Value] formato. Insira cada parâmetro em uma linha separada (Use Ctrl + Enter para obter uma nova linha).

Consulta SQL

Se você escolher a opção de consulta SQL, Exportar exigirá três consultas diferentes para executar operações de Inserir/Atualizar/Excluir.

• Inserir consulta: Esta consulta é executada se algum objeto chegar ao conector para inserção na respetiva tabela.
• Consulta de atualização: Esta consulta é executada se algum objeto chegar ao conector para atualização na respetiva tabela.
• Excluir consulta: Esta consulta é executada se algum objeto chegar ao conector para exclusão na respetiva tabela.
• Atributo selecionado do esquema usado como um valor de parâmetro para a consulta, por exemplo Insert into Employee (ID, Name) Values (@ID, @EmployeeName)

Importante

CRLF ou novo caractere de linha serve como um separador entre várias instruções.

Exemplo de consulta SQL de atualização em várias etapas - o novo caractere de linha é usado para separar instruções SQL:

update Employee set jobTitle=@JOBTITLE where BusinessEntityID=@BUSINESSENTITYID
insert into ChangeLog VALUES (@BUSINESSENTITYID)

Resolução de Problemas

• Para obter informações sobre como habilitar o log para solucionar problemas do conector, consulte Como habilitar o rastreamento ETW para conectores.