Solucionar problemas de API de provisionamento de entrada

Introdução

Este documento aborda erros e problemas frequentemente encontrados na API de provisionamento de entrada e como solucioná-los.

Cenários de solução de problemas

Formato de dados inválido

Descrição do problema

• Você está recebendo a mensagem de erro Invalid Data Format com o código de resposta HTTP 400 (Solicitação inválida).

Causas prováveis

1. Você está enviando uma solicitação em massa válida de acordo com as especificações de provisionamento /bulkUpload da API, mas não configurou o "Content-Type" do Cabeçalho de Solicitação HTTP como application/scim+json.
2. Você está enviando uma solicitação em massa que não está em conformidade com as especificações de provisionamento /bulkUpload da API.

Resolução:

1. Certifique-se de que o valor da configuração do Content-Type do cabeçalho da Solicitação HTTP esteja configurado como application/scim+json.
2. Certifique-se de que o conteúdo da solicitação em massa esteja em conformidade com as especificações de provisionamento /bulkUpload da API.

Não há nada nos logs de provisionamento

Descrição do problema

• Você enviou uma solicitação para o ponto de extremidade /bulkUpload da API de provisionamento e obteve o código de resposta HTTP 202, mas não há dados nos logs de provisionamento correspondentes à sua solicitação.

Causas prováveis

1. Seu aplicativo de provisionamento orientado por API está pausado.
2. O serviço de provisionamento ainda não atualizou os logs de provisionamento com os detalhes de processamento da solicitação em massa.
3. O status do agente de provisionamento local está inativo (se você estiver executando o provisionamento de usuário de entrada controlado por /API para o Active Directory local).

Resolução:

1. Certifique-se de que seu aplicativo de provisionamento esteja em execução. Se não estiver em execução, selecione a opção do menu Iniciar provisionamento para processar os dados.
2. Ative o status do agente de provisionamento local reiniciando o agente local.
3. Espere um atraso de 5 minutos a 10 minutos entre o processamento da solicitação e a gravação nos logs de provisionamento. Se seu cliente de API estiver enviando dados para o ponto de extremidade /bulkUpload da API de provisionamento, insira um atraso entre a invocação de solicitação e a consulta aos logs de provisionamento.

Código de resposta 403: Proibido

Descrição do problema

• Você enviou uma solicitação para o ponto de extremidade /bulkUpload da API de provisionamento e obteve o código de resposta HTTP 403 (Forbidden).

Causas prováveis

• A permissão SynchronizationData-User.Upload do Graph não é atribuída ao seu cliente de API.

Resolução:

• Atribua a permissão SynchronizationData-User.Upload do Graph ao seu cliente de API e repita a operação.

Muitas solicitações Código de resposta 429

O ponto de extremidade da API bulkUpload impõe os seguintes limites de limitação e retorna um código de resposta 429 se esses limites forem violados.

• 40 chamadas de API por cinco segundos - se o número de chamadas ultrapassar esse limite em um intervalo de cinco segundos, o cliente receberá uma resposta 429. Uma forma de evitar isso é espaçar o envio de solicitações usando atrasos na lógica de envio de solicitações do cliente. 

• 6.000 chamadas à API durante um período de 24 horas – se o número de chamadas ultrapassar esse limite, o cliente receberá uma resposta de 429. Uma maneira de evitar isso é garantir que o conteúdo em massa do SCIM seja otimizado para usar o máximo de 50 registros por chamada à API. Com essa abordagem, é possível enviar 300 mil registros a cada 24 horas.

Código de resposta 500 completo do bucket

Descrição do problema

• O cliente SCIM obtém HTTP 500 (Erro interno do servidor) com a mensagem: "O bucket que armazena os dados ingeridos está cheio, aguarde até que o serviço de sincronização processe os dados ingeridos e repita essa solicitação."
• Você pode encontrar esse erro durante a sincronização inicial ou durante ciclos de sincronização completa, quando grandes volumes de dados de RH são enviados ao endpoint de provisionamento /bulkUpload.

