Identity Service疑難排解指南

本檔案提供Adobe Experience Platform Identity Service常見問題的解答,以及常見錯誤的疑難排解指南。 如需Platform API的一般問題和疑難排解,請參閱Adobe Experience Platform API疑難排解指南

識別單一客戶的資料通常會分散在客戶與您的品牌互動所使用的各種裝置和系統中。 Identity Service 會將這些分散的身分資料收集在一起,協助您全面了解客戶行為,以便您即時提供具影響力的數位體驗。如需詳細資訊,請參閱Identity服務概述

常見問題集

以下是關於Identity Service常見問題的解答清單。

什麼是身分資料?

身分資料是可用來識別個別人員的任何資料。 根據您組織內使用資料的方式,身分資料可以包含CRM系統的使用者名稱、電子郵件地址和ID。 身分資料不限於您網站或服務的註冊使用者,因為匿名使用者也可透過其裝置或Cookie ID來識別。

將資料欄位標示為身分有何好處?

將某些資料欄位標示為記錄和時間系列資料中的身分,可讓您在資料的自然結構中對應身分關係,並跨管道調解重複資料。 如需詳細資訊,請參閱Identity服務概述

什麼是已知和匿名身分?

已知身分是指可單獨使用,或搭配其他資訊使用,以識別、聯絡或尋找個別人員的身分值。 已知身分識別的範例可能包括電子郵件地址、電話號碼及CRM ID。

匿名身分是指無法單獨使用或搭配其他資訊使用,以識別、聯絡或尋找個別人員(例如Cookie ID)的身分值。

什麼是私人身分圖?

「私人身分圖」是已連結身分與已連結身分之間關係的私人地圖,只會顯示給您的組織。

從串流端點擷取或傳送至已啟用Identity Service的資料集的資料中,會包含多個身分識別時,這些身分識別會在「私人身分圖表」中連結。 Identity Service 可運用此圖表來蒐集指定消費者或實體的身分,以便進行身分拼接和設定檔合併。

如何在XDM架構中建立多個身分欄位?

Experience Data Model(XDM) 結構支援多個身分欄位。實作XDM個別設定檔或XDM ExperienceEvent類別之架構中,任何類型string的資料欄位都可標示為身分欄位。 標示後,這些欄位中包含的任何資料都會新增至設定檔的身分對應。

如需如何使用使用者介面將XDM欄位標示為身分欄位的步驟,請參閱結構編輯器教學課程中的身分區段。 如果您正在使用API,請參閱Schema Registry API教學課程中的 Identity描述符部分

是否有些欄位不應標示為身分的內容?

應為每個個人專屬的值保留身分欄位。 例如,將資料集視為客戶忠誠度計畫。 「忠誠度」欄位(金、銀、銅)不會是有用的身分欄位,而忠誠度ID(唯一值)則會是。

郵遞區號和IP位址等欄位不應標示為個人的身分,因為這些值可套用至多個個人。 這些類型的欄位只應標示為家庭層級行銷策略的身分。

為什麼我的身分欄位無法連結我預期的方式?

使用Identity Service API中的/cluster/members端點,您可以檢視一或多個身分欄位的相關身分。 如果回應未傳回您預期的連結身分,請務必在XDM資料中提供適當的身分資訊。 如需詳細資訊,請參閱Identity Service概覽中的提供XDM資料給Identity Service一節。

什麼是身分命名空間?

身分命名空間提供身分欄位與客戶身分相關的內容。 例如,「電子郵件」命名空間下的身分欄位應符合標準電子郵件格式(名稱@emailprovider.com),而使用「電話」命名空間的欄位則應符合標準電話號碼(例如北美的987-555-1234)。

命名空間可區分不同CRM系統之間的類似身分值。 例如,假設設定檔包含與公司獎勵計畫相關聯的數值忠誠度ID。 「忠誠度」的命名空間會將此值與您電子商務系統的類似數值ID(也顯示在相同的設定檔中)區隔開。

