Atualizar em massa as propriedades de perfil de usuário personalizado do SharePoint Online

Como parte da versão do modelo de objeto do lado do cliente (CSOM) (4622.1208 ou posterior), o Microsoft Office SharePoint Online tem a capacidade de importar em massa propriedades de perfil de usuário personalizadas. Antes desta versão, sua única opção era aproveitar as operações CSOM do perfil de usuário para atualizar propriedades específicas para perfis de usuário individuais. No entanto, essa abordagem é ineficiente e muito demorada (especialmente ao lidar com milhares de perfis)

Muitas empresas precisam replicar atributos personalizados para o serviço de perfil de usuário do Microsoft Office SharePoint Online, portanto, uma API em massa de perfil de usuário mais eficaz foi lançada, o UserProfile.BatchUpdate.API.

Visão geral do processo de atualização de perfil de usuário em massa

A lista a seguir descreve o fluxo do processo de atualização de perfil de usuário em massa:

1. Os atributos de usuário são sincronizados do Active Directory corporativo com o Azure Active Directory (Azure AD). Você pode selecionar quais atributos são replicados no local e no Azure.
2. Um conjunto padronizado de atributos é replicado do Azure Active Directory para o Repositório de Perfis de Usuário do SharePoint Online no Office 365. Ao contrário do Microsoft Office SharePoint Online local, esses atributos não podem ser personalizados.
3. Uma ferramenta de sincronização personalizada aproveita as APIs de atualização em massa. Essa ferramenta carrega um arquivo JSON para o locatário do Office 365 e enfileira o processo de importação. Essa ferramenta pode ser implementada usando o código gerenciado (.NET) ou como um script do PowerShell usando as APIs CSOM.
4. Um sistema LOB (linha de negócios), ou qualquer sistema externo, é a origem das informações no arquivo JSON. Isso também pode ser uma combinação de dados do Active Directory e de qualquer sistema externo. Observe que, de uma perspectiva de API, o sistema LOB pode até mesmo ser um farm do Microsoft Office SharePoint Online local.
5. Um trabalho de timer do lado do servidor integrado em execução no SharePoint Online verifica se há solicitações de importação na fila e executa a operação de importação real com base nas chamadas à API e nas informações no arquivo JSON fornecido.
6. As informações estendidas de perfil de usuário estão disponíveis em perfis de usuário e podem ser usadas para qualquer funcionalidade personalizada ou fora da caixa no SharePoint Online.

Veja a seguir um breve vídeo que demonstra como usar a API CSOM UserProfile.BatchUpdate.API de código gerenciado (.NET) e do PowerShell.

Processo de importação de propriedade de perfil de usuário.

A seguir está o processo completo:

1. Crie ou sincronize usuários em um locatário do Office 365 ou no Azure Active Directory associado a ele.
   • Quando os usuários são sincronizados com o Azure Active Directory, ele também sincroniza um conjunto padronizado de atributos com o serviço de perfil de usuário do SharePoint Online.
2. Crie as propriedades personalizadas necessárias no serviço de perfil de usuário.
   • Como não há APIs remotas para criar propriedades personalizadas no serviço de perfil de usuário, essa etapa deve ser executada manualmente para cada um dos locatários em que as propriedades de perfil de usuário personalizadas são necessárias (isso só precisa ser feito uma vez por locatário).
   • Somente as propriedades de perfil de usuário que não têm permissão para serem editadas pelos usuários finais podem ser importadas. Tentar importar uma propriedade de objeto JSON para uma propriedade de perfil de usuário marcada como "editável por usuários finais" resulta em uma exceção quando a API CSOM é chamada.
3. Crie e carregue o arquivo JSON para o locatário do Office 365.
   • Você deve carregar o arquivo de dados JSON que contém as informações a serem atualizadas para o locatário do Office 365.
   • No caso de qualquer exceção durante o processo de importação, o Microsoft Office SharePoint Online fornece informações de log adicionais salvas na mesma biblioteca de documentos em que o arquivo existia em uma nova subpasta.
   • A limpeza dos arquivos de log e arquivos JSON não é feita automaticamente e é responsabilidade da solução personalizada usando a API. Você deve considerar o ciclo de vida desses arquivos em sua implementação. Esses arquivos são armazenados em bibliotecas de documentos e, portanto, consomem uma parte do armazenamento atribuído para o conjunto de sites.