Por que esse erro ocorre

• O "bucket" é a fila de ingestão temporária usada pelo serviço de provisionamento para armazenar em buffer as cargas de entrada /bulkUpload antes de serem processadas.
• Cada trabalho de provisionamento controlado por API tem uma fila de ingestão dedicada.
• O serviço de provisionamento processa continuamente os conteúdos enfileirados e, em seguida, exclui os dados processados. Se esse ciclo de processamento e exclusão atrasar ou parar, os dados enfileirados poderão se acumular até o bucket ficar cheio.

Causas e resolução prováveis

Código de resposta 401: Não autorizado

Descrição do problema

• Você enviou uma solicitação para o ponto de extremidade /bulkUpload da API de provisionamento e obteve o código de resposta HTTP 401 (Unauthorized). O código de erro mostra "InvalidAuthenticationToken" com uma mensagem informando que o "Token de acesso expirou ou ainda não está válido".

Causas prováveis

• O token de acesso expirou.

Resolução:

• Gere um novo token de acesso para o seu cliente de API.

O trabalho entra no estado de quarentena

Descrição do problema

• Você acabou de iniciar o aplicativo de provisionamento e ele está no estado de quarentena.

Causas prováveis

• Você não configurou o email de notificação antes de iniciar o trabalho.

Solução: vá para o item de menu Editar Provisionamento. Em Configurações, há uma caixa de seleção ao lado de Enviar uma notificação por email quando ocorrer uma falha e um campo para inserir seu Email de Notificação. Certifique-se de marcar a caixa, forneça um email e salve a alteração. Clique em Reiniciar o provisionamento para remover o trabalho da quarentena.

Criação de usuário: UPN inválido

Descrição do problema Há uma falha de provisionamento de usuário. Os logs de provisionamento exibem o código de erro: AzureActiveDirectoryInvalidUserPrincipalName.

Resolução:

1. Vá para a página Editar Mapeamentos de Atributos.
2. Selecione o mapeamento de UserPrincipalName e o atualize para usar a função RandomString.
3. Copie e cole essa expressão na caixa de expressão: Join("", Replace([userName], , "(?<Suffix>@(.)*)", "Suffix", "", , ), RandomString(3, 3, 0, 0, 0, ), "@", DefaultDomain())

Essa expressão corrige o problema ao acrescentar um número aleatório ao valor do UPN aceito pelo Microsoft Entra ID.

Falha na criação do usuário: Domínio inválido

Descrição do problema Há uma falha de provisionamento de usuário. Os logs de provisionamento mostram uma mensagem de erro que indica domain does not exist.

Resolução:

1. Vá para a página Editar Mapeamentos de Atributos.
2. Selecione o mapeamento de UserPrincipalName e copie e cole essa expressão na caixa de inserção de expressão: Join("", Replace([userName], , "(?<Suffix>@(.)*)", "Suffix", "", , ), RandomString(3, 3, 0, 0, 0, ), "@", DefaultDomain())

Essa expressão corrige o problema acrescentando um domínio padrão ao valor de UPN aceito pela ID do Microsoft Entra.

Limitação conhecida: endereços com valores múltiplos, emails e números de telefone

Descrição do problema

• Atualmente, o provisionamento orientado por API não processa atributos SCIM com vários valores em addresses, emails e phoneNumbers quando o valor de type é home ou qualquer outro valor diferente de work.
• Essa limitação se aplica a expressões como addresses[type eq "home"], addresses[type eq "any-other-value"]e phoneNumbers[type eq "home"].

Comportamento atual

• Somente addresses[type eq "work"], emails[type eq "work"] e phoneNumbers[type eq "work"] os valores são processados.

Workaround

• Envie valores com suporte usando o work tipo quando precisar que o atributo seja processado pelo provisionamento controlado por API.

Próximas etapas

• Saiba mais sobre o provisionamento de entrada orientado por API