Guida alla risoluzione dei problemi di Identity Service

Questo documento fornisce le risposte alle domande più frequenti su Adobe Experience Platform Identity Service, nonché una guida alla risoluzione dei problemi relativi agli errori più comuni. Per domande e risoluzione dei problemi relativi a Platform API in generale, consulta Guida alla risoluzione dei problemi API di Adobe Experience Platform.

I dati che identificano un singolo cliente sono spesso frammentati tra i vari dispositivi e sistemi utilizzati per interagire con il tuo marchio. Identity Service riunisce queste identità frammentate, facilitando una comprensione completa del comportamento dei clienti in modo da poter fornire esperienze digitali di impatto in tempo reale. Per ulteriori informazioni, vedere Panoramica del servizio Identity.

Domande frequenti

Di seguito è riportato un elenco di risposte alle domande più frequenti su Identity Service.

Cosa sono i dati di identità?

I dati di identità sono tutti i dati che possono essere utilizzati per identificare una singola persona. A seconda del contesto in cui i dati vengono utilizzati all’interno dell’organizzazione, i dati di identità possono includere nomi utente, indirizzi e-mail e ID dai sistemi di gestione delle relazioni con i clienti. I dati di identità non sono limitati agli utenti registrati del sito web o del servizio, in quanto gli utenti anonimi possono essere identificati anche dal loro ID dispositivo o cookie.

Qual è il vantaggio di etichettare i campi di dati come identità?

Etichettare alcuni campi di dati come identità nei dati di record e serie temporali consente di mappare le relazioni di identità all’interno della struttura naturale dei dati e riconciliare i dati duplicati tra canali diversi. Consulta la Panoramica del servizio Identity per ulteriori informazioni.

Cosa sono le identità note e anonime?

Un’identità nota si riferisce a un valore di identità che può essere utilizzato da solo o con altre informazioni per identificare, contattare o individuare una singola persona. Esempi di identità note possono includere indirizzi e-mail, numeri di telefono e ID CRM.

Un’identità anonima si riferisce a un valore di identità che non può essere utilizzato da solo o con altre informazioni per identificare, contattare o individuare una singola persona (ad esempio un ID cookie).

Cos’è un grafico dell’identità privata?

Un grafo di identità privata è una mappa privata delle relazioni tra identità collegate e unite, visibile solo all’organizzazione.

Quando più identità sono incluse in un dato acquisito da un endpoint di streaming o inviate a un set di dati abilitato per Identity Service, queste identità sono collegate nel grafo delle identità private. Identity Service sfrutta questo grafico per ottenere le identità per un dato consumatore o entità, consentendo l’unione di identità e profili.

Come si creano più campi di identità in uno schema XDM?

Experience Data Model (XDM) gli schemi supportano più campi di identità. Qualsiasi campo di dati di tipo string all’interno di uno schema che implementa la classe XDM Individual Profile o XDM ExperienceEvent può essere etichettato come campo di identità. Una volta etichettati, tutti i dati contenuti in questi campi vengono aggiunti alla mappa di identità del profilo.

Per i passaggi su come etichettare un campo XDM come campo di identità utilizzando l’interfaccia utente, consulta la sezione Sezione identità nell’esercitazione sull’Editor di schema. Se utilizzi l’API, consulta Sezione del descrittore di identità nell’esercitazione API del registro dello schema.

Esistono contesti in cui alcuni campi non devono essere etichettati come identità?

I campi di identità devono essere riservati a valori univoci per ogni singolo utente. Ad esempio, considera un set di dati per un programma fedeltà dei clienti. Il campo "livello di fedeltà" (oro, argento, bronzo) non sarebbe un campo di identità utile, mentre l’ID di fedeltà (un valore univoco) sarebbe.

Campi come i codici postali e gli indirizzi IP non devono essere etichettati come identità per singoli utenti, in quanto questi valori possono essere applicati a più di una singola persona. Questi tipi di campi dovrebbero essere etichettati solo come identità per le strategie di marketing a livello familiare.

Perché i campi di identità non collegano come previsto?

Utilizzo di /cluster/members endpoint nell’API del servizio Identity, puoi visualizzare le identità associate a uno o più campi di identità. Se la risposta non restituisce le identità collegate previste, assicurati di fornire le informazioni di identità appropriate nei dati XDM. Consulta la sezione su fornitura di dati XDM al servizio Identity nella panoramica del servizio Identity per ulteriori informazioni.

Che cos’è uno spazio dei nomi delle identità?