如需詳細資訊,請參閱身分命名空間概述

如何將身分識別與身分命名空間建立關聯?

身分欄位建立時,必須與現有的身分命名空間相關聯。 任何新的命名空間都必須先使用API🔗建立,才能與身分欄位建立關聯。

有關在使用API建立標識描述符時定義命名空間的逐步說明,請參閱《Schema Registry開發人員指南》中的建立描述符一節。 若要在UI中將結構欄位標示為身分,請遵循結構編輯器教學課程中的步驟。

Experience Platform提供的標準身分命名空間為何?

標準身分識別命名空間是所有組織皆可使用的命名空間。 如需可用標準命名空間的完整清單,請參閱身分識別命名空間概述

我可以在哪裡找到組織可用的身分識別命名空間清單?

使用Identity Service API,您可以向/idnamespace/identities端點提出GET要求,以列出貴組織的所有可用身分識別命名空間。 如需詳細資訊,請參閱Identity服務API概覽中列出可用命名空間的區段。

如何為組織建立自訂命名空間?

使用Identity服務API,您可以向/idnamespace/identities端點提出POST請求,以建立組織的自訂身分命名空間。 如需詳細資訊,請參閱Identity服務API概覽中關於建立自訂命名空間的區段。

什麼是複合身份和XID?

身分識別在API呼叫中會透過其複合身分識別或XID參考。 複合身分代表包含ID值和命名空間的身分。 XID是單值識別碼,代表與複合身分識別(ID和命名空間)相同的建構,且會在Identity Service保存時自動指派給新身分識別。 如需詳細資訊,請參閱Identity服務API概述

Identity Service如何處理個人識別資訊(PII)?

Identity Service會在保存值之前,先建立PII的強式單向密碼編譯雜湊。 「Phone」和「Email」命名空間中的身分資料會使用SHA-256自動雜湊,並在雜湊前將「電子郵件」值自動轉換為小寫。

傳送至Platform之前,應先加密所有PII嗎?

將PII資料擷取至Platform之前,您不需要手動加密。 透過將I1資料使用量標籤套用至所有適用的資料欄位,Platform會在擷取時自動將這些欄位轉換為雜湊ID值。

如需如何套用及管理資料使用量標籤的步驟,請參閱資料使用量標籤教學課程

雜湊PII型身分識別時是否有任何考量?

如果您要將雜湊PII值傳送至Identity Service,必須在資料集中使用相同的加密方法。 這可確保資料集中的相同身分值會產生相同的雜湊值,且能在身分圖表中正確比對及連結。

疑難排解

下節提供使用Identity Service API時可能遇到的特定錯誤碼和非預期行為的疑難排解建議。

Identity Service 錯誤訊息

以下是使用Identity Service API時可能遇到的錯誤訊息清單。

缺少必需的查詢參數

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

當要求路徑中未包含必要的查詢參數時,就會顯示此錯誤。 錯誤訊息的detail提供缺少參數的名稱。 此錯誤訊息的變數包括:

  • 缺少必需的查詢參數 — nsId
  • 缺少必需的查詢參數 — id
  • 缺少必需的查詢參數 — xid或(nsid,id)
  • 缺少必需的查詢參數 — targetNs
  • 缺少必需的查詢參數 — xids或compositeXids

再次嘗試之前,請先檢查您是否已在請求路徑中正確加入指示的參數。

時間戳記應為最近180天內

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

Identity Service 清除180天以前的資料。當您嘗試存取早於此版本的資料時,會顯示此錯誤訊息。

單一呼叫中有1000個XID的限制

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

當您嘗試擷取的身分資訊超過單一API呼叫中允許的XID上限時,會顯示此錯誤訊息。 將請求中的XID數量減少至顯示限制以解決此問題。

單個呼叫中有1000個compositeXid的限制

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