4. Chame a API de Importação de UPA em massa para enfileirar o trabalho de importação.
   • Use a API CSOM para enfileirar processo de importação. Isso pode ser feito executando o código CSOM usando o código gerenciado (.NET) ou o PowerShell.
   • O método para enfileirar o trabalho requer informações de mapeamento de propriedade e o local do arquivo de dados. Esse método é executado rapidamente porque enfileira o processo de importação real, que posteriormente é executado como parte de um processo de back-end no Microsoft Office SharePoint Online.
5. Verifique o status do trabalho de importação.
   • Você também pode usar APIs remotas para verificar o status de um trabalho de importação específico ou todos os trabalhos de importação recentes. Para poder verificar o status de uma chamada específica, você deve armazenar o identificador de trabalho exclusivo recebido como um valor retornado quando o trabalho é enfileirado.

Criar e carregar arquivo JSON

O processo de importação usa um arquivo JSON que contém as propriedades e seus valores. A seguir está a estrutura esperada desse arquivo:

{
   "value": [
     {
       "<IdName>": "<UserIdValue_1>",
       "<AttributeName_1>": "<User1_AttributeValue_1>",
       "<AttributeName_2>": "<User1_AttributeValue_2>",
     },
     {
       "<IdName>": "<UserIdValue_2>",
       "<AttributeName_1>": "<User2_AttributeValue_1>",
       "<AttributeName_2>": "<User2_AttributeValue_2>",
     },
     {
       "<IdName>": "<UserIdValue_n>",
       "<AttributeName_1>": "<Usern_AttributeValue_1>",
       "<AttributeName_2>": "<Usern_AttributeValue_2>",
     }
   ]
}

Exemplo

A seguir está um arquivo de exemplo simples que usa o formato no exemplo anterior. Neste exemplo, a resolução de identidade baseia-se na propriedade IdName e há duas propriedades que estão sendo atualizadas chamadas City e Office. O arquivo contém informações para quatro contas diferentes dentro do locatário. Os nomes de propriedade usados neste arquivo de origem não são necessariamente os mesmos que os nomes usados no serviço de perfil de usuário do SharePoint Online porque fornecemos o mapeamento de propriedade correto em nosso código. 

{
  "value": [
    {
      "IdName": "vesaj@contoso.com",
      "City": "Helsinki",
      "Office": "Viper"
    },
    {
      "IdName": "bjansen@contoso.com",
      "City": "Brussels",
      "Office": "Beetle"
    },
    {
      "IdName": "unknowperson@contoso.com",
      "City": "None",
      "Office": ""
    },
    {
      "IdName": "erwin@contoso.com",
      "City": "Stockholm",
      "Office": "Elite"
    }
  ]
}

Restrições de arquivo de dados de origem

A seguir estão as restrições em arquivos de dados de origem individuais:

• Tamanho máximo do arquivo: 2 GB
• Número máximo de propriedades: 500.000
• Backslashes () em valores de propriedade precisam escapar, preparando-se com outro backslash
• O arquivo de origem deve ser carregado no mesmo locatário do Microsoft Office SharePoint Online em que o processo é iniciado.

Enfileirar o processo de importação

Você pode enfileirar a API CSOM para o processo de importação em massa chamando o método QueueImportProfileProperties localizado no objeto Office365Tenant. Essa é uma chamada assíncrona, pois não baixa os dados de origem nem executa a importação; ele simplesmente adiciona um item de trabalho à fila para fazer isso mais tarde.

A seguir está a assinatura completa do método:

public ClientResult<Guid> QueueImportProfileProperties(
                          ImportProfilePropertiesUserIdType idType,
                          string sourceDataIdProperty,
                          IDictionary<string, string> propertyMap,
                          string sourceUri);

