Conector CSV Genérico – Guia de Referência Técnica (Prévia)
Este artigo descreve o Conector CSV Genérico (GCSV). O artigo se aplica aos seguintes produtos:
- Agente de Provisionamento do Microsoft Entra Connect (ECMA2Host)
- Microsoft Identity Manager 2016 (MIM2016)
Para MIM 2016, o Conector está disponível como download do Microsoft Download Center.
Para ver esse conector em ação, consulte o artigo Generic SQL Connector step-by-step .
Observação
O serviço de provisionamento do Azure AD agora fornece uma solução baseada em agente simplificado para provisionamento de usuários em arquivos CSV, sem a necessidade de uma implementação completa de sincronização MIM. Recomendamos avaliar se ele atende às suas necessidades. Saiba mais.
O Conector CSV Genérico (GCSV) permite integrar dados de identidade de usuário e grupo mantidos em arquivos CSV com produtos da Microsoft, como o Agente de Provisionamento do Microsoft Entra Connect (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 importações ou operações de exportação. Ele oferece suporte para vários tipos de dados, incluindo binários e referências, suporte para valores de cadeia de caracteres qualificados e cadeias de caracteres multivalorizados.
Este artigo descreve os recursos e as funções do Conector CSV Genérico e como configurá-lo para MIM 2016.
A tabela a seguir lista os recursos compatíveis com a versão atual do conector, de uma perspectiva de alto nível:
| Característica | Detalhes |
|---|---|
| Suporte a vários produtos | O uso desse conector tem suporte com os seguintes produtos da Microsoft: |
| Arquivos CSV com suporte | Esse conector dá suporte ao gerenciamento de usuários (obrigatórios) e grupos (opcional), por meio da configuração de até três arquivos CSV: |
| Processamento pré/pós-operação com o PowerShell | Esse conector dá suporte à configuração de até quatro (4) scripts do PowerShell para facilitar o pré-processamento ou pós-processamento de dados de identidades de usuários e grupos antes ou depois de importações ou exportações. |
| Codificações de arquivo CSV suportadas | O conector dá suporte a todos os tipos de codificação de servidor padrão (ou instalados): (por exemplo, Unicode, UTF-8, UTF-7, ASCII etc.) |
| Tipos de dados de campo CSV com suporte | O conector dá suporte aos seguintes tipos de dados de atributo: |
| Delimitação de campo CSV | Suporte para vírgulas (,) ou qualquer caractere alfanumérico imprimível para qualificar o início e o fim de qualquer valor de cadeia de caracteres. |
| Suporte à qualificação de string | Suporte para aspas duplas (") ou qualquer caractere alfanumérico imprimível para qualificar o início e o fim de qualquer valor de cadeia de caracteres. |
| Suporte a cadeias de caracteres com vários valores | Suporte para cadeias de caracteres com vários valores |
| Operações de conector com suporte | O conector dá suporte às seguintes operações: |
| Esquema | A descoberta de esquema é dinâmica, mas requer configuração manual para conclusão. Os campos são identificados dinamicamente com base em um delimitador especificado (ou conhecido como "Separador de Valor". Os tipos de dados de campo são designados manualmente durante a configuração. |
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 (necessários se os grupos forem usados)
- (Opcional) Scripts do PowerShell para gerenciar o pré e pós-processamento para os seguintes tipos de operações:
- Pré-importação – esse script é executado antes da execução de uma operação de importação.
- Pós-Importação – esse script é executado após a execução de uma operação de importação.
- Pré-exportação – esse script é executado antes de uma operação de exportação ser executada.
- Pós-Exportação – esse script é executado após a execução de uma operação de exportação.
Importante
A conta de serviço de Sincronização do MIM 2016 é o contexto de segurança que executa as operações em arquivos CSV e executa os scripts de pré-processamento/pós-processamento do PowerShell. Essa conta de serviço precisa de permissões de leitura/gravação para todos os arquivos CSV e PowerShell configurados. Ele também precisa das permissões apropriadas ExecutePolicy do PowerShell para executar os scripts configurados.
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 Administrador de Sincronizações do MIM precisa ser usada para executar estas tarefas:
- Abra a janela Criar novo agente de gerenciamento (MA) no Gerenciador de serviços de sincronização MIM.
- Selecione o conector genérico CSV 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 os 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 e parâmetros de script para os scripts do PowerShell, se houver.
- Execute o 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 Conector CSV genérico (Microsoft) .
A página Conectividade contém os locais de arquivo dos arquivos CSV dos usuários, dos grupos e dos membros do grupo.
A seguinte imagem é um exemplo da página Conectividade.
Os locais dos seguintes arquivos CSV são especificados nesta página:
- Arquivo de Usuários: o caminho totalmente qualificado do arquivo CSV que contém os registros de usuário e seus valores de atributo. Esse arquivo é necessário.
- Arquivo de Grupos: o caminho completo do arquivo CSV que contém os registros de grupo. Esse arquivo é opcional.
- Arquivo de Membros: o caminho completo do arquivo CSV que contém registros de referência dos membros do grupo.
Importante
A conta de serviço do MIM Sync deve ter permissões de leitura e permissões de gravação para todos os arquivos CSV designados. Conforme mencionado anteriormente, os arquivos de grupo e membro não serão necessários se apenas os usuários estiverem configurados.
A tela de conectividade é a primeira quando você cria um novo conector SQL genérico. Primeiro, você precisa fornecer as informações da seguinte seção:
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 informar sobre o funcionamento do conector.
A seguinte imagem é um exemplo da página Funcionalidades.
A seção a seguir lista as configurações individuais e seus significados:
- Estilo de Nome Distinto (LDAP): O Conector GCSV usa a sintaxe LDAP (Lightweight Directory Access Protocol) para construir o DN (nome distinto) que identifica exclusivamente cada objeto de Usuário ou Grupo em seu espaço de conector. Todos os valores de DN são expressos no seguinte formato: CN=[ANCHOR_VALUE],Object=[User|Group],O=CSV.
- Confirmação de Objeto (Normal): normalmente, o mecanismo de sincronização pressupõe que ele possa 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 maneira. Essa configuração de Normal garante que não haja nenhum aviso de
exported-change-not-reimportedna importação subsequente. - 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, usa AttributeUpdate.
- Normalizações (Nenhum): Normalizações se referem à padronização de dados para um formato consistente. Nenhum significa que nenhuma regra de normalização específica é aplicada. Os dados permanecem as-is sem transformações adicionais pelo conector.
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 é uma imagem 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, instrui o conector a tratar o primeiro registro de cada arquivo CSV como um registro de cabeçalho e não registro de dados de identidade. Se essa opção não estiver selecionada, o conector atribuirá o nome Attribute com um valor inteiro incrementado exclusivo acrescentado (por exemplo, Attribute1, Attribute2, etc.) e tratará a primeira linha como um registro de dados de identidade.
- separador de valores: esse caractere separa os campos (ou seja, valores) dos registros CSV. A vírgula (,) é o padrão, mas qualquer caractere alfanumérico que pode ser impresso é permitido.
- separador multivalor: Esse tipo de separador é usado para delimitar os valores individuais de uma cadeia de caracteres com 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 pode ser impresso é permitido.
Observação
Embora os esquemas de arquivos CSV não contenham campos multivalorizados ou não contenham valores que exijam qualificação de cadeia de caracteres, a designação de um caractere imprimível exclusivo para cada tipo de separador é necessária.
- Codificação de arquivo: essa configuração indica a codificação usada nos arquivos CSV adicionados no menu Conectividade. Verifique se ela corresponde à codificação dos seus arquivos CSV.
Observação
Se você não tiver certeza sobre o tipo de codificação dos arquivos CSV, tente usar o tipo de codificação Unicode padrão. Unicode é um padrão comum que dá suporte a muitos caracteres e símbolos, tornando-se uma boa opção para codificar dados de texto na maioria dos idiomas ou conjunto de caracteres é usado.
O valor da âncora é um identificador exclusivo para um registro em um arquivo CSV. Diferencia um registro dos outros. O Conector GCSV também usa esse valor para criar o DN (nome diferenciado) que identifica o objeto de espaço do conector relacionado.
Nesta página, as configurações de atributo de âncora são configuradas para cada um dos arquivos CSV listados na página Conectividade.
A imagem a seguir é um exemplo da página Esquema 2 (Configurações de campo de identidade e referência).
A seção a seguir é uma lista das configurações individuais nesta página:
- Usuário
- Âncora do Usuário: o campo no arquivo de Usuários que serve como 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 da Âncora de 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 âncora de grupo: este é o tipo de atributo da âncora selecionada.
- Membro
- ID do Grupo Pai: o campo no arquivo de Membros que possui o mesmo valor (âncora) que o grupo pai no arquivo CSV de Grupos. O primeiro campo no arquivo Membros é usado por padrão.
- ID do Membro: o campo no arquivo de Membros que tem o mesmo valor de âncora que no arquivo CSV de Usuários ou Grupos. O segundo campo no arquivo Membros é selecionado por padrão.
- Tipo de Objeto Membro: o campo que contém um valor de texto "User" ou "Group" para indicar o tipo de objeto do membro. Esse campo só será necessário se o arquivo Membro contiver mais de dois campos. O campo Tipo de Objeto deve conter apenas o valor da cadeia de caracteres "User" ou "Grupo". Se esse campo estiver ausente, o conector pressupõe que os registros do arquivo 'Members' se referem a um membro do objeto do tipo Usuário. O terceiro campo encontrado no arquivo Membros é selecionado por padrão.
Importante
Os nomes dos atributos designados para serem usados como âncoras devem ser exclusivos em todos os esquemas de tipo de objeto. Isso inclui as âncoras especificadas no arquivo Membros do Grupo.
Esta página destina-se a 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 Esquema 3 (Configurações de esquema de atributo de arquivo de usuários).
A seção a seguir lista considerações ao fazer atribuições de tipo de dados de atributo.
O Conector GCSV dá suporte ao uso dos seguintes tipos de dados de seção:
- booliano: um valor que pode ser verdadeiro ou falso.
- binário: um valor 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 usado 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 de âncora do objeto de usuário referenciado.
Importante
Atributos de referência de usuário ou grupo só podem ser usados para se referir a objetos de usuário. Isso não se aplica ao atributo Member de objetos Group, que pode conter referências de usuário ou grupo, desde que o campo de tipo de objeto seja especificado.
O conector dá suporte ao uso de atributos multivalorizados apenas para os seguintes tipos de dados:
- String
Observação
Se o esquema dos objetos Usuário e Grupo ambos tiverem um atributo (não âncora) com o mesmo nome, pode ser que tipos de dados diferentes não possam ser atribuídos entre eles. Ambos devem compartilhar o mesmo tipo de dados.
Esta página destina-se a 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).
As diretrizes oferecidas em Esquema 3 (Configurações de Atributo de Arquivo de Usuários também se aplicam a esta seção. .
Após a execução de uma operação de importação completa inicial, o espaço do conector será semelhante à imagem a seguir:
captura de tela 
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é-processamento e pós-processamento em seus registros de usuários e grupos de identidade.
A imagem a seguir é um exemplo da página Parâmetros globais.
captura de tela 
A seção a seguir lista as configurações individuais nesta página:
- tempo limite de script (minutos): o número de minutos que um script será executado antes de ser anulado automaticamente. O valor padrão dessa 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 de 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 de 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.
O conector GCSV executa cada um dos scripts configurados do PowerShell em sua própria sessão e não dá 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 Executar Perfil executada e pode ser um dos três valores:
Importante
Não há suporte para a criação dinâmica de arquivos CSV antes das operações de importação ou exportação. Todos os arquivos CSV devem estar presentes antes que qualquer perfil de execução seja iniciado.
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.
- Completo – esse valor é fornecido durante operações de Importação Completa ou Exportação Completa.
- Delta – esse 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.
Como os arquivos CSV não armazenam informações em uma estrutura hierárquica, o Conector GCSV não dá suporte a nenhuma configuração de provisionamento hierárquico.
A imagem a seguir é um exemplo da página da Hierarquia de Provisionamento .
Captura de tela 
O Conector GCSV cria um DN (nome distinto) para cada registro de usuário e grupo em seu espaço de conexão, 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.
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 objetos.
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.
Observação
O atributo Member só existirá se Os Grupos forem selecionados e conterá as referências aos objetos mantidos nos arquivos CSV dos membros do grupo.
O Conector GCSV não dá suporte ao uso de âncoras complexas nem configurações de atributo de âncora que diferem dos campos de ID de âncora do arquivo CSV correspondentes.
Para alterar as designações de âncora exibidas nesta página, retorne ao Esquema 2 (Configurações de Âncora).
A imagem a seguir é um exemplo da página Âncoras.
Para que o conector GCSV adicione novos objetos de Usuário ou Grupo aos arquivos CSV correspondentes, um novo Objeto de Espaço do Conector deve ser provisionado para ele.
Seja usando de Provisionamento Declarativo do MIM 2016, ou escrevendo suas próprias extensões de regras de sincronização do MIM , novos objetos do Espaço Conector devem ter um DN construído usando o seguinte formato:
CN=[ANCHOR_VALUE],Object=User|Group,O=CSV
A tabela a seguir fornece detalhes sobre cada um dos valores de componente:
| Componente | Anotações |
|---|---|
| CN=[ANCHOR VALUE] | O Nome Comum (CN) deve ser um valor exclusivo e será gravado no campo de âncora designado do arquivo CSV. |
| Objeto=Usuário/Grupo | Esse componente indica o tipo de objeto desse conector. Dá suporte apenas a "User" ou "Group". |
| O=CSV | O componente raiz comum a todos os objetos de espaço do conector GCSV. |
A imagem a seguir é uma regra de sincronização que demonstra como construir um DN corretamente ao provisionar um novo objeto user em um conector GCSV:
O código a seguir demonstra a lógica de provisionamento equivalente usando Extensões de Regras do Metaverso .
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 corretamente escapado para estar em conformidade com a sintaxe do LDAP.
Importante
Escapar incorretamente do valor da âncora ao construir um DN resultará em um erro de invalid‑dn.
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 de delimitador de campo padrão do conector:
- Valor separado: Vírgula (,)
- Separador de vários valores: Semi-Colon (;)
- Qualificador de texto: aspas duplas (")
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"
Para fornecer vários valores de cadeia de caracteres em um campo de cadeia de caracteres, delimite os valores com o separador multivalorado . O exemplo CSV na seção a seguir mostra como o campo ProxyAddress pode ter 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
Observação
Cadeias de caracteres multivaloradas também oferecem suporte ao uso de valores qualificados de cadeia de caracteres. Valores qualificados de texto podem ser delimitados por separadores multivalorizadores.
Para especificar um valor de referência em um arquivo CSV, preencha seu campo com o valor de âncora do objeto de usuário referenciado. No exemplo CSV da seção a seguir, o campo Gerenciador 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",
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 do PowerShell da seção a seguir demonstra como codificar um valor de cadeia de caracteres em sua cadeia de caracteres codificada em base64 no 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 no Unicode.
public static string ConvertToBase64(string text)
{
byte[] bytes = System.Text.Encoding.UTF8.GetBytes(text);
string encodedText = System.Convert.ToBase64String(bytes);
return encodedText;
}
Arquivos CSV que contêm campos boolianos devem usar o texto True ou False para indicar seu valor. A seção a seguir é uma
EmployeeID,DisplayName,IsActive
E001,"Smith, John",true
E002,"Doe, Jane",true
E003,"Perez, Juan",false
A lista a seguir contém as limitações conhecidas do conector GCSV.
- atributos de referência
- Além do atributo membro do grupo, não há suporte para atributos de referência multivalorizados.
- O valor de referência deve se referir 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.