Risolvere i problemi relativi all'API di provisioning in ingresso

Introduzione

Questo documento illustra gli errori e i problemi comunemente riscontrati con l'API di provisioning in ingresso e spiega come risolverli.

Scenari di risoluzione dei problemi

Formato dati non valido

Descrizione del problema

• Viene visualizzato il messaggio di errore Invalid Data Format con codice di risposta HTTP 400 (Richiesta non valida).

Cause probabili

1. Si sta inviando una richiesta in blocco valida in base alle specifiche dell'API di provisioning /bulkUpload, ma l'intestazione della richiesta HTTP "Content-Type" non è stata impostata su application/scim+json.
2. Si sta inviando una richiesta in blocco che non è conforme alle specifiche dell'API di provisioning /bulkUpload.

Risoluzione:

1. Verificare che l'intestazione Content-Type della richiesta HTTP sia impostata sul valore application/scim+json.
2. Assicurarsi che il payload della richiesta in blocco sia conforme alle specifiche dell'API di provisioning /bulkUpload.

I log di provisioning sono vuoti

Descrizione del problema

• È stata inviata una richiesta all'endpoint API di provisioning /bulkUpload ed è stato ricevuto il codice di risposta HTTP 202, ma non sono presenti dati nei log di provisioning corrispondenti alla richiesta.

Cause probabili

1. L'app di provisioning basata su API è sospesa.
2. Il servizio di provisioning non ha ancora aggiornato i log di provisioning con i dettagli dell’elaborazione delle richieste in blocco.
3. Lo stato dell'agente di provisioning locale è inattivo (se stai eseguendo il provisioning di utenti in ingresso basato su API per Active Directory on-premises).

Risoluzione:

1. Verifica che l'app di provisioning sia in esecuzione. Se non è in esecuzione, selezionare l'opzione di menu Avvia provisioning per elaborare i dati.
2. Portare lo stato dell'agente di provisioning locale su attivo riavviando l'agente locale.
3. Prevedere un ritardo di 5 minuti a 10 minuti tra l'elaborazione della richiesta e la scrittura nei log di provisioning. Se il client API invia dati all’endpoint dell’API di provisioning /bulkUpload, introduci un intervallo di tempo tra l’invio della richiesta e la query dei log di provisioning.

Codice di stato 403 Proibito

Descrizione del problema

• È stata inviata una richiesta all'endpoint API di provisioning /bulkUpload ed è stato ricevuto il codice di risposta HTTP 403 (Accesso negato).

Cause probabili

• L'autorizzazione SynchronizationData-User.Upload Graph non è assegnata al client API.

Risoluzione:

• Assegnare al client API l'autorizzazione SynchronizationData-User.Upload di Graph e ripetere l'operazione.

Codice di risposta 429 Troppe richieste

L'endpoint API bulkUpload applica i limiti seguenti previsti dalla limitazione delle richieste e restituisce un codice di risposta 429 se questi limiti vengono superati.

• 40 chiamate API per 5 secondi: se il numero di chiamate supera questo limite in un intervallo di 5 secondi, il client ottiene una risposta 429. Un modo per evitare questo è scaglionare l'invio delle richieste introducendo ritardi nella logica client di invio delle richieste. 

• 6.000 chiamate API in un periodo di 24 ore: se il numero di chiamate supera questo limite, il client riceve una risposta 429. Un modo per evitare questo problema consiste nell'assicurarsi che il payload in blocco SCIM sia ottimizzato per usare il numero massimo di 50 record per ogni chiamata API. Con questo approccio è possibile inviare 300.000 record ogni 24 ore.

Codice di risposta completo del bucket 500

Descrizione del problema

• Il client SCIM ottiene HTTP 500 (errore interno del server) con il messaggio : "Il bucket in cui sono archiviati i dati inseriti è pieno, attendere che il servizio di sincronizzazione elabori i dati inseriti e riprova a eseguire questa richiesta".
• Questo errore potrebbe verificarsi durante la sincronizzazione iniziale o i cicli di sincronizzazione completa quando i set di dati HR di grandi dimensioni vengono inviati all'endpoint di provisioning /bulkUpload .