Parâmetros

• idType: ImportProfilePropertiesUserIdType

  O tipo de ID a ser usado ao pesquisar o perfil do usuário. Os valores possíveis são Email, CloudIde PrincipalName. Observe que, independentemente do tipo, o usuário já deve existir no serviço de perfil de usuário para que a importação funcione. Recomendamos usar o valor CloudId para garantir a exclusividade.

  Mapeamento de propriedade entre o tipo de ID e a propriedade do Azure Active Directory:

  Tipo de ID de importação em massa upa	Atributo do Microsoft Azure Active Directory
  CloudId	ObjectID
  PrincipalName	userPrincipalName
  Email	email

• sourceDataIdProperty: System.String

  O nome da propriedade ID nos dados de origem. O valor da propriedade dos dados de origem é usado para pesquisar o usuário. A propriedade de serviço de perfil de usuário usada para a pesquisa depende do valor de idType.

• propertyMap: IDictionary<string, string>

  Um mapa do nome da propriedade de origem para o nome da propriedade do serviço de perfil de usuário. Observe que as propriedades do serviço de perfil de usuário já devem existir. A chave é o nome da propriedade usada no arquivo de origem; o valor é o nome da propriedade usado no serviço de perfil de usuário.

• sourceUri: System.String

  O URI do arquivo de dados de origem a ser importado. O arquivo não deve ser movido ou excluído imediatamente, pois pode não ser baixado por algum tempo.

Valor de retorno

Um GUID que identifica o trabalho de importação que foi enfileirado.

Exemplo

A seguir está um exemplo que usa C# para iniciar o processo usando o arquivo de entrada de exemplo anterior:

// Create an instance of the Office 365 Tenant object. Loading this object is not technically needed for this operation.
Office365Tenant tenant = new Office365Tenant(ctx);
ctx.Load(tenant);
ctx.ExecuteQuery();

// Type of user identifier ["PrincipalName", "Email", "CloudId"] in the
// user profile service. In this case, we use Email as the identifier at the UPA storage
ImportProfilePropertiesUserIdType userIdType =
      ImportProfilePropertiesUserIdType.Email;

// Name of the user identifier property within the JSON file
var userLookupKey = "IdName";

var propertyMap = new System.Collections.Generic.Dictionary<string, string>();

// The key is the property in the JSON file
// The value is the user profile property Name in the user profile service
// Notice that we have 2 custom properties in UPA called 'City' and 'OfficeCode'
propertyMap.Add("City", "City");
propertyMap.Add("Office", "OfficeCode");

// Returns a GUID that can be used to check the status of the execution and the end results
var workItemId = tenant.QueueImportProfileProperties(
      userIdType, userLookupKey, propertyMap, fileUrl
      );

ctx.ExecuteQuery();

Verificar o status de um trabalho de importação

Você pode verificar o status dos trabalhos de importação do serviço de perfil de usuário usando as APIs CSOM. Há dois métodos para isso no objeto Tenant:

• Para verificar o status de um trabalho de importação individual, use método GetImportProfilePropertyJob.
• Para verificar o status de todos os trabalhos de importação, use o método GetImportProfilePropertyJobs usuário.

Trabalho de importação individual

Você pode verificar o status de um trabalho de importação individual usando o método GetImportProfilePropertyJob localizado no objeto Office365Tenant. Você deve ter o identificador exclusivo de um trabalho de importação específico fornecido como um parâmetro para esse método.

A seguir está a assinatura completa do método:

public ImportProfilePropertiesJobInfo GetImportProfilePropertyJob(Guid jobId);

Parâmetros

• jobID: System.Guid

  A ID do trabalho para o qual obter o status de alto nível.

Valor de retorno

Um ImportProfilePropertiesJobStatus objeto com informações de status de alto nível sobre o trabalho especificado.

Exemplo

A seguir está um exemplo que usa para recuperar o status de um trabalho de importação C# específico usando um identificador armazenado:

