Resolver problemas na API de provisionamento de entrada

Introdução

Este documento aborda erros comumente encontrados e problemas com a API de provisionamento de entrada e como solucioná-los.

Cenários de resolução de problemas

Formato de dados inválido

Descrição do problema

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

Causas prováveis

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

Resolução:

1. Verifique se a Solicitação HTTP tem o Content-Type cabeçalho definido como o valor application/scim+json.
2. Certifique-se de que a carga útil de solicitação em massa esteja em conformidade com as especificações da API de provisionamento /bulkUpload .

Não há nada nos logs de provisionamento

Descrição do problema

• Você enviou uma solicitação para o ponto de extremidade da API de provisionamento /bulkUpload 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 controlado por API está pausado.
2. O serviço de provisionamento ainda não atualizou os logs de provisionamento com os detalhes de processamento de 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 orientado por /API para o Ative Directory local).

Resolução:

1. Verifique se seu aplicativo de provisionamento está em execução. Se não estiver em execução, selecione a opção de menu Iniciar provisionamento para processar os dados.
2. Coloque o estado do agente de provisionamento local como ativo 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 o seu cliente de API estiver enviando dados para o ponto de extremidade da API de provisionamento /bulkUpload, introduza um intervalo de tempo entre a invocação da solicitação e a consulta de logs de provisionamento.

Código de resposta 403 proibido

Descrição do problema

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

Causas prováveis

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

Resolução:

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

Código de resposta 429: demasiadas solicitações

O endpoint da API bulkUpload aplica os seguintes limites de throttling e devolve um código de resposta 429 se esses limites forem excedidos.

• 40 chamadas de API por 5 segundos – se o número de chamadas ultrapassar esse limite em um intervalo de 5 segundos, o cliente receberá uma resposta de 429. Uma forma de evitar isto é espaçar o envio do pedido, introduzindo atrasos na lógica do cliente para submeter pedidos. 

• 6.000 chamadas de API em um período de 24 horas – se o número de chamadas ultrapassar esse limite, o cliente receberá uma resposta 429. Uma forma de evitar isto é garantir que o seu payload SCIM em lote está otimizado para utilizar o máximo de 50 registos por chamada à API. Com essa abordagem, você pode enviar 300 mil registros a cada 24 horas.

Código de resposta 500: bucket cheio

Descrição do problema

• O cliente SCIM recebe HTTP 500 (Erro do Servidor Interno) com a mensagem: "O balde que armazena os dados ingeridos está cheio, por favor aguarde que o serviço de sincronização processe os dados ingeridos e tente novamente este pedido."
• Pode ver este erro durante a sincronização inicial ou ciclos completos de sincronização quando grandes conjuntos de dados de RH são enviados para o endpoint de provisionamento /bulkUpload .

Por que motivo este erro ocorre

• O "bucket" é a fila de ingestão temporária utilizada pelo serviço de aprovisionamento para reter temporariamente os payloads recebidos /bulkUpload antes de serem processados.
• Cada trabalho de provisionamento orientado por API tem uma fila de ingestão dedicada.
• O serviço de provisionamento processa continuamente cargas úteis em fila e depois apaga os dados processados. Se este ciclo de processo e eliminação ficar atrasado ou parar, os dados em fila podem acumular-se até o bucket estar cheio.

Causas prováveis e resolução

Código de resposta 401 não autorizado

Descrição do problema

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

Causas prováveis

• O seu token de acesso expirou.

Resolução:

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

O trabalho entra em estado de quarentena

Descrição do problema

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

Causas prováveis

• Você não definiu o e-mail de notificação antes de iniciar o trabalho.

Resolução: Vá para a opção de menu Editar provisionamento. Em Configurações , há uma caixa de seleção ao lado de Enviar uma notificação por e-mail quando ocorrer uma falha e um campo para inserir seu Email de notificação. Certifique-se de marcar a caixa, fornecer um e-mail e salvar a alteração. Clique em Reiniciar provisionamento de forma a tirar o trabalho da quarentena.

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

Descrição do problema: há uma falha de provisionamento do 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 UserPrincipalName mapeamento e atualize-o para usar a RandomString função.
3. Copie e cole esta expressão na caixa de expressão: Join("", Replace([userName], , "(?<Suffix>@(.)*)", "Suffix", "", , ), RandomString(3, 3, 0, 0, 0, ), "@", DefaultDomain())

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

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

Descrição do problema: há uma falha de provisionamento do usuário. Os logs de provisionamento exibem uma mensagem de erro informando domain does not exist.

Resolução:

1. Aceda à página Editar os mapeamentos de atributos.
2. Selecione o mapeamento UserPrincipalName e copie e cole esta expressão na caixa de texto da expressão: Join("", Replace([userName], , "(?<Suffix>@(.)*)", "Suffix", "", , ), RandomString(3, 3, 0, 0, 0, ), "@", DefaultDomain())

Esta expressão corrige o problema anexando um domínio padrão ao valor UPN aceito pelo ID do Microsoft Entra.

Limitação conhecida: endereços, emails e números de telefone multivalorados

Descrição do problema

• O provisionamento baseado em API não processa atualmente atributos SCIM multivalorados em addresses, emails e phoneNumbers quando o valor de type é home ou qualquer outro valor que não seja work.
• Esta limitação aplica-se a expressões como addresses[type eq "home"], addresses[type eq "any-other-value"], e phoneNumbers[type eq "home"].

Comportamento atual

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

Solução

• Envie valores suportados usando o work tipo quando precisar que o atributo seja processado por provisionamento orientado por API.

Próximos passos

• Saiba mais sobre o provisionamento de entrada orientado por API