Conector CSV Genérico - Guia de Referência Técnica (Antevisão)

Este artigo descreve o conector CSV genérico (GCSV). O artigo aplica-se aos seguintes produtos:

• Agente de Provisionamento do Microsoft Entra Connect (ECMA2Host)
• Microsoft Identity Manager 2016 (MIM2016)

Para o MIM 2016, o Conector está disponível para download no Centro de Download da Microsoft.

Para ver este Conector em ação, consulte o artigo passo a passo do Generic SQL Connector.

Visão geral do conector CSV genérico

O Conector CSV Genérico (GCSV) permite integrar dados de identidade de Utilizador e Grupo mantidos em ficheiros CSV com produtos da Microsoft, como o Microsoft Entra Connect Provisioning Agent (ECMA2Host) e o Microsoft Identity Manager 2016 (MIM2016).

Ele tem vários recursos, como a capacidade de orquestrar o uso do PowerShell para gerenciar dados de identidade antes ou depois de operações de importação ou exportação. Ele oferece suporte para vários tipos de dados, incluindo binários e referências, suporte para valores de cadeia de caracteres qualificada e cadeias de caracteres de valores múltiplos.

Este artigo descreve os recursos e funções do Conector CSV Genérico e como configurá-lo para o MIM 2016.

A tabela a seguir lista os recursos que a versão atual do conector suporta, de uma perspetiva de alto nível:

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
• Arquivos CSV que contêm o esquema desejado para os seguintes tipos de identidade:
  • Arquivo de usuários (obrigatório)
  • Grupos (opcional)
  • Membros do Grupo (obrigatório se forem utilizados grupos)
• (Opcional) Scripts do PowerShell para gerenciar o processamento pré e posterior para os seguintes eventos de Tipos de Operação:
  • Pré-importação – Este script é executado antes de uma operação de importação ser executada.
  • Pós-importação – Este script é executado após a execução de uma operação de importação.
  • Pré-exportação – Este script é executado antes de uma operação de exportação ser executada.
  • Pós-exportação – Este script é executado após a execução de uma operação de exportação.

Permissões da conta de serviço de sincronização do MIM

Criar um novo conector

A lista a seguir é uma visão geral de alto nível das etapas descritas neste guia. Para começar, uma conta com a função MIM Syncs Admin precisa ser usada para executar estas tarefas:

• Abra a janela Criar Novo Agente de Gestão (MA) a partir do MIM Sync Service Manager.
• Selecione o Conector CSV Genérico como o tipo de conector.
• Forneça o caminho do arquivo e o nome do arquivo CSV a ser importado ou exportado.
• Especifique a codificação de arquivo, o separador de valor, o separador de vários valores e o qualificador de texto para o arquivo CSV.
• Escolha se deseja usar os valores na primeira linha como campos de cabeçalho ou não.
• Selecione os tipos de objeto e atributos a serem importados ou exportados do arquivo CSV.
• Configure a partição, o perfil de execução e os detalhes de mapeamento para o MA.
• Forneça os caminhos de script e parâmetros para os scripts do PowerShell, se houver.
• Execute a MA para executar as operações de importação, sincronização ou exportação.

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

Conectividade

A página Conectividade contém os locais dos ficheiros CSV de Utilizadores, Grupos e Membros do Grupo.

A imagem é um exemplo da página de Conectividade .

Os locais dos seguintes arquivos CSV são especificados nesta página:

• Users File: O caminho totalmente qualificado do ficheiro CSV que contém os registos dos utilizadores e os seus valores de atributos. Este ficheiro é obrigatório.
• Groups File: O caminho totalmente qualificado do ficheiro CSV que contém os registos do grupo. Este ficheiro é opcional.
• Arquivos de Membros: O caminho totalmente qualificado do ficheiro CSV que contém os registos de referência dos membros do grupo.

A tela Conectividade é a primeira quando você cria um novo Conector SQL Genérico. Primeiro, você precisa fornecer as seguintes informações da seção:

Capacidades

Esta página descreve os recursos do conector. Os recursos do conector são fixos e não podem ser alterados, mas são explicados aqui para fornecer informações sobre como o conector opera.

A imagem a seguir é um exemplo da página de Capacidades .

A seção a seguir lista as configurações individuais e seus significados:

• Estilo de Nome Distinguido (LDAP): O Conector GCSV usa a sintaxe LDAP (Lightweight Directory Access Protocol) para construir o DN (nome distinguido) para identificar de forma exclusiva cada objeto Utilizador ou Grupo em seu espaço do conector. Todos os valores DN são expressos no seguinte formato: CN=[ANCHOR_VALUE],Object=[User|Grupo],O=CSV.
• Confirmação de objeto (normal): Normalmente, o mecanismo de sincronização assume que pode recuperar o objeto novamente em uma importação delta subsequente após uma exportação. É assim que o mecanismo de sincronização geralmente funciona, mas nem todos os sistemas conectados operam dessa forma. Essa configuração de Normal garante que não haja nenhum aviso de exported-change-not-reimported na importação de acompanhamento.
• Tipo de exportação (MultivaluedReferenceAttributeUpdate): O tipo de exportação especifica como os objetos são formatados e enviados para o sistema de destino durante a sincronização. MultivaluedReferenceAttributeUpdate é um tipo de exportação projetado para funcionar com o Microsoft Entra ID. Ele envia apenas os atributos que foram alterados. Para atributos de tipo de valor, ele usa AttributeReplace e para atributos de referência, ele usa AttributeUpdate.
• Normalizações (Nenhuma): Normalizações referem-se à padronização de dados para um formato consistente. Nenhum significa que nenhuma regra específica de normalização é aplicada. Os dados permanecem as-is sem transformações adicionais pelo conector.

Esquema 1 (Configurações de formato de arquivo CSV)

O Conector GCSV utiliza três tipos de separadores (ou delimitadores) para delimitar e analisar campos CSV e seus valores.

Esta página contém as configurações de valor de caractere para esses separadores e o tipo de codificação que foi usado para criar o arquivo como CSV.

A imagem a seguir é da página Esquema 1 (Configurações de Formato de Arquivo CSV).

A seção a seguir é uma lista das configurações individuais:

• Usar cabeçalhos para descoberta de esquema: Quando essa opção é selecionada, ela instrui o conector a tratar o primeiro registro de cada arquivo CSV como um registro de cabeçalho e não um registro de dados de identidade. Se essa opção não estiver selecionada, o conector atribuirá o nome Atributo com um valor inteiro incrementado exclusivo anexado (por exemplo, Attribute1, Attribute2, etc.) e tratará a primeira linha de como um registro de dados de identidade.
• Separador de valores: Este caractere separa os campos (ou seja, valores) dos registros CSV. A vírgula (,) é o padrão, mas qualquer caractere alfanumérico que possa ser impresso é permitido.
• Separador de vários valores: Este tipo de separador é usado para delimitar os valores individuais de uma cadeia de caracteres de vários valores (por exemplo, endereços proxy) ou atributos de referência (por exemplo, subordinados). O padrão é um ponto-e-vírgula (;) mas qualquer caractere alfanumérico imprimível é aceitável.
• Qualificador de texto: Quando um valor de cadeia de caracteres contém caracteres que, de outra forma, seriam interpretados como delimitadores (por exemplo, como vírgulas), ele requer que o valor seja qualificado para que o analisador CSV possa interpretar corretamente a cadeia de caracteres como um único campo. As aspas duplas (") são o padrão, mas qualquer caractere alfanumérico que possa ser impresso é permitido.

• Codificação de arquivo: Esta configuração indica a codificação usada nos arquivos CSV adicionados na guia Conectividade. Certifique-se de que corresponde à codificação dos seus ficheiros CSV.

Esquema 2 (Configurações de Identidade e Campo de Referência)

O valor de âncora é um identificador exclusivo para um registro em um arquivo CSV. Diferencia um disco dos outros. O conector GCSV também usa esse valor para criar o nome distinto (DN) que identifica o objeto do espaço do conector relacionado.

Nesta página, as configurações do atributo âncora são configuradas para cada um dos arquivos CSV listados na página Conectividade.

A imagem a seguir é um exemplo da página do Esquema 2 (Configurações de Identidade e Campo de Referência).

A seção a seguir é uma lista das configurações individuais nesta página:

• Utilizador
  • User Anchor: O campo no arquivo Users que serve como o valor de âncora para o registro do usuário. O primeiro campo de cabeçalho no arquivo Usuários é a opção padrão.
  • Tipo de atributo Âncora do Usuário: Este é o tipo de atributo da âncora selecionada.
• Grupo
  • Âncora de Grupo: O campo no arquivo Grupos que serve como o valor de âncora para o registro de grupo. O primeiro campo de cabeçalho no arquivo Grupos é a opção padrão.
  • Tipo de Atributo da Âncora de Grupo: Este é o tipo de atributo da âncora selecionada.
• Estado-Membro
  • ID do Grupo Pai: O campo no arquivo Membros que tem o mesmo valor (âncora) que o grupo pai no arquivo CSV Grupos. O primeiro campo no arquivo Membros é usado por padrão.
  • ID de Membro: O campo no ficheiro Membros que tem o mesmo valor (âncora) que no ficheiro CSV Utilizadores ou Grupos. O segundo campo no arquivo Membros é selecionado por padrão.
• Tipo de Objeto Membro: O campo que contém um valor de cadeia de caracteres "User" ou "Group" para indicar o tipo de objeto do membro. Este campo só é obrigatório se o ficheiro Membro contiver mais de dois campos. O campo Tipo de objeto deve conter apenas o valor da cadeia de caracteres "User" ou um "Group". Se este campo estiver ausente, o conector assumirá que os registos do ficheiro Membros se referem a um membro do objeto User. O terceiro campo encontrado no arquivo Membros é selecionado por padrão.

Esquema 3 (Configurações de esquema de atributo de arquivo de usuários)

Esta página é para especificar e explicar o tipo de dados de cada um dos campos identificados no esquema do arquivo CSV Usuários e se eles podem ter mais de um valor.

A imagem a seguir é um exemplo da página Schema 3 (Configurações do Esquema de Atributos de Ficheiros de Utilizadores).

A seção a seguir lista considerações ao fazer atribuições de tipo de dados de atributo.

Tipos de dados suportados

O conector GCSV suporta o uso dos seguintes tipos de dados de seção:

• booleano: um valor que pode ser verdadeiro ou falso.
• binário : um valor que é armazenado como uma sequência de bytes, normalmente usado para armazenar dados como imagens ou outros arquivos.
• Inteiro: um valor que é um número inteiro, sem casas decimais.
• String: um valor que é uma sequência de caracteres, normalmente usada para armazenar dados de texto.
• Referência: um valor que é uma referência a outro objeto de usuário. Para especificar um valor de referência em um arquivo CSV, preencha seu campo com o valor âncora do objeto de usuário referido.

Tipos de dados Multiple-Value suportados

O conector suporta o uso de atributos de valores múltiplos apenas para os seguintes tipos de dados:

• String

Esquema 4 (Configurações de esquema de atributo de arquivo de grupos)

Esta página é para especificar e explicar o tipo de dados de cada um dos campos identificados no esquema do arquivo CSV Grupos e se eles podem ter mais de um valor.

A imagem a seguir é um exemplo da página Esquema 4 (Configurações de esquema de atributo de arquivo de grupos).

A orientação oferecida no Esquema 3 (Configurações de Atributos de Arquivo de Utilizadores) também se aplica a esta seção. .

Após a execução de uma operação inicial de importação completa, o espaço do conector será semelhante à seguinte imagem:

Parâmetros globais (configuração de scripts do PowerShell)

Esta página permite a configuração de scripts do PowerShell que serão executados antes e/ou depois das operações de importação e/ou exportação. Esses recursos oferecem oportunidades para executar uma ampla variedade de ações de pré e pós-processamento em seus registros de identidade, usuário e grupo.

A imagem a seguir é um exemplo da página Parâmetros Globais.

A seção a seguir lista as definições de configuração individuais nesta página:

• Tempo limite do script (minutos): o número de minutos que um script executará antes de ser automaticamente anulado. O valor padrão para essa configuração é 100 e requer um valor maior que zero (0).
• Arquivo de script de pré-importação : o caminho totalmente qualificado para o script do PowerShell que deve ser executado antes de uma importação. Essa configuração é opcional e não requer um valor.
• Arquivo de script pós-importação: o caminho totalmente qualificado para o script do PowerShell que deve ser executado após uma importação. Essa configuração é opcional e não requer um valor.
• Arquivo de script de pré-exportação: o caminho totalmente qualificado para o script do PowerShell que deve ser executado antes de uma exportação. Essa configuração é opcional e não requer um valor.
• Arquivo de script pós-exportação: o caminho totalmente qualificado para o script do PowerShell que deve ser executado após uma exportação. Essa configuração é opcional e não requer um valor.

Parâmetros de entrada e execução de script do PowerShell

O conector GCSV executa cada um dos scripts PowerShell configurados em sua própria sessão e não oferece suporte à passagem de parâmetros entre estágios.

O conector passa um parâmetro de entrada para cada script chamado OperationType. O valor desse parâmetro varia dependendo da operação Run Profile executada e pode ser um dos três valores:

Parâmetro de entrada do PowerShell: OperationType

Embora não haja suporte para o uso de parâmetros de entrada, o conector GCSV passa um parâmetro de entrada para a execução de cada script do PowerShell: OperationType.

• Full – este valor é fornecido durante as operações de Importação Total ou Exportação Completa.
• Delta – este valor é fornecido durante as operações de exportação.

Esse valor de parâmetro pode ser usado dentro da lógica dos scripts do PowerShell para determinar a operação ou ação de pré/pós-processamento apropriada a ser tomada.  

Hierarquia de provisionamento

Como os arquivos CSV não armazenam informações em uma estrutura hierárquica, o GCSV Connector não oferece suporte a nenhuma configuração de provisionamento hierárquico.

A imagem a seguir é um exemplo da página Hierarquia de Provisionamento.

Partições e Hierarquias

O Conetor GCSV cria um nome distinto (DN) para cada registo de utilizador e grupo no seu espaço de conetor, seguindo este formato LDAP.

CN=[ANCHOR_VALUE],Object=User|Group,O=CSV

A imagem a seguir é um exemplo da página Partições e Hierarquias.

Tipos de objeto

O Conector GCSV requer que pelo menos o tipo de objeto User seja selecionado. A escolha do tipo de objeto Group é opcional.

A imagem a seguir é um exemplo da página Tipos de objeto.

Atributos

Esta página exibe uma lista normalizada de todos os atributos em todos os esquemas de tipo de objeto selecionados.

A imagem a seguir é um exemplo da página Atributos.

Âncoras

O Conector GCSV não suporta o uso de âncoras complexas nem configurações de atributos de âncora que diferem dos campos de ID de âncora do arquivo CSV correspondente.

Para alterar as designações de âncora exibidas nesta página, retorne ao Esquema 2 (Configurações de Âncora).

A seguinte imagem é um exemplo da página Âncoras.

Provisionamento de registros CSV

Para que o conector GCSV adicione novos objetos de Utilizador ou Grupo aos seus arquivos CSV correspondentes, deve ser provisionado um novo objeto de espaço de conector para isso.

Seja usando de provisionamento declarativo do MIM 2016 ou escrevendo seu próprio Extensões de Regras de Sincronização do MIM, os novos objetos de Espaço do Conector devem ter um DN construído usando o seguinte formato:

CN=[ANCHOR_VALUE],Object=Utilizador|Grupo,O=CSV

A tabela a seguir fornece detalhes sobre cada um dos valores de componentes:

A imagem a seguir é uma Regra de Sincronização que demonstra como construir um DN corretamente ao provisionar um novo objeto de Utilizador em um Conector GCSV:

O código a seguir demonstra a lógica de provisionamento equivalente usando Metaverse Rules Extensions.

void IMVSynchronization.Provision(MVEntry mventry)
{
	if (mventry["employeeID"].IsPresent)
	{
		ConnectedMA GCSVConnector = = mventry.ConnectedMAs["Generic CSV Conenctor"];

		if (GCSVConnector.Connectors.Count == 0)
		{
			CSEntry csentry = GCSVConnector.Connectors.StartNewConnector("user");

			//Sets DN to "CN=[ANCHOR_VALUE],OBJECT=[User|Group],O=CSV"
			csentry.DN = GCSVConnector.EscapeDNComponent("CN=" + mventry["employeeID"].Value).Concat("OBJECT=User,O=CSV");

			csentry["AccountName"].StringValue = mventry["accountName"].StringValue;
			csentry["CountryCode"].IntegerValue = 1;
			csentry["DisplayName"].Value = mventry["displayName"].Value;
			csentry["ProxyAddresses"].Value = mventry["proxyAddressCollection"].Value;
			csentry["IsActive"].BooleanValue = true;
			csentry["Manager"].Value = mventry["manager"].Value;
			csentry["ProfilePic"].Value = mventry["pic"].Value;

			csentry.CommitNewConnector();
		}
	}
}

Na imagem anterior, observe o uso da função EcapeDNComponent() para garantir que o valor da âncora seja convertido corretamente para estar em conformidade com a sua sintaxe LDAP.

Exemplos de formatação de campo CSV

As seções a seguir listam exemplos de como formatar diferentes tipos de dados em arquivos CSV. Todos os exemplos A seção a seguir pressupõe o uso das configurações padrão do delimitador de campo do conector:

• Valor separado: Vírgula (,)
• Separador multivalor: Semi-Colon (;)
• Qualificador de texto: aspas duplas (")

Exemplo: Qualificação de texto

Se um valor de cadeia de caracteres contiver caracteres que, de outra forma, seriam interpretados como delimitadores (por exemplo, vírgulas), ele exigirá que o valor seja qualificado para que o analisador CSV possa interpretar corretamente a cadeia de caracteres como um único campo.

O exemplo CSV da seção a seguir mostra como o campo DisplayName tem valores formatados como texto qualificado:

EmployeeID,DisplayName
E001,"Smith, John"
E002,"Doe, Jane"
E003,"Perez, Juan"

Exemplo: Delimitando cadeias de caracteres de valores múltiplos

Para fornecer vários valores de cadeia de caracteres dentro de um campo de cadeia de caracteres, delimite os valores com o separador Multivalor. O exemplo de CSV na seção seguinte mostra como usar o campo ProxyAddress com múltiplos valores:

EmployeeID,DisplayName,ProxyAddresses
E001,"Smith, John",SMTP:john.smith@contoso.com;smtp:js001@contoso.com
E002,"Doe, Jane",SMTP:jane.doe@contoso.com;smtp:jd002@contoso.com

Exemplo: campos de referência

Para especificar um valor de referência em um arquivo CSV, preencha seu campo com o valor âncora do objeto de usuário referido. No exemplo CSV da seção a seguir, o campo Manager contém o valor de âncora do registro de usuário ao qual ele se refere:

EmployeeID,DisplayName,Manager
E001,"Smith, John",
E002,"Doe, Jane",E001
E003,"Doe, Jane", 
E004,"Perez, Juan",

Exemplo: campos binários

Para expressar valores binários em arquivos CSV, eles devem ser convertidos em cadeias de caracteres base64 que usam o mesmo tipo de codificação que o arquivo CSV. A função PowerShell da seção a seguir demonstra como codificar um valor de cadeia de caracteres em sua cadeia de caracteres codificada em base64 em Unicode:

function ConvertTo-Base64([string]$text) 
{
    $bytes = [System.Text.Encoding]::Unicode.GetBytes($text)
    $encodedText = [System.Convert]::ToBase64String($bytes)
    return $encodedText
}

Aqui está a função equivalente em C# que aceita um parâmetro de entrada chamado texto e retorna uma cadeia de caracteres codificada em base64 em Unicode.

public static string ConvertToBase64(string text)
{
    byte[] bytes = System.Text.Encoding.UTF8.GetBytes(text);
    string encodedText = System.Convert.ToBase64String(bytes);
    return encodedText;
}

Exemplo: campos booleanos

Os arquivos CSV que contêm campos booleanos devem usar o texto Verdadeiro ou Falso para indicar seu valor. A secção seguinte é uma

EmployeeID,DisplayName,IsActive
E001,"Smith, John",true
E002,"Doe, Jane",true
E003,"Perez, Juan",false

Limitações conhecidas

A lista a seguir contém as limitações conhecidas do conector GCSV.

• Atributos de referência
  • Com exceção do atributo Member do grupo, os atributos de referência multivalorados não são suportados.
  • O valor de referência deve referir-se a objetos de usuário. Não há suporte para referências a objetos de grupo.
• Âncoras
  • Não há suporte para valores de âncora duplicados entre objetos de usuário e grupo.
  • Os nomes dos atributos de âncora devem ser exclusivos entre esquemas de usuário e grupo.
• PowerShell
  • Não há suporte para a passagem de variáveis de entrada para scripts do PowerShell.