// Check the status of a specific request based on the job id received when we queued the job
Office365Tenant tenant = new Office365Tenant(ctx);
var job = tenant.GetImportProfilePropertyJob(workItemId);
ctx.Load(job);
ctx.ExecuteQuery();

Todos os trabalhos de importação

Você pode verificar o status de todos os trabalhos de importação usando o método GetImportProfilePropertyJobs localizado no objeto Office365Tenant.

A seguir está a assinatura completa do método:

public ImportProfilePropertiesJobStatusCollection GetImportProfilePropertyJobs(); 

Parâmetros

Um ImportProfilePropertiesJobInfo retornado com as informações de status de importação tem as seguintes propriedades. 

• JobId: System.Guid

  A ID do trabalho de importação.

• State: ImportProfilePropertiesJobState

  Uma enumeração com os seguintes valores:

  • Desconhecido - Não é possível determinar o estado do trabalho.
  • Enviado - O trabalho foi enviado para o sistema.
  • Processamento - O trabalho está sendo processado.
  • Enfileirado - O trabalho passou na validação e está na fila para importação para UPA.
  • Êxito - O trabalho foi concluído sem erros.
  • Erro - O trabalho foi concluído com erros.

• SourceUri: System.String

  O URI para o arquivo de fonte de dados.

• Error: ImportProfilePropertiesJobError

  Uma enumeração que representa o possível erro:

  • NoError - Nenhum erro encontrado.
  • InternalError - O erro foi causado por uma falha no serviço.
  • DataFileNotExist - Não foi possível encontrar o arquivo de fonte de dados.
  • DataFileNotInTenant - O arquivo de fonte de dados não pertença ao mesmo locatário.
  • DataFileTooBig - O tamanho do arquivo de dados era muito grande.
  • InvalidDataFile - O arquivo de fonte de dados não foi aprovado na validação (pode haver detalhes adicionais no arquivo de log).
  • ImportCompleteWithError - Os dados foram importados, mas houve um erro.

• ErrorMessage: System.String

  A mensagem de erro.

• LogFileUri: System.String

  O URI para a pasta em que os logs foram gravados.

Valor de retorno

Um objeto ImportProfilePropertiesJobStatusCollection, que é uma coleção de objetos ImportProfilePropertiesJobStatus com informações de status de alto nível sobre cada um dos trabalhos.

Exemplo

A seguir está um exemplo que usa para obter o status de todos os trabalhos de importação C# atualmente salvos no locatário. Eles já podem ser trabalhos processados ou enfileirados:

// Load all import jobs – old and queued ones
Office365Tenant tenant = new Office365Tenant(ctx);
var jobs = tenant.GetImportProfilePropertyJobs();
ctx.Load(jobs);
ctx.ExecuteQuery();
foreach (var item in jobs)
{
   // Check whatever properties needed
   var state = item.State;
}

Chamar a API de importação do PowerShell

Você pode aproveitar a API de importação em massa do serviço de perfil de usuário usando o PowerShell. Isso significa que você usa o código CSOM diretamente em um script do PowerShell usando os parâmetros necessários. Isso requer que o pacote redistribuível CSOM atualizado tenha sido instalado no computador em que o script é executado.

Usando o PowerShell, você não precisa compilar seu código no Visual Studio, que pode ser um modelo mais adequado para alguns clientes.

Como alternativa, você pode usar o PowerShell PnP que permitirá que você use a API de importação em massa do serviço de perfil de usuário sem a necessidade de bibliotecas adicionais instaladas em seu sistema.

Script do PowerShell de exemplo usando bibliotecas CSOM

A seguir, um exemplo de script do PowerShell que executa as mesmas operações que o código anterior:

# Get needed information from the end user
$adminUrl = Read-Host -Prompt 'Enter the admin URL of your tenant'
$userName = Read-Host -Prompt 'Enter your user name'
$pwd = Read-Host -Prompt 'Enter your password' -AsSecureString
$importFileUrl = Read-Host -Prompt 'Enter the URL to the file located in your tenant'

# Get instances to the Office 365 tenant using CSOM
$uri = New-Object System.Uri -ArgumentList $adminUrl
$context = New-Object Microsoft.SharePoint.Client.ClientContext($uri)

