Conector CSV Genérico – Guia de Referência Técnica (Pré-visualização)

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

• Microsoft Entra Connect Provisioning Agent (ECMA2Host)
• Microsoft Identity Manager 2016 (MIM2016)

Para o MIM 2016, o Conector está disponível como uma transferência do Centro de Transferências da Microsoft.

Para ver este Conector em ação, veja o artigo Passo a passo do Conector SQL Genérico .

Descrição geral do Conector CSV Genérico

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

Tem várias funcionalidades, como a capacidade de orquestrar a utilização do PowerShell para gerir dados de identidade antes ou depois de importar ou exportar operações. Oferece suporte para vários tipos de dados, incluindo binários e referências, suporte para valores de cadeias de carateres qualificados e cadeias de carateres de valores múltiplos.

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

A tabela seguinte lista as funcionalidades que a versão atual do conector suporta, de uma perspetiva de alto nível:

Funcionalidade	Detalhes
Suporte de Vários Produtos	A utilização deste conector é suportada com os seguintes produtos Microsoft: Microsoft Entra Connect Provisioning Agent (ECMA2Host) Microsoft Identity Manager 2016 (MIM2016)
Ficheiros CSV Suportados	Este conector suporta a gestão de utilizadores (obrigatórios) e grupos (opcional), através da configuração de até três ficheiros CSV: Ficheiro CSV de Utilizadores (por exemplo, Users.csv) Ficheiro CSV de Grupos (por exemplo, Groups.csv) Ficheiro CSV dos Membros do Grupo (por exemplo, Members.csv)
Processamento pré/pós-operação com o PowerShell	Este conector suporta a configuração de até quatro (4) Scripts do PowerShell para facilitar o processamento pré ou pós-processamento dos dados de identidade do Utilizador e do Grupo antes ou depois das importações ou exportações.
Codificação de Ficheiros CSV Suportada	O conector suporta todos os tipos de codificação de servidor predefinidos (ou instalados): (por exemplo, Unicode, UTF-8, UTF-7, ASCII, etc.)
Tipos de Dados de Campo CSV Suportados	O conector suporta os seguintes tipos de dados de atributo: Binário – (como cadeias base64) Booleano – (como Verdadeiro/Falso) Números inteiros Cadeias/Cadeias de Valores Múltiplos Referência
Delimitação do Campo CSV	Suporte para vírgulas (,) ou qualquer caráter alfamerico imprimível para qualificar o início e o fim de qualquer valor de cadeia.
Suporte de Qualificação de Cadeias	Suporte para aspas duplas (") ou qualquer caráter alfamerico imprimível para qualificar o início e o fim de qualquer valor de cadeia.
Suporte de Cadeias de Carateres de Valores Múltiplos	Suporte para cadeias de valores múltiplos
Operações de Conector Suportadas	O conector suporta as seguintes operações: Importação Completa Exportar Exportação Completa
Esquema	A deteção de esquemas é dinâmica, mas requer a configuração manual para conclusão. Os campos são identificados dinamicamente com base num delimitador especificado (ou conhecido como "Separador de Valor".) Os tipos de dados de campo são designados manualmente durante a configuração.

Pré-requisitos

Antes de utilizar o conector, certifique-se de que tem o seguinte no servidor de sincronização:

• Microsoft .NET 4.6.2 Framework ou posterior
• Ficheiros CSV que contêm o esquema pretendido para os seguintes tipos de identidade:
  • Ficheiro de Utilizadores (obrigatório)
  • Grupos (opcional)
  • Membros do Grupo (necessário se forem utilizados grupos)
• (Opcional) Scripts do PowerShell para gerir o processamento pré e pós 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 do Serviço de Sincronização do MIM

Criar um novo Conector

A lista seguinte é uma descrição geral de alto nível dos passos descritos neste guia. Para começar, tem de ser utilizada uma conta com a função Administração Sincronizações do MIM para realizar estas tarefas:

• Abra a janela Criar Novo Agente de Gestão (MA) a partir do Service Manager de Sincronização do MIM.
• Selecione o Conector CSV Genérico como o tipo de conector.
• Indique o caminho do ficheiro e o nome do ficheiro CSV a importar ou exportar.
• Especifique a codificação de ficheiros, o separador de valor, o separador de valores múltiplos e o qualificador de texto para o ficheiro CSV.
• Escolha se pretende ou não utilizar os valores na primeira linha como campos de cabeçalho.
• Selecione os tipos e atributos de objeto a importar ou exportar do ficheiro CSV.
• Configure a partição, o perfil de execução e os detalhes de mapeamento do MA.
• Indique os caminhos e parâmetros do script para os scripts do PowerShell, se existirem.
• Execute o MA para efetuar as operações de importação, sincronização ou exportação.

Para Criar um conector CSV Genérico, no Serviço de Sincronização , selecione Agente de Gestão e Criar. Selecione o Conector CSV Genérico (Microsoft ).

Conectividade

A página Conectividade contém as localizações de ficheiro dos ficheiros CSV Utilizadores, Grupos e Membros do Grupo.

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

As localizações dos seguintes ficheiros CSV são especificadas nesta página:

• Ficheiro de Utilizadores: o caminho completamente qualificado do ficheiro CSV que contém os registos de utilizador e os respetivos valores de atributo. Este ficheiro é obrigatório.
• Ficheiro de Grupos: o caminho completamente qualificado do ficheiro CSV que contém os registos de grupo. Este ficheiro é opcional.
• Ficheiro de Membros: o caminho completamente qualificado do ficheiro CSV que contém registos de referência de membros do grupo.

O ecrã Conectividade é o primeiro quando cria um novo Conector SQL Genérico. Primeiro, tem de fornecer as seguintes informações de secção:

Capacidades

Esta página descreve as capacidades do conector. As capacidades do conector são fixas e não podem ser alteradas, mas são explicadas aqui para fornecer informações sobre o funcionamento do conector.

A imagem seguinte é um exemplo da página Capacidades .

As seguintes secções listam as configurações individuais e os respetivos significados:

• Estilo de Nome Único (LDAP): o Conector GCSV utiliza a sintaxe LDAP (Lightweight Directory Access Protocol) para construir o DN (nome único) para identificar exclusivamente cada objeto utilizador ou grupo no respetivo espaço de conector. Todos os valores de DN são expressos no seguinte formato: CN=[ANCHOR_VALUE],Object=[User|Grupo],O=CSV.
• Confirmação do Objeto (Normal): normalmente, o motor de sincronização assume que pode obter o objeto novamente numa importação delta subsequente após uma exportação. É assim que o motor de sincronização funciona normalmente, mas nem todos os sistemas ligados funcionam desta forma. Esta definição de Normal garante que não existe nenhum exported-change-not-reimported aviso na importação de seguimento.
• 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 concebido para funcionar com Microsoft Entra ID. Só envia os atributos que foram alterados. Para atributos de tipo de valor, utiliza AttributeReplace e, para atributos de referência, utiliza AttributeUpdate.
• Normalizações (Nenhuma): as normalizações referem-se à uniformização dos dados para um formato consistente. Nenhum significa que não são aplicadas regras de normalização específicas. Os dados permanecem como estão sem transformações adicionais por parte do conector.

Esquema 1 (Configurações de Formato de Ficheiro CSV)

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

Esta página contém as definições de valor do caráter para estes separadores e o tipo de codificação que foi utilizado para criar o ficheiro como CSV.

A imagem seguinte é uma imagem da página Esquema 1 (Configurações de Formato de Ficheiro CSV).

A secção seguinte é uma lista das configurações individuais:

• Utilizar cabeçalhos para deteção de esquemas: quando esta opção está selecionada, indica ao conector para tratar o primeiro registo de cada ficheiro CSV como um registo de cabeçalho e não como registo de dados de identidade. Se esta opção não estiver selecionada, o conector atribui o nome Atributo com um valor inteiro incrementado exclusivo acrescentado (por exemplo, Atributo1, Atributo2, etc.) e trata a primeira linha de como um registo de dados de identidade.
• Separador de valores: este caráter separa os campos (ou seja, os valores) dos registos CSV. A vírgula (,) é a predefinição, mas é permitido qualquer caráter alfanumérico que possa ser impresso.
• Separador de valores múltiplos: este tipo de separador é utilizado para delimitar os valores individuais de uma cadeia de valores múltiplos (por exemplo, endereços proxy) ou atributos de referência (por exemplo, subordinados.) A predefinição é um ponto e vírgula (;), mas qualquer caráter alfanumérico imprimível é aceitável.
• Qualificador de texto: quando um valor de cadeia contém carateres que de outra forma seriam interpretados como delimitadores (por exemplo, por exemplo, vírgulas), é necessário que o valor seja qualificado para que o analisador CSV possa interpretar corretamente a cadeia como um único campo. As aspas duplas (") são a predefinição, mas é permitido qualquer caráter alfanumérico que possa ser impresso.

• Codificação de ficheiros: esta definição indica a codificação utilizada nos ficheiros CSV adicionados no separador Conectividade. Certifique-se de que corresponde à codificação dos seus ficheiros CSV.

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

O valor de âncora é um identificador exclusivo para um registo num ficheiro CSV. Diferencia um registo dos outros. O Conector GCSV também utiliza este valor para criar o nome único (DN) que identifica o objeto de espaço do conector relacionado.

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

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

A secção seguinte é uma lista das configurações individuais nesta página:

• Utilizador
  • Âncora do Utilizador: o campo no ficheiro Utilizadores que serve como o valor de âncora para o registo de utilizador. O primeiro campo de cabeçalho no ficheiro Utilizadores é a escolha predefinida.
  • Tipo de atributo Âncora do Utilizador: este é o tipo de atributo da âncora selecionada.
• Grupo
  • Âncora de Grupo: o campo no ficheiro Grupos que serve de valor de âncora para o registo de grupo. O primeiro campo de cabeçalho no ficheiro Grupos é a escolha predefinida.
  • Tipo de atributo Âncora de Grupo: este é o tipo de atributo da âncora selecionada.
• Membro
  • ID do Grupo Principal: o campo no ficheiro Membros que tem o mesmo valor (âncora) que o grupo principal no ficheiro CSV de Grupos. O primeiro campo no ficheiro Membros é utilizado por predefiniçã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 ficheiro Membros está selecionado por predefinição.
• Tipo de Objeto de Membro: o campo que contém um valor de cadeia "Utilizador" ou "Grupo" para indicar o tipo de objeto do membro. Este campo só é necessário se o ficheiro Membro contiver mais de dois campos. O campo Tipo de Objeto só tem de conter o valor de cadeia "Utilizador" ou um "Grupo". Se este campo estiver em falta, o conector assume que os registos do ficheiro Membros se referem a um membro do objeto Utilizador. O terceiro campo encontrado no ficheiro Membros está selecionado por predefinição.

Esquema 3 (Configurações de Esquema de Atributo de Ficheiro de Utilizadores)

Esta página destina-se a especificar e explicar o tipo de dados de cada um dos campos identificados no esquema do ficheiro CSV utilizadores e se podem ter mais do que um valor.

A imagem seguinte é um exemplo da página Esquema 3 (Configurações de Esquema de Atributo de Ficheiro de Utilizadores).

A secção seguinte lista as considerações ao efetuar atribuições de tipos de dados de atributos.

Tipos de Dados Suportados

O Conector GCSV suporta a utilização dos seguintes tipos de dados de secção:

• Booleano: um valor que pode ser verdadeiro ou falso.
• Binário: um valor que é armazenado como uma sequência de bytes, normalmente utilizado para armazenar dados, como imagens ou outros ficheiros.
• Número inteiro: um valor que é um número inteiro, sem casas decimais.
• Cadeia: um valor que é uma sequência de carateres, normalmente utilizada para armazenar dados de texto.
• Referência: um valor que é uma referência a outro objeto de utilizador. Para especificar um valor de referência num ficheiro CSV, preencha o respetivo campo com o valor de âncora do objeto de utilizador referido.

Tipos de Dados Multiple-Value Suportados

O conector suporta a utilização de atributos de valores múltiplos apenas para os seguintes tipos de dados:

• String

Esquema 4 (Configurações de Esquema de Atributo de Ficheiro de Grupos)

Esta página destina-se a especificar e explicar o tipo de dados de cada um dos campos identificados no esquema do ficheiro CSV de Grupos e se podem ter mais do que um valor.

A imagem seguinte é um exemplo da página Esquema 4 (Configurações de Esquema de Atributo de Ficheiro de Grupos).

A documentação de orientação disponibilizada no Esquema 3 (Configurações de Atributos de Ficheiro de Utilizadores também se aplica a esta secção. .

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

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. Estas funcionalidades proporcionam oportunidades para realizar uma grande variedade de ações de processamento pré e pós-processamento nos registos de utilizador e grupo de identidade.

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

A secção seguinte lista as definições de configuração individuais nesta página:

• Tempo Limite do Script (Minutos): o número de minutos que um script irá executar antes de ser automaticamente abortado. O valor predefinido para esta definição é 100 e requer um valor superior a zero (0).
• Ficheiro de script de pré-importação: o caminho completamente qualificado para o script do PowerShell que deve ser executado antes de uma importação. Esta definição é opcional e não requer um valor.
• Ficheiro de script pós-importação: o caminho completamente qualificado para o script do PowerShell que deve ser executado após uma importação. Esta definição é opcional e não requer um valor.
• Ficheiro de script de pré-exportação: o caminho completamente qualificado para o script do PowerShell que deve ser executado antes de uma exportação. Esta definição é opcional e não requer um valor.
• Ficheiro de script pós-exportação: o caminho completamente qualificado para o script do PowerShell que deve ser executado após uma exportação. Esta definição é opcional e não requer um valor.

Parâmetros de Entrada e Execução de Scripts do PowerShell

O conector GCSV executa cada um dos scripts do PowerShell configurados na sua própria sessão e não suporta a transmissão de parâmetros entre fases.

O conector transmite um parâmetro de entrada para cada script denominado OperationType. O valor deste parâmetro varia consoante a operação Executar Perfil executada e pode ser um de três valores:

Parâmetro de Entrada do PowerShell: OperationType

Embora a utilização de parâmetros de entrada não seja suportada, o conector GCSV transmite um parâmetro de entrada para a execução de cada script do PowerShell: OperationType.

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

Este valor de parâmetro pode ser utilizado na lógica dos scripts do PowerShell para determinar a operação ou ação de pré/pós-processamento adequada a tomar.  

Hierarquia de Aprovisionamento

Uma vez que os ficheiros CSV não armazenam informações numa estrutura hierárquica, o Conector GCSV não suporta configurações de aprovisionamento hierárquicas.

A imagem seguinte é um exemplo da página Hierarquia de Aprovisionamento .

Partições e Hierarquias

O Conector GCSV cria um nome único (DN) distinto para cada registo de utilizador e grupo no respetivo espaço de conector, seguindo este formato LDAP:

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

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

Tipos de Objeto

O Conector GCSV requer que, pelo menos, o tipo de objeto Utilizador seja selecionado. A escolha do tipo de objeto Grupo é opcional.

A imagem seguinte é um exemplo da página Tipos de Objeto .

Atributos

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

A imagem seguinte é um exemplo da página Atributos .

Âncoras

O Conector GCSV não suporta a utilização de âncoras complexas nem configurações de atributos de âncora que diferem dos campos de ID de âncora do ficheiro CSV correspondentes.

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

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

Aprovisionar Registos CSV

Para que o conector GCSV adicione novos objetos de Utilizador ou Grupo aos respetivos ficheiros CSV correspondentes, tem de ser aprovisionado um novo Objeto de Espaço do Conector para o mesmo.

Quer utilize o Aprovisionamento Declarativo do MIM 2016 ou escreva as suas próprias Extensões de Regras de Sincronização do MIM, os novos objetos de Espaço do Conector têm de ter um DN construído com o seguinte formato:

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

A tabela seguinte fornece detalhes sobre cada um dos valores dos componentes:

Componente	Notas
CN=[VALOR DA ÂNCORA]	O Nome Comum (CN) tem de ser um valor exclusivo para e será escrito no campo de âncora designado do ficheiro CSV.
Objeto=Utilizador/Grupo	Este componente indica o tipo de objeto deste conector. Suporta apenas "Utilizador" ou "Grupo".
O=CSV	O componente raiz comum a todos os objetos de espaço do conector GCSV.

A imagem seguinte é uma Regra de Sincronização que demonstra como construir um DN corretamente ao aprovisionar um novo objeto de Utilizador num Conector GCSV:

O código seguinte demonstra a lógica de aprovisionamento equivalente com Extensões de Regras metaversas.

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, tenha em atenção a utilização da EcapeDNComponent() função para garantir que o valor da âncora é corretamente escapado para estar em conformidade com a sintaxe LDAP.

Exemplos de Formatação de Campos CSV

As secções seguintes listam exemplos de como formatar diferentes tipos de dados em ficheiros CSV. Todos os exemplos A secção seguinte assume a utilização das predefinições do delimitador de campos do conector:

• Valor separado: Vírgula (,)
• Separador de valores múltiplos: Semi-Colon (;)
• Qualificador de texto: Aspas duplas (")

Exemplo: Qualificação de Texto

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

O exemplo CSV da secção seguinte mostra como o campo DisplayName tem valores formatados como texto qualificado:

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

Exemplo: Delimitar Cadeias de Valores Múltiplos

Para fornecer vários valores de cadeia dentro de um campo de cadeia, delimita os valores com o separador De valores múltiplos. O exemplo CSV da secção seguinte mostra como o campo ProxyAddress com vários 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 num ficheiro CSV, preencha o respetivo campo com o valor de âncora do objeto de utilizador referido. No exemplo CSV da secção seguinte, o campo Gestor contém o valor de âncora do registo de utilizador ao qual 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 ficheiros CSV, estes têm de ser convertidos em cadeias base64 que utilizem o mesmo tipo de codificação que o ficheiro CSV. A secção seguinte função do PowerShell demonstra como codificar um valor de cadeia na cadeia codificada base64 no Unicode:

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

Eis a função equivalente em C# que aceita um parâmetro de entrada chamado texto e devolve uma cadeia codificada 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 Ficheiros CSV que contêm campos booleanos devem utilizar o texto Verdadeiro ou Falso para indicar o respetivo 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 seguinte contém as limitações conhecidas do conector GCSV.

• Atributos de Referência
  • Para além do atributo Membro do grupo, os atributos de referência de valores múltiplos não são suportados.
  • O valor de referência tem de fazer referência a objetos de utilizador. As referências a objetos de grupo não são suportadas.
• Âncoras
  • Não são suportados valores de âncora duplicados entre objetos de utilizador e grupo.
  • Os nomes dos atributos de âncora têm de ser exclusivos em esquemas de utilizador e grupo.
• PowerShell
  • A passagem de variáveis de entrada para scripts do PowerShell não é suportada.