當您嘗試擷取單一API呼叫中允許之複合身分數量上限的身分資訊時,會顯示此錯誤訊息。 將請求中的複合身分識別數量減少至所顯示限制以下,以解決此問題。

指定的圖形類型無效

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

graph-type查詢參數在請求路徑中指定無效值時,系統會顯示此錯誤訊息。 請參閱Identity Service概覽中身分圖表的相關章節,了解支援哪些圖表類型。

服務令牌沒有有效範圍

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

當您的IMS組織尚未布建Identity Service的適當權限時,會顯示此錯誤訊息。 請連絡您的系統管理員以解決此問題。

網關服務令牌無效

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

如果發生此錯誤,您的存取權杖無效。 存取權杖每24小時過期一次,必須重新產生才能繼續使用Platform API。 如需產生新存取權杖的相關指示,請參閱驗證教學課程

授權服務令牌無效

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

如果發生此錯誤,您的存取權杖無效。 存取權杖每24小時過期一次,必須重新產生才能繼續使用Platform API。 如需產生新存取權杖的相關指示,請參閱驗證教學課程

用戶令牌沒有有效的產品上下文

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

未從Experience Platform整合產生存取權杖時,會顯示此錯誤訊息。 如需為Experience Platform整合產生新存取權杖的指示,請參閱驗證教學課程

從身分和命名空間程式碼取得原生XID時發生內部錯誤

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

當Identity Service保存身份時,將為標識的ID和關聯的命名空間ID分配一個稱為XID的唯一標識符。 當在尋找指定ID值和命名空間的XID過程中發生錯誤時,會顯示此訊息。

未針對Identity Service使用狀況布建IMS組織

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

當您的IMS組織尚未布建Identity Service的適當權限時,會顯示此錯誤訊息。 請連絡您的系統管理員以解決此問題。

內部伺服器錯誤

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

當Platform服務呼叫的執行中發生非預期的例外時,便會顯示此錯誤。 最佳實務是讓自動呼叫在收到此錯誤時,以計時間隔重試其請求幾次。 如果問題仍然存在,請與系統管理員聯繫。

批次擷取錯誤碼

Identity Service 從使用批次內嵌功能上傳至的記錄和時間序列資料內嵌 Platform 身分資料。由於批次內嵌是非同步流程,因此您必須檢視批次的詳細資訊才能檢視錯誤。 錯誤會隨著批次進行而累積,直到批次完成為止。

以下是使用資料擷取API時可能遇到的與Identity Service相關的錯誤訊息清單。

未知XDM架構

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

Identity Service 僅針對分別符合或類的記錄或時間序列資料 Profile 取 ExperienceEvent 用身份。嘗試為Identity Service內嵌未符合任一類別的資料將觸發此錯誤。

處理批次的前100列中有0個有效身分

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

當批次的前100列未顯示身分時,即會顯示此錯誤。 但是,此錯誤並未明確指出在後續記錄中找不到任何身分。

已略過記錄,因為每個XDM記錄只有1個身分

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

Identity Service 只有在單一記錄顯示兩個或多個身分值時,才會連結身分。此錯誤訊息會針對每個擷取的批次發出一次,並顯示只能找到一個身分的記錄數,且導致身分圖表未變更。

未為此IMS組織註冊命名空間代碼

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

擷取的記錄呈現的身分不存在或您的IMS組織無法存取其相關聯命名空間時,就會顯示此錯誤。

由於未針對私人身分圖布建IMS組織,因此略過批次內嵌

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

擷取批次資料時,當您的IMS組織尚未布建Identity Service的適當權限時,會顯示此錯誤訊息。 請連絡您的系統管理員以解決此問題。

內部錯誤

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

批次擷取期間發生非預期的例外時,就會顯示此錯誤。 最佳實務是讓自動呼叫在收到此錯誤時,以計時間隔重試其請求幾次。 如果問題仍然存在,請與系統管理員聯繫。

本頁內容