Uno spazio dei nomi delle identità fornisce contesto per il modo in cui i campi di identità si relazionano all’identità di un cliente. Ad esempio, i campi di identità nello spazio dei nomi "E-mail" devono essere conformi a un formato e-mail standard (nome@emailprovider.com) i campi che utilizzano lo spazio dei nomi "Telefono" devono essere conformi a un numero di telefono standard (come 987-555-1234 in Nord America).

Gli spazi dei nomi distinguono valori di identità simili tra sistemi di gestione delle relazioni con i clienti diversi. Ad esempio, considera un profilo che contiene un ID fedeltà numerico associato al programma di premi della tua azienda. Uno spazio dei nomi di "Fedeltà" separerebbe questo valore da un ID numerico simile per il sistema di eCommerce che appare anche nello stesso profilo.

Consulta la panoramica dello spazio dei nomi delle identità per ulteriori informazioni.

Come si associa un’identità a uno spazio dei nomi delle identità?

I campi di identità devono essere associati a uno spazio dei nomi di identità esistente al momento della creazione. Eventuali nuovi spazi dei nomi devono essere creato utilizzando l’API prima di associarli ai campi di identità.

Per istruzioni dettagliate sulla definizione di uno spazio dei nomi durante la creazione di un descrittore di identità tramite l’API, consulta la sezione su creazione di un descrittore nella guida per gli sviluppatori del registro dello schema. Per contrassegnare un campo schema come identità nell’interfaccia utente, segui i passaggi descritti in Esercitazione sull’editor di schemi.

Quali sono gli spazi dei nomi di identità standard forniti da Experienci Platform? standard-namespaces

Gli spazi dei nomi di identità standard sono spazi dei nomi disponibili per tutte le organizzazioni. Consulta la Panoramica sugli spazi dei nomi delle identità per un elenco completo degli spazi dei nomi standard disponibili.

Dove posso trovare l’elenco degli spazi dei nomi di identità disponibili per la mia organizzazione?

Utilizzo di API del servizio Identity, puoi elencare tutti gli spazi dei nomi di identità disponibili per la tua organizzazione effettuando una richiesta GET al /idnamespace/identities endpoint. Consulta la sezione su elenco degli spazi dei nomi disponibili per ulteriori informazioni, consulta la panoramica dell’API del servizio Identity.

Come si crea uno spazio dei nomi personalizzato per l’organizzazione?

Utilizzo di API del servizio Identity, puoi creare uno spazio dei nomi di identità personalizzato per la tua organizzazione effettuando una richiesta POST al /idnamespace/identities endpoint. Consulta la sezione su creazione di uno spazio dei nomi personalizzato per ulteriori informazioni, consulta la panoramica dell’API del servizio Identity.

Cosa sono le identità composite e gli XID?

Nelle chiamate API viene fatto riferimento alle identità tramite l’identità composita o XID. Un’identità composita è una rappresentazione di un’identità che contiene un valore ID e uno spazio dei nomi. Un XID è un identificatore a valore singolo che rappresenta lo stesso costrutto di un’identità composita (un ID e uno spazio dei nomi) e viene assegnato automaticamente alle nuove identità quando viene mantenuto da Identity Service. Consulta la Panoramica API del servizio Identity per ulteriori informazioni.

In che modo il servizio Identity gestisce le informazioni personali (PII, personally identifiable information)?

Identity Service dispone di spazi dei nomi standard per supportare l’acquisizione di valori di identità con hash per numeri di telefono e e-mail. Tuttavia, sei responsabile dell’hashing dei valori. Per ulteriori informazioni sull’hashing dei dati acquisiti in Platform, consulta Data Prep guida alle funzioni di mappatura.

Ci sono considerazioni quando si esegue l’hashing di identità basate su PII?

Se invii valori PII con hash a Identity Service, devi utilizzare lo stesso metodo di crittografia nei set di dati. In questo modo lo stesso valore di identità in tutti i set di dati genera gli stessi valori con hash e può essere correttamente associato e collegato nel grafico delle identità.

Perché non posso accedere alla pagina o alle API del grafo delle identità?

L’amministratore di Platform deve effettuare il provisioning con view-identity-graph per visualizzare i dati del grafico delle identità. Senza questa autorizzazione, riceverai un messaggio di autorizzazione negata nella pagina del visualizzatore del grafico delle identità e quando chiami le API di Platform. Consulta la panoramica sul controllo degli accessi per ulteriori informazioni sulle autorizzazioni.

