Conector CSV genérico – Guia de referência passo a passo (versão preliminar)
Este artigo descreve o Conector CSV Genérico. O artigo se aplica aos seguintes produtos:
Para MIM 2016, o Conector está disponível como download do Microsoft Download Center.
Observação
O serviço de 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.
Em um servidor que executa o Servidor de Sincronização do MIM, crie a pasta C:\GCSV e copie os seguintes arquivos CSV encontrados no apêndice A – Arquivos CSV de exemplo nele. Certifique-se de conceder à conta do Serviço de Sincronização do MIM permissões de leitura e gravação para essa pasta.
Copie o seguinte CSV para a pasta C:\GCSV\SCRIPTS :
- Arquivo CSV de usuários de exemplo (Users.csv)
- Arquivo CSV de grupos de exemplo (Groups.csv)
- Exemplo de arquivo CSV de membros (Members.csv)
Observação
Este guia pressupõe que os arquivos CSV estão no seguinte caminho no servidor de Sincronização do MIM: C:\GCSV e que eles são salvos usando os nomes de arquivo indicados. Se você instalá-los em um local diferente ou renomear esses arquivos, será necessário fazer as alterações adequadas redefinindo este guia.
Em um servidor que executa o Servidor de Sincronização do MIM, crie a pasta C:\GCSV\SCRIPTS e copie os scripts de exemplo do PowerShell localizados em Apêndice B – Arquivos de Exemplo do PowerShell nele. Certifique-se de que a conta do serviço de sincronização MIM tenha permissões ExecutePolicy apropriadas do PowerShell para executar os scripts.
Copie os seguintes scripts do PowerShell para a pasta C:\GCSV\SCRIPTS:
- Exemplo de script de pré-importação (Pre-Import.ps1)
- Exemplo de script de pós-importação (Post-Import.ps1)
- Script de pré-exportação de exemplo (Pre-Export.ps1)
- Exemplo de script de pós-exportação (Post-Export.ps1)
Observação
Este guia pressupõe que os arquivos CSV estão no seguinte caminho no servidor de sincronização do MIM: C:\GCSV\SCRIPTS. Se você instalá-los em um local diferente, será necessário fazer as alterações adequadas redefinindo este guia.
Importante
A conta do Serviço de Sincronização MIM requer as permissões ExecutePolicy apropriadas do PowerShell no servidor de Sincronização MIM para executar os scripts de exemplo do PowerShell.
A lista a seguir é uma visão geral de alto nível das etapas descritas neste guia. Para isso, é necessário usar uma conta com a função Administrador de sincronizações MIM 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.
- Avalie os resultados.
Vamos começar!
Para criar um conector CSV genérico, em Gerenciador de serviço de sincronização MIM selecione Agente de gerenciamento e Criar. Selecione o Conector CSV genérico (Microsoft) .
Forneça o nome do conector (por exemplo: CSV genérico) e clique no botão Próximo.
A página Conectividade contém os caminhos de arquivo onde o conector pode localizar os arquivos CSV de usuário, grupos e membros do grupo.
A seguinte imagem é um exemplo da página Conectividade:
Veja a seguir uma lista dos valores que devem ser fornecidos para as configurações nesta página:
| Nome da Configuração | Valor de configuração | Anotações |
|---|---|---|
| Arquivo de usuários | C:\GCSV\USERS. CSV | (O caminho totalmente qualificado e o nome do arquivo usado.) |
| Arquivo de grupos | C:\GCSV\GROUPS.CSV | (O caminho totalmente qualificado e o nome do arquivo usado.) |
| Arquivo de membros | C:\GCSV\MEMBERS.CSV | (O caminho totalmente qualificado e o nome do arquivo usado.) |
Depois de verificar se as configurações correspondem aos valores fornecidos, clique no botão Próximo.
Esta página descreve os recursos do conector. As capacidades do Conector GCSV são fixas e não podem ser modificadas.
A seguinte imagem é um exemplo da página Funcionalidades:
Para obter uma descrição detalhada dessas configurações de funcionalidades, consulte o Conector CSV genérico – Guia de referência técnica.
Após analisar as configurações acima, clique no botão Próximo.
O Conector CSV Genérico (GCSV) utiliza três tipos de separadores (ou delimitadores) para delimitar e analisar campos CSV e seus valores: separadores de valor, separadores multivalorizadose qualificadores de texto . Para obter uma explicação mais detalhada desses tipos de delimitadores, consulte o Conector CSV genérico – Guia de referência técnica
Esta página contém as configurações de valor de caractere para esses delimitadores e o tipo de codificação que foi usado para criar o arquivo como CSV.
A imagem a seguir é um exemplo 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: se essa opção estiver selecionada, ele instrui o conector a ignorar o primeiro registro de cada arquivo CSV como um registro de dados e usá-lo como um registro de cabeçalho (ou seja, que tem os nomes de cada campo).) Se essa opção não estiver selecionada, o conector fornecerá um nome genérico a cada campo (por exemplo, Attribute1, Attribute2 etc.) e usará a primeira linha como um registro de dados.
- 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: Este tipo de separador é usado para delimitar os valores individuais de uma string de múltiplos 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: se um valor de cadeia de caracteres contiver caracteres que de outra forma seriam interpretados como delimitadores (por exemplo, como 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. As aspas duplas (") são o padrão, mas qualquer caractere alfanumérico que pode ser impresso é permitido.
- Codificação de arquivo: Esta configuração indica a codificação usada nos arquivos CSV adicionados na guia 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 exclusivamente o objeto de espaço do conector.
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).
Na tabela a seguir estão os valores individuais que devem ser atribuídos a cada uma das configurações nesta página:
| Nome da Configuração | Valor de configuração |
|---|---|
| Campo de ID de registro de usuário | EmployeeID |
| Tipo de atributo do campo de ID do registro do usuário | Cadeia de caracteres |
| Campo de ID de registro do grupo | GroupID |
| Tipo de atributo do campo de ID do registro do grupo | Cadeia de caracteres |
| ID do grupo pai | ParentID |
| ID do membro | MemberID |
| Tipo de objeto de membro | ObjectType |
Depois de verificar se as configurações correspondem aos valores fornecidos, clique no botão Próximo.
Esta página é usada para atribuir um tipo de dados para cada atributo no esquema do arquivo CSV dos 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).
Na tabela a seguir estão os valores individuais que devem ser atribuídos a cada uma das configurações nesta página:
| Nome da Configuração | Valor de configuração | Anotações |
|---|---|---|
| Atributo do tipo DisplayName | Cadeia de caracteres | Exemplos de cadeias de caracteres qualificadas estão neste campo |
| DisplayName possui múltiplos valores | false | -- |
| Atributo do tipo AccountName | Cadeia de caracteres | -- |
| AccountName tem vários valores | false | -- |
| Tipo de atributo CountryCode | Inteiro | -- |
| CountryCode possui múltiplos valores | false | -- |
| Tipo de atributo do gerenciador | Referência | Contém os valores de atributo de âncora do registro de usuário dos gerentes atribuídos (por exemplo, E001) |
| Manager tem vários valores | false | -- |
| Atributo do tipo ProxyAddresses | Cadeia de caracteres | -- |
| ProxyAddresses tem vários valores | TRUE | Contém exemplos de como delimitar cadeias de caracteres de vários valores |
| Tipo de atributo IsActive | Booleano | -- |
| IsActive possui múltiplos valores | false | -- |
| Tipo de atributo ProfilePic | Binário | -- |
| ProfilePic tem múltiplos valores | false | -- |
Depois de verificar se as configurações correspondem aos valores fornecidos, clique no botão Próximo.
Esta página é usada para atribuir um tipo de dados para cada atributo no esquema do arquivo CSV de 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).
Na tabela a seguir estão os valores individuais que devem ser atribuídos a cada uma das configurações nesta página:
| Nome da Configuração | Valor de configuração | Anotações |
|---|---|---|
| Atributo do tipo DisplayName | Cadeia de caracteres | -- |
| DisplayName tem valores múltiplos | false | Fornece um exemplo de valores de cadeia de caracteres qualificados. |
| Tipo de atributo Description | Cadeia de caracteres | -- |
| Description tem vários valores | false | -- |
| Tipo de atributo Owner | Referência | Fornece um exemplo de valores de referência. |
| Owner possui múltiplos valores | false | -- |
Depois de verificar se as configurações correspondem aos valores fornecidos, clique no botão Próximo.
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. O valor desses parâmetros de entrada oferece uma oportunidade para executar uma ampla variedade de ações de pré e pós-processamento em seus registros de usuário e grupo de identidade.
A imagem a seguir é um exemplo da página de Parâmetros Globais .
captura de tela 
Na tabela a seguir estão os valores individuais que devem ser atribuídos a cada uma das configurações nesta página:
| Nome da Configuração | Valor de configuração | Anotações |
|---|---|---|
| Arquivo de pré-importação | C:\GCSV\SCRIPTS\PRE-IMPORT.CSV | Esse script é executado antes de uma importação completa |
| Arquivo pós-importação | C:\GCSV\SCRIPTS\POST-IMPORT.CSV | Esse script é executado após uma importação completa |
| Arquivo de Pré-Exportação | C:\GCSV\SCRIPTS\PRE-EXPORT.CSV | Esse script é executado antes de uma exportação completa ou exportação delta. |
| Arquivo de pós-exportação | C:\GCSV\SCRIPTS\POST-EXPORT.CSV | Esse script é executado antes de uma exportação completa ou exportação (delta) |
Depois de verificar se as configurações correspondem aos valores fornecidos, clique no botão Próximo.
O Conector GCSV executa cada script do PowerShell configurado em sua própria sessão e não fornece suporte para passar variáveis entre a execução de scripts.
Além disso, o Conector GCSV executa o script do PowerShell dentro dos arquivos, não como um cmdlet. Isso significa que os parâmetros de entrada não podem ser passados para scripts adicionando-os ao final de suas instruções de caminho. Fazer isso faz com que a execução do script falhe.
Importante
O Conector GCSV não dá suporte ao uso da passagem de parâmetros de entrada na execução dos scripts do PowerShell.
Se uma execução de script de pré-importação ou pré-exportação gerar uma exceção, para impedir a importação ou exportação de registros de usuário ou grupo processados incorretamente, o Conector GCSV anulará e interromperá a execução de todo o perfil de execução.
Da mesma forma, se uma operação pós-importação ou pós-exportação encontrar uma exceção, isso fará com que o status da operação falhe.
Os erros encontrados durante a execução do script do PowerShell serão registrados no log *Evento *do servidor de Sincronização do MIM.
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.
A variável de entrada OperationType terá o valor Completo ou Delta para mostrar o tipo de operação (por exemplo, Importação Completa, Importação Delta, Exportação Completa, (Delta) que está em execução com o script. Esse valor permite que os scripts verifiquem se estão em execução em um contexto de importação/exportação completo ou delta e executam suas tarefas pré ou pós-processamento adequadamente.
Como os arquivos CSV não armazenam informações em uma estrutura hierárquica; O conector CSV genérico não dá suporte a nenhuma configuração de provisionamento hierárquico.
A imagem a seguir é um exemplo da página de Hierarquia de Provisionamento .
Captura de tela 
Depois de verificar se as configurações correspondem aos valores fornecidos, clique no botão Próximo.
O Conector CSV genérico 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.
Depois de verificar se as configurações correspondem aos valores fornecidos, clique no botão Próximo.
O conector CSV genérico requer que pelo menos o tipo de objeto User seja especificado. A escolha do tipo de objeto Group é opcional.
A imagem a seguir é um exemplo da página Tipos de Objeto.
Depois de verificar se as configurações correspondem aos valores fornecidos, clique no botão Próximo.
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.
Depois de verificar se as configurações correspondem aos valores fornecidos, clique no botão Próximo.
Observação
Atributos de âncora são sempre necessários para que o Conector GCSV opere corretamente.
O Conector CSV genérico não oferece suporte ao uso de âncoras complexas ou configurações de atributos de âncora que sejam diferentes da designação do campo de ID de âncora do arquivo CSV do objeto correspondente. Por isso, os campos de seleção de âncora estão bloqueados. Para fazer uma alteração na designação de atributo de âncora, retorne à página Esquema 2 (Configurações de Campo de Identidade e Referência).
A imagem a seguir é um exemplo da página Âncoras.
Após analisar as configurações padrão na página, clique no botão Próximo.
Este guia não usará nenhuma configuração de filtro de conectores. Esta seção está aqui para fornecer continuidade no guia.
A imagem a seguir é um exemplo da página Filtros de conector.
Após analisar as configurações padrão na página, clique no botão Próximo.
Este guia não usará nenhuma configuração de regras de junção e projeção. Esta seção está aqui para fornecer continuidade no guia.
A imagem a seguir é um exemplo da página Regras de junção e projeção.
Após analisar as configurações padrão na página, clique no botão Próximo.
Este guia não usará nenhuma configuração de regras de fluxo de atributo. Esta seção está aqui para fornecer continuidade no guia.
A imagem a seguir é um exemplo da página Fluxo de atributos.
captura de tela 
Depois de verificar se as configurações correspondem aos valores padrão, clique no botão Próximo.
Este guia não alterará as configurações de desprovisionamento padrão deste conector. Esta seção está aqui para fornecer continuidade no guia.
A imagem a seguir é um exemplo da página Desprovisionamento.
Depois de verificar se as configurações correspondem aos valores padrão, clique no botão Próximo.
Um perfil de execução de importação completa é necessário para importar dados de identidade de usuário e grupo dos registros CSV para objetos do Connector Space.
Use as seguintes etapas para criar um novo Perfil de execução de importação completa:
- Volte para Synchronization Service Manager.
- Selecione o agente de gerenciamento do GCSV.
- Clique com o botão direito do mouse nele e escolha Configurar Perfis de Execução.
- Clique em Novo Perfil.
A janela Configurar Perfil de Execução será exibida.
Na página Nome do perfil, insira o nome Importação completa
A imagem a seguir é um exemplo da página Perfil.
Depois de verificar se as configurações correspondem aos valores fornecidos, clique no botão Próximo.
Na página Etapa de configuração, selecione o Tipo: Importação completa.
A filtragem no Conector GCSV opera da mesma forma que em qualquer outro conector ECMA.
A imagem a seguir é um exemplo da página Filtro de conector.
Depois de verificar se as configurações correspondem aos valores fornecidos, clique no botão Próximo.
Na página Tipo de Configuração do Agente de Gerenciamento, verifique se a partição O=CSV está selecionada.
Deixe o restante das configurações em seus valores padrão. Clicar no botão Concluir criará o Perfil de execução.
Esta seção detalha as etapas necessárias para validar os resultados da criação de um novo Conector GCSV e a importação dos registros usuário e grupo dos arquivos CSV de exemplo.
Após criar o perfil de execução, siga as etapas a seguir e execute este novo perfil de execução de importação completa:
- Volte para Synchronization Service Manager.
- Selecione o agente de gerenciamento do GCSV.
- Clique com o botão direito do mouse nele e escolha Executar.
- Selecione Importação completa e clique em OK.
Deve haver cinco (5) adições com base no conteúdo dos arquivos CSV de exemplo:
A imagem a seguir é um exemplo dos resultados da importação com êxito do conteúdo dos arquivos CSV de exemplo:
Após criar o perfil de execução, siga as etapas a seguir e execute este novo perfil de execução de importação completa:
- Volte para Synchronization Service Manager.
- Selecione o agente de gerenciamento do conector GCSV .
- Clique com o botão direito do mouse e escolha Pesquisar espaço do conector.
- Deixe o escopo com seu valor padrão de Subárvore e clique no botão Pesquisar.
A imagem a seguir é um exemplo da janela Pesquisar espaço do conector que será exibida.
captura de tela 
Selecione um dos objetos de usuário para inspeção. A imagem a seguir é um exemplo de um objeto no espaço de conectores GCSV de um usuário.
O exame do campo DisplayName mostra como uma cadeia de caracteres qualificada foi analisada corretamente.
Clicar no botão dentro da entrada ProxyAddresses revela que a cadeia de caracteres multivalorizada também foi corretamente analisada em valores individuais:
Selecionando um dos objetos do grupo para inspeção. A imagem a seguir é um exemplo de um objeto no espaço de conectores GCSV de um grupo.
Clicar no botão dentro da entrada Membro revela como os registros associados ao arquivo de grupo de registros dentro do arquivo Membros foram carregados corretamente como membros:
Os scripts de exemplo do PowerShell fornecidos neste guia foram projetados para adicionar uma entrada CSV a um log central para demonstrar sua execução bem-sucedida.
O local padrão desse log é C:\GCSV\PS_Run_Ledger.csv.
Abrir o registro revela:
"DateTime","Stage","Name","Type","Description"
"3/17/2024 1:05:44 PM","Pre","Import","Full","The Pre-Import PowerShell script was executed successfully."
"3/17/2024 1:05:46 PM","Pre","Import","Full","The Post-Import PowerShell script was executed successfully."
Esses dois registros indicam que os scripts pré-importação e pós-importação do PowerShell foram executados com êxito. Observe que o campo Tipo indica que esses scripts do PowerShell foram executados durante uma Importação Completa. Ele obtém esses valores do parâmetro de entrada OperationType PowerShell que indica se o script foi executado durante uma operação Completa ou Delta.
As seções a seguir contêm os Arquivos CSV usados neste guia.
Na configuração do conector, este guia pressupõe o nome do arquivo USERS.CSV.
EmployeeID,DisplayName,AccountName,CountryCode,Manager,ProxyAddresses,IsActive,ProfilePic
E001,"Smith, John",JS001,1,,SMTP:john.smith@contoso.com;smtp:js001@contoso.com,True,SgBTADAAMAAxAA==
E002,"Doe, Jane",JD003,1,E001,SMTP:jane.doe@contoso.com;smtp:jd002@contoso.com,True,SgBEADAAMAAyAA==
E003,"Perez, Juan",JP003,1,E001,SMTP:juan.perez@contoso.com;smtp:jp003@contoso.com,False,SgBEADAAMAAyAA==
Na configuração do conector, este guia pressupõe o nome do arquivo GROUPS.CSV.
GroupID,DisplayName,Description,Owner
G001,Test Group (G001),"This group is for teams A, B, and C",E002
G002,Test Group (G002),"This group is for teams D, E, and F",E003
Na configuração do conector, este guia pressupõe o nome do arquivo MEMBERS.CSV.
ParentID,MemberID,ObjectType
G001,E001,USER
G001,E002,USER
G001,E003,USER
G002,E001,USER
G002,E002,USER
G002,E003,USER
G002,G001,GROUP
G003,E001,USER
G003,E002,USER
G003,E003,USER
G003,G001,GROUP
Contido nesse apêndice está o conjunto de scripts de exemplo do PowerShell usados neste guia. As seções a seguir detalham algumas das considerações que devem ser feitas quando
Importante
qualquer uso de comandos write-hostnos scripts do PowerShell resultará na falha da execução do script.
Na configuração do conector, este guia pressupõe o nome do arquivo PRE-IMPORT.PS1.
param ([string]$OperationType)
[string]$stage = "Pre"
[string]$operation = "Import"
[string]$filePath = "C:\GCSV\PS_Run_Ledger.csv"
# Create a new record
$record = [PSCustomObject]@{
"DateTime" = (Get-Date).ToString()
"Stage" = $stage
"Type" = $OperationType
"Name" = $operation
"Description" = "The $stage-$operation PowerShell script was successfully executed before a $OperationType-$operation."
}
$record | Export-Csv -Path $FilePath -NoTypeInformation -Append
Na configuração do conector, este guia assume que o nome do arquivo é POST-IMPORT.PS1.
param ([string]$OperationType)
[string]$stage = "Post"
[string]$operation = "Import"
[string]$filePath = "C:\GCSV\PS_Run_Ledger.csv"
# Create a new record
$record = [PSCustomObject]@{
"DateTime" = (Get-Date).ToString()
"Stage" = $stage
"Type" = $OperationType
"Name" = $operation
"Description" = "The $stage-$operation PowerShell script was successfully executed after a $OperationType-$operation."
}
$record | Export-Csv -Path $FilePath -NoTypeInformation -Append
Na configuração do conector, este guia pressupõe o nome do arquivo PRE-EXPORT.PS1.
param ([string]$OperationType)
[string]$stage = "Pre"
[string]$operation = "Export"
[string]$filePath = "C:\GCSV\PS_Run_Ledger.csv"
# Create a new record
$record = [PSCustomObject]@{
"DateTime" = (Get-Date).ToString()
"Stage" = $stage
"Type" = $OperationType
"Name" = $operation
"Description" = "The $stage-$operation PowerShell script was successfully executed before a $OperationType-$operation."
}
$record | Export-Csv -Path $FilePath -NoTypeInformation -Append
Na configuração do conector, este guia assume que o nome do arquivo é POST-EXPORT.PS1.
param ([string]$OperationType)
[string]$stage = "Post"
[string]$operation = "Export"
[string]$filePath = "C:\GCSV\PS_Run_Ledger.csv"
# Create a new record
$record = [PSCustomObject]@{
"DateTime" = (Get-Date).ToString()
"Stage" = $stage
"Type" = $OperationType
"Name" = $operation
"Description" = "The $stage-$operation PowerShell script was successfully executed after a $OperationType-$operation."
}
$record | Export-Csv -Path $FilePath -NoTypeInformation -Append