$context.Credentials = New-Object Microsoft.SharePoint.Client.SharePointOnlineCredentials($userName, $pwd)
$o365 = New-Object Microsoft.Online.SharePoint.TenantManagement.Office365Tenant($context)
$context.Load($o365)

# Type of user identifier ["Email", "CloudId", "PrincipalName"] in the user profile service
$userIdType=[Microsoft.Online.SharePoint.TenantManagement.ImportProfilePropertiesUserIdType]::Email

# Name of user identifier property in the JSON
$userLookupKey="idName"

# Create property mapping between the source file property name and the Office 365 property name
# Notice that we have here 2 custom properties in UPA called 'City' and 'OfficeCode'
$propertyMap = New-Object -type 'System.Collections.Generic.Dictionary[String,String]'
$propertyMap.Add("City", "City")
$propertyMap.Add("Office", "OfficeCode")

# Call to queue UPA property import
$workItemId = $o365.QueueImportProfileProperties($userIdType, $userLookupKey, $propertyMap, $importFileUrl);

# Execute the CSOM command for queuing the import job
$context.ExecuteQuery();

# Output the unique identifier of the job
Write-Host "Import job created with the following identifier:" $workItemId.Value

Atualizando o perfil de usuário do Microsoft Office SharePoint Online usando o PnP PowerShell

Para sincronizar propriedades de perfil de usuário do Azure Active Directory com perfis de usuário do Microsoft Office SharePoint Online, você pode aproveitar o cmdlet Sync-PnPSharePointUserProfilesFromAzureActiveDirectory do PnP PowerShell.

Como alternativa, se você quiser sincronizar propriedades de perfil de usuário de outra fonte, poderá usar New-PnPUPABulkImportJob.

Para verificar o status de processamento de um trabalho de importação em massa, você pode usar Get-PnPUPABulkImportStatus.

Tratar exceções

Há dois níveis de validação quando essa API é usada. Quando você enfileira o processo de importação com o CSOM, há um nível inicial de validação dos valores fornecidos. Isso inclui a confirmação de que as propriedades de mapeamento fornecidas existem no serviço de perfil de usuário e que essas propriedades não são editáveis pelo usuário final. Quando a API de fila é chamada, apenas um nível inicial de validação é aplicado e a validação final das informações fornecidas é executada quando o trabalho de importação é realmente executado.

Se houver exceções durante a execução real do trabalho de importação, um arquivo de log com detalhes adicionais será gerado na mesma biblioteca de documentos em que o arquivo de importação estava localizado. Arquivos de log para trabalhos de importação específicos são salvos em subpastas nomeadas usando o identificador exclusivo do trabalho de importação específico.

A seguir está um exemplo dos resultados da execução de um trabalho de importação. Na imagem a seguir, você pode ver duas subpastas para duas execuções diferentes criadas na biblioteca de documentos em que o arquivo de importação está armazenado.

O arquivo de log real é salvo na subpasta e você pode baixá-lo do Office 365 para análise detalhada.

Exceções comuns

A tabela a seguir contém exceções típicas que você pode encontrar ao começar a usar a API em massa do serviço de perfil de usuário.

Perguntas frequentes

Posso executar o código usando permissões somente de aplicativo/suplemento?

Sim, a importação real do arquivo não ocorre de forma síncrona com a identidade do chamador, portanto, isso funciona com contexto somente de aplicativo sem problemas.

Para usar um contexto somente de aplicativo com o modelo de suplemento do SharePoint, você precisa registrar uma ID do cliente e um segredo para poder executar as APIs seguindo estas diretrizes. Além disso, ao registrar o suplemento do SharePoint, você precisará conceder as permissões usando o seguinte snippet XML:

<AppPermissionRequests AllowAppOnlyPolicy="true">
  <AppPermissionRequest Scope="http://sharepoint/content/tenant" Right="FullControl" />
  <AppPermissionRequest Scope="http://sharepoint/social/tenant" Right="FullControl" />