Perché si verifica questo errore

• Il "bucket" è la coda di inserimento temporanea usata dal servizio di provisioning per memorizzare nel buffer i payload in ingresso /bulkUpload prima dell'elaborazione.
• Ogni processo di provisioning basato su API ha una coda di inserimento dedicata.
• Il servizio di provisioning elabora continuamente i payload in coda e quindi elimina i dati elaborati. Se questo ciclo di elaborazione ed eliminazione subisce ritardi o si arresta, i dati in coda possono accumularsi finché il bucket non si riempie.

Cause e risoluzione probabili

Codice di risposta 401 Non autorizzato

Descrizione del problema

• È stata inviata una richiesta all'endpoint API di provisioning /bulkUpload ed è stato ricevuto il codice di risposta HTTP 401 (Non autorizzato). Il codice errore visualizza "InvalidAuthenticationToken" con un messaggio in cui viene segnalato che il token di accesso è scaduto o non è ancora valido.

Cause probabili

• Il token di accesso è scaduto.

Risoluzione:

• Generare un nuovo token di accesso per il client API.

Il processo entra in stato di quarantena

Descrizione del problema

• Hai appena avviato l'app di provisioning ed è in quarantena.

Cause probabili

• Non è stato impostato l'indirizzo e-mail per le notifiche prima di avviare l'attività.

Risoluzione: Vai alla voce di menu Modifica provisioning. In Impostazioni è presente una casella di controllo accanto a Invia una notifica di posta elettronica in caso di errore e un campo in cui inserire l'indirizzo di posta elettronica per le notifiche. Assicurarsi di selezionare la casella, specificare un indirizzo di posta elettronica e salvare la modifica. Fare clic su Riavvia provisioning per liberare il processo dalla quarantena.

Creazione di utenti - UPN non valido

Descrizione del problema: si è verificato un errore di provisioning degli utenti. I log di provisioning visualizzano il codice errore AzureActiveDirectoryInvalidUserPrincipalName.

Risoluzione:

1. Vai alla pagina Modifica le mappature degli attributi.
2. Selezionare il mapping UserPrincipalName e aggiornarlo per usare la funzione RandomString.
3. Copiare e incollare questa espressione nella casella dell'espressione: Join("", Replace([userName], , "(?<Suffix>@(.)*)", "Suffix", "", , ), RandomString(3, 3, 0, 0, 0, ), "@", DefaultDomain()).

Questa espressione consente di risolvere il problema aggiungendo un numero casuale al valore UPN accettato da Microsoft Entra ID.

Creazione dell'utente non riuscita - Dominio non valido

Descrizione del problema: si è verificato un errore di provisioning degli utenti. I log di provisioning visualizzano un messaggio di errore in cui si legge domain does not exist.

Risoluzione:

1. Passare alla pagina Modifica i mapping degli attributi.
2. Selezionare il mapping UserPrincipalName, quindi copiare e incollare questa espressione nella casella di input dell'espressione: Join("", Replace([userName], , "(?<Suffix>@(.)*)", "Suffix", "", , ), RandomString(3, 3, 0, 0, 0, ), "@", DefaultDomain()).

Questa espressione consente di risolvere il problema aggiungendo un dominio predefinito al valore UPN accettato da Microsoft Entra ID.

Limitazione nota: indirizzi multivalore, messaggi di posta elettronica e numeri di telefono

Descrizione del problema

• Il provisioning basato su API non elabora attualmente gli attributi SCIM multivalore in addresses, emails e phoneNumbers quando il valore type è home o qualsiasi altro valore diverso da work.
• Questa limitazione si applica alle espressioni come addresses[type eq "home"], addresses[type eq "any-other-value"]e phoneNumbers[type eq "home"].

Comportamento corrente

• Vengono elaborati solo i valori addresses[type eq "work"], emails[type eq "work"] e phoneNumbers[type eq "work"].

Workaround

• Inviare valori supportati usando il work tipo quando è necessario elaborare l'attributo tramite provisioning basato sulle API.

Passaggi successivi

• Altre informazioni sul provisioning in ingresso basato su API