Risoluzione dei problemi

La sezione seguente fornisce suggerimenti per la risoluzione dei problemi relativi a codici di errore specifici e a comportamenti imprevisti che potrebbero verificarsi durante l'utilizzo di Identity Service API.

Identity Service messaggi di errore

Di seguito è riportato un elenco di messaggi di errore che è possibile visualizzare quando si utilizza Identity Service API.

Parametro di query richiesto mancante

{
    "title": "InvalidInput",
    "status": 400,
    "detail": "Missing required query parameter - namespace"
}

Questo errore viene visualizzato quando un parametro di query richiesto non è stato incluso nel percorso della richiesta. Il detail del messaggio di errore fornisce il nome del parametro mancante. Le varianti di questo messaggio di errore includono:

Prima di riprovare, verifica di includere correttamente il parametro indicato nel percorso della richiesta.

Il timestamp deve rientrare negli ultimi 180 giorni

{
    "title": "InvalidInput",
    "status": 400,
    "detail": "Timestamp should be within last 180 days"
}

Identity Service elimina i dati più vecchi di 180 giorni. Questo messaggio di errore viene visualizzato quando si tenta di accedere a dati precedenti a questo.

Una singola chiamata ha un limite di 1000 XID

{
    "title": "InvalidInput",
    "status": 400,
    "detail": "There is a limit of 1000 XIDs in a single call"
}

Questo messaggio di errore viene visualizzato quando si tenta di recuperare informazioni di identità per un numero di elementi superiore al numero massimo consentito di XID consentito in una singola chiamata API. Per risolvere il problema, riduci il numero di XID nella richiesta a meno del limite visualizzato.

Una singola chiamata ha un limite di 1000 compositeXids

{
    "title": "InvalidInput",
    "status": 400,
    "detail": "There is a limit for 1000 compositeXids in a single call"
}

Questo messaggio di errore viene visualizzato quando si tenta di recuperare informazioni di identità per un numero di elementi superiore al numero massimo consentito di identità composite consentito in una singola chiamata API. Per risolvere il problema, riduci il numero di identità composite nella richiesta a meno del limite visualizzato.

Il tipo di grafico specificato non è valido

{
    "title": "InvalidInput",
    "status": 400,
    "detail": "The graph-type abc specified is invalid. Please provide a valid graph-type"
}

Questo messaggio di errore viene visualizzato quando graph-type al parametro query viene assegnato un valore non valido nel percorso della richiesta. Consulta la sezione su grafi di identità nel Identity Service panoramica per scoprire quali tipi di grafo sono supportati.

Il token di servizio non dispone di un ambito valido

{
    "title": "UnauthorizedAccess",
    "status": 401,
    "detail": "Service token does not have valid scope. Either acp.core.identity or acp.foundation is required"
}

Questo messaggio di errore viene visualizzato quando all’organizzazione non sono state assegnate le autorizzazioni appropriate per Identity Service. Per risolvere il problema, contatta l’amministratore di sistema.

Token del servizio gateway non valido

{
    "title": "UnauthorizedAccess",
    "status": 401,
    "detail": "Gateway service token is not valid"
}

In caso di errore, il token di accesso non è valido. I token di accesso scadono ogni 24 ore e devono essere rigenerati per continuare a utilizzare Platform API. Consulta la tutorial sull’autenticazione per istruzioni sulla generazione di nuovi token di accesso.

Token del servizio di autorizzazione non valido

{
    "title": "UnauthorizedAccess",
    "status": 401,
    "detail": "Authorization service token is not valid"
}

In caso di errore, il token di accesso non è valido. I token di accesso scadono ogni 24 ore e devono essere rigenerati per continuare a utilizzare Platform API. Consulta la tutorial sull’autenticazione per istruzioni sulla generazione di nuovi token di accesso.

Il token utente non dispone di un contesto di prodotto valido

{
    "title": "UnauthorizedAccess",
    "status": 401,
    "detail": "User token does not have valid product context"
}

Questo messaggio di errore viene visualizzato quando il token di accesso non è stato generato da un Experience Platform integrazione. Consulta la tutorial sull’autenticazione per istruzioni sulla generazione di nuovi token di accesso per un Experience Platform integrazione.

Errore interno nell’ottenere XID nativo dal codice di identità e spazio dei nomi

{
    "title": "UnauthorizedAccess",
    "status": 401,
    "detail": "Invalid IMS Token/IMS Org | Internal error - when tried to get native XID from identity and namespace code"
}