</AppPermissionRequests>

Para usar somente aplicativo com um aplicativo registrado no Azure Active Directory , você precisa registrar o aplicativo, fornecer um certificado X.509 para autenticação, que é um requisito para autenticação somente de aplicativo do SharePoint Online no Azure Active Directory e conceder os seguintes escopos de permissões do SharePoint Online para o Aplicativo: Sites.FullControl.All e User.ReadWrite.All.

Essa API está atualizando propriedades no serviço de perfil de usuário, mas como eu criaria essas propriedades no locatário?

Não há nenhuma API remota para criar propriedades de perfil de usuário personalizadas programaticamente, portanto, essa é uma operação manual que precisa ser concluída uma vez por determinado locatário. Para obter instruções sobre como criar essas propriedades personalizadas, consulte Adicionar e editar propriedades de perfil de usuário no SharePoint Online.

Essa funcionalidade está disponível no Microsoft Office SharePoint Online local?

Infelizmente, essa funcionalidade é atualmente apenas para o SharePoint Online. No Microsoft Office SharePoint Online local, essa funcionalidade seria útil, mas não tão crítica, pois você pode modificar o mapeamento de atributo no aplicativo de serviço de perfil de usuário local. Você também pode aproveitar a importação de atributos de perfil de usuário usando o BCS (Serviço corporativo de conectividade) no Microsoft Office SharePoint Online 2013. No entanto, essa opção não está disponível no Microsoft Office SharePoint Online 2016, o que significa que, para o Microsoft Office SharePoint Online 2016, a única opção atualmente é implementar personalizações que aproveitam os serviços Web de perfil de usuário.

Posso usar essa API para sincronizar valores de propriedade de perfil de usuário de meus farms do SharePoint locais com o SharePoint Online?

Sim, o Microsoft Office SharePoint Online local pode ser usado como qualquer outro sistema de origem. Você deve exportar os valores de perfil de usuário do Microsoft Office SharePoint Online local para o formato de arquivo JSON e, em seguida, o processo seria exatamente o mesmo que importar valores de qualquer outro sistema.

Posso importar propriedades de vários valores baseadas em cadeia de caracteres?

Não, atualmente não há suporte para isso nesta API.

Quais permissões são necessárias para executar esta API?

Você deve ter permissões de Administrador Global no momento, a menos que use um contexto de autenticação somente de aplicativo. O Administrador do Microsoft Office SharePoint Online não é suficiente.

Posso importar propriedades baseadas em taxonomia?

Não, atualmente não há suporte para isso nesta API.

E se eu definir um mapeamento no código que não é usado ou tem propriedades no arquivo JSON que não estão mapeadas?

Se o código/script definir um mapeamento que não é usado ou se o arquivo de dados não contiver propriedades para esse mapeamento, a execução continuará sem exceções e a importação será aplicada com base nas propriedades mapeadas. No entanto, se você tiver uma propriedade no arquivo JSON que não esteja mapeada, o processo de importação será anulado e os detalhes da exceção serão fornecidos no arquivo de log para a execução específica do trabalho.

E se eu precisar atualizar propriedades personalizadas que estão além das limitações de tamanho dessa API em massa (ou seja, maior que um arquivo de 2 GB ou 500.000 propriedades)?

Você deve agrupar seus trabalhos adequadamente disparando vários trabalhos em sequência (ou seja, concluindo um trabalho por vez com o limite máximo nessa API). Você deve esperar que essas importações de largura de banda alta levarão muito tempo para serem concluídas. Além disso, você deve otimizar os trabalhos de importação somente para alterações delta em propriedades de perfil personalizado em vez de importar um conjunto completo de valores em todos os trabalhos.

Quais atributos do Azure Active Directory estão sendo sincronizados com os perfis de usuário do SharePoint Online por padrão?

Consulte a tabela a seguir para obter a lista oficial de atributos sincronizados e seu mapeamento entre o Azure Active Directory e o serviço de perfil de usuário do SharePoint Online.

Confira também

• Soluções de perfil de usuário do SharePoint