Quando Identity Service persiste un’identità, all’ID dell’identità e all’ID dello spazio dei nomi associato viene assegnato un identificatore univoco denominato XID. Questo messaggio viene visualizzato quando si verifica un errore durante il processo di ricerca dell’XID per un determinato valore ID e spazio dei nomi.

Non è stato eseguito il provisioning per l’organizzazione IMS Identity Service utilizzo

{
    "title": "AccountNotProvisioned",
    "status": 403,
    "detail": "The IMS Org. {IMS_ORG_NAME} is not provisioned for Identity Service usage"
}

Questo messaggio di errore viene visualizzato quando all’organizzazione non sono state assegnate le autorizzazioni appropriate per Identity Service. Per risolvere il problema, contatta l’amministratore di sistema.

Errore interno del server

{
    "title": "InternalError",
    "status": 500,
    "detail": "Internal Server Error. There was a problem processing your request"
}

Questo errore viene visualizzato quando si verifica un'eccezione imprevista nell'esecuzione di un Platform chiamata del servizio. Si consiglia di programmare le chiamate automatizzate in modo da ritentare le richieste più volte a intervalli temporizzati quando si riceve questo errore. Se il problema persiste, contattare l'amministratore di sistema.

Codici di errore di acquisizione batch

Identity Service acquisisce i dati di identità dai dati di record e serie temporali caricati in Platform utilizzo dell’acquisizione in batch. Poiché l’acquisizione batch è un processo asincrono, è necessario visualizzare i dettagli di un batch per visualizzare gli errori. Gli errori si accumulano con l’avanzamento del batch fino al suo completamento.

Di seguito è riportato un elenco di messaggi di errore relativi a Identity Service è possibile che si verifichino problemi durante l’utilizzo di API di acquisizione in batch.

Schema XDM sconosciuto

{
    "title": "InvalidInput",
    "status": 400,
    "detail": "Unknown XDM schema"
}

Identity Service utilizza le identità solo per i dati di record o serie temporali conformi al Profile o ExperienceEvent classi. Tentativo di acquisire dati per Identity Service se non aderisce a nessuna delle due classi, verrà attivato questo errore.

Nelle prime 100 righe del batch elaborato erano presenti 0 identità valide

{
    "title": "InvalidInput",
    "status": 400,
    "detail": "There were 0 valid identities in the first 100 rows of the processed batch"
}

Questo errore viene visualizzato quando le prime 100 righe di un batch non presentano identità. Questo errore non indica in modo conclusivo che non sono state trovate identità nei record successivi, tuttavia.

Record ignorati perché avevano una sola identità per record XDM

{
    "title": "InvalidInput",
    "status": 400,
    "detail": "Skipped {NUMBER_OF_RECORDS} records as they had only 1 identity per XDM record"
}

Identity Service collega le identità solo quando singoli record presentano due o più valori di identità. Questo messaggio di errore si verifica una volta per ogni batch acquisito e visualizza il numero di record in cui è stata trovata una sola identità e non ha prodotto alcuna modifica al grafico delle identità.

Codice dello spazio dei nomi non registrato per questa organizzazione IMS

{
    "title": "InvalidInput",
    "status": 400,
    "detail": "Namespace Code {ERRONEOUS_CODE} is not registered for this IMS Org"
}

Questo errore viene visualizzato quando un record acquisito presenta un’identità il cui spazio dei nomi associato non esiste o è inaccessibile per la tua organizzazione.

L’acquisizione batch verrà ignorata perché non è stato eseguito il provisioning dell’organizzazione IMS per il grafo delle identità private

{
    "title": "AccountNotProvisioned",
    "status": 403,
    "detail": "Skipping batch ingestion as IMS Org is not provisioned for Private Identity Graph"
}

Quando si acquisiscono dati batch, questo messaggio di errore viene visualizzato se all’organizzazione non sono state assegnate le autorizzazioni appropriate per Identity Service. Per risolvere il problema, contatta l’amministratore di sistema.

Errore interno

{
    "title": "InternalError",
    "status": 500,
    "detail": "Internal Error. There was a problem during the ingestion"
}

Questo errore viene visualizzato quando si verifica un’eccezione imprevista durante l’acquisizione di un batch. Si consiglia di programmare le chiamate automatizzate in modo da ritentare le richieste più volte a intervalli temporizzati quando si riceve questo errore. Se il problema persiste, contattare l'amministratore di sistema.