XDM系統故障排除指南

本檔案提供有關Adobe Experience Platform中Experience Data Model (XDM)和XDM System的常見問題解答，以及常見錯誤的疑難排解指南。 有關其他平台服務的問題和疑難排解，請參閱體驗平台疑難排解指南。

Experience Data Model (XDM)是開 放原始碼規格，可定義客戶體驗管理的標準架構。構建Experience Platform的方法​XDM系統​操作Experience Data Model方案，以便由Platform服務使用。 Schema Registry​提供用戶介面和REST風格的API以訪問Experience Platform中的​Schema Library。 如需詳細資訊，請參閱XDM檔案。

常見問題集

以下是有關XDM系統及Schema Registry API使用的常見問題解答清單。

如何將欄位新增至架構？

您可以使用mixin，將欄位添加到架構中。 每個混音都與一個或多個類相容，允許混音用於實現這些相容類之一的任何模式。 雖然Adobe Experience Platform提供數種業界混音及其預先定義的欄位，但您可以使用API或使用者介面建立新混音，將自己的欄位新增至架構。

有關在Schema Registry API中建立新混音的詳細資訊，請參閱mixin端點指南。 如果您使用UI，請參閱架構編輯器教程。

混音與資料類型的最佳用途為何？

Mixinsare 是定義架構中一個或多個欄位的元件。Mixins可強制其欄位在架構階層中的顯示方式，因此在每個架構中都會顯示與其所包含的相同結構。 Mixins僅與特定類相容，由其meta:intendedToExtend屬性所識別。

資料 類型還可以為模式提供一個或多個欄位。但是，與mixin不同，資料類型不限於特定類別。 這使得資料類型成為更有彈性的選項，以說明可在具有潛在不同類別的多個結構中重複使用的常用資料結構。

架構的唯一ID是什麼？

所有Schema Registry資源（結構、混合、資料類型、類別）都有URI，可當成參考和查閱用途的唯一ID。 在API中查看架構時，可在頂級$id和meta:altId屬性中找到。

如需詳細資訊，請參閱Schema Registry API開發人員指南中的資源識別一節。

架構何時開始防止中斷更改？

只要在建立資料集時從未使用過或在Real-time Customer Profile中啟用過，就可以對模式進行中斷更改。 一旦在資料集建立中使用模式或啟用與Real-time Customer Profile一起使用，系統將嚴格執行模式演化規則。

長欄位類型的最大大小是多少？

長欄位類型是一個最大大小為53(+1)位的整數，其電位範圍介於-9007199254740992和9007199254740992之間。 這是由於JSON的JavaScript實作如何表示長整數的限制。

有關欄位類型的詳細資訊，請參閱XDM欄位類型約束上的文檔。

如何定義我的架構的身分？

在Experience Platform中，身分用於識別對象（通常是個人），而不管所解釋的資料源為何。 它們是在結構中定義的，方法是將鍵欄位標籤為「標識」。 常用的身分識別欄位包括電子郵件地址、電話號碼、Experience Cloud ID (ECID)、CRM ID和其他唯一ID欄位。

欄位可使用API或使用者介面標示為身分。

在API中定義身份

在API中，通過建立身份描述符來建立身份。 身份描述符信號表示模式的特定屬性是唯一標識符。

身份描述符由POST請求建立到／描述符端點。 如果成功，您將會收到HTTP狀態201（已建立）和包含新描述符詳細資訊的響應對象。

有關在API中建立身份描述符的詳細資訊，請參閱Schema Registry開發人員指南中描述符部分的文檔。

在UI中定義身份

在模式編輯器中開啟模式時，在編輯器的​Structure​部分中選擇要標籤為身份的欄位。 在右側的​欄位屬性​下，選擇​Identity​複選框。

有關在UI中管理身份的詳細資訊，請參閱方案編輯器教程中定義身份欄位部分一節。

我的架構需要主要身分識別嗎？

主要身份是可選的，因為結構可能有0或1個。 但是，方案必須具有主標識，才能在Real-time Customer Profile中啟用方案。 如需詳細資訊，請參閱架構編輯器教學課程的identity一節。

如何啟用模式以用於Real-time Customer Profile?

通過在架構的meta:immutableTags屬性中添加"union"標籤，可在Real-time Customer Profile中使用架構。 可以使用API或用戶介面來啟用與Profile一起使用的模式。

使用API為Profile啟用現有模式

發出PATCH請求以更新模式，並將meta:immutableTags屬性添加為包含值"union"的陣列。 如果更新成功，回應將顯示現在包含union標籤的更新架構。

有關使用API啟用架構以用於Real-time Customer Profile的詳細資訊，請參閱Schema Registry開發人員指南的unions檔案。

使用UI為Profile啟用現有模式

在Experience Platform中，在左側導航中選擇​方案，然後從方案清單中選擇要啟用的方案的名稱。 然後，在編輯器的右側，在​方案屬性​下，選擇​描述檔​以開啟它。

如需詳細資訊，請參閱架構編輯器教學課程中「即時客戶描述檔使用」一節。

我可以直接編輯聯合架構嗎？

聯合模式是只讀的，由系統自動生成。 無法直接編輯。 將"union"標籤添加到實現該類的模式時，將為特定類建立聯合模式。

有關XDM中工會的詳細資訊，請參閱Schema Registry API開發人員指南中的unions一節。

如何格式化資料檔案以將資料嵌入到模式？

Experience Platform 接受或JSON格式 Parquet 的資料檔案。這些檔案的內容必須符合資料集參考的架構。 有關資料檔案提取的最佳做法的詳細資訊，請參見批次提取概述。

錯誤和疑難排解

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

找不到對象

{
    "type": "/placeholder/type/uri",
    "status": 404,
    "title": "NotFoundError",
    "detail": "Object https://ns.adobe.com/incorrectTenantId/schemas/ee067e31b08514d21e2b82577813409d 
      with version 1 not found"
}

當系統找不到特定資源時，將顯示此錯誤。 資源可能已刪除，或API呼叫中的路徑無效。 請確定您已輸入API呼叫的有效路徑，然後再次嘗試。 您可能想檢查是否已為資源輸入正確的ID，以及路徑是否與適當的容器（全域或租用戶）正確命名。

如需在API中建構查閱路徑的詳細資訊，請參閱Schema Registry開發人員指南中的container和資源識別章節。

標題必須是唯一的

{
    "type": "/placeholder/type/uri",
    "status": 400,
    "title": "BadRequestError",
    "detail": "Title must be unique. An object 
      https://ns.adobe.com/{TENANT_ID}/schemas/26f6833e55db1dd8308aa07a64f2042d 
      already exists with the same title."
}

當您嘗試使用另一個資源已使用的標題建立資源時，將顯示此錯誤消息。 標題在所有資源類型中必須是唯一的。 例如，如果您嘗試建立包含已由架構使用之標題的混音，您會收到此錯誤。

自訂欄位必須使用頂層欄位

{
    "type": "/placeholder/type/uri",
    "status": 400,
    "title": "BadRequestError",
    "detail": "For custom fields, you must use a top level field named _{TENANT_ID}
       and all the other fields must be defined under it"
}

當您嘗試建立新混音時，會顯示此錯誤訊息，其中的欄位名稱不正確。 由IMS組織定義的Mixin必須使用TENANT_ID命名其欄位，以避免與其他產業和廠商資源產生衝突。 在mixins端點指南中可找到混合的適當資料結構的詳細示例。

Real-time Customer Profile 錯誤

以下錯誤消息與啟用Real-time Customer Profile方案時涉及的操作相關聯。 如需詳細資訊，請參閱Schema Registry API開發人員指南中的unions一節。

要啟用配置檔案資料集，架構應有效

{
    "type": "/placeholder/type/uri",
    "status": 400,
    "title": "BadRequestError",
    "detail": "To enable profile datasets the schema should be valid"
}

當您嘗試為尚未為Real-time Customer Profile啟用的架構啟用配置式資料集時，將顯示此錯誤消息。 在啟用資料集之前，請確定架構包含union標籤。

必須有引用標識描述符

{
    "type": "/placeholder/type/uri",
    "status": 400,
    "title": "BadRequestError",
    "detail": "For a schema to be able to participate in union, if any of its 
      property is associated with a xdm:descriptorOneToOne descriptor, there must 
      be a xdm:descriptorReferenceIdentity descriptor for that property"
}

當您嘗試為Profile啟用模式時，將顯示此錯誤消息，其中一個屬性包含沒有引用標識描述符的關係描述符。 將參考身份描述符添加到相關的模式欄位以解決此錯誤。

引用標識描述符欄位和目標模式的名稱空間必須匹配

{
    "type": "/placeholder/type/uri",
    "status": 400,
    "title": "BadRequestError",
    "detail": "If both schemas from an already defined xdm:descriptorOneToOne 
      descriptor are promoted to union, and if there is a primary identity on one of 
      the schemas from the xdm:descriptorOneToOne descriptor, the 
      xdm:identityNamespace of the sourceSchema's descriptorReferenceIdentity and the 
      xdm:namespace field of the xdm:descriptorIdentity for the destinationSchema must 
      match"
}

為了啟用包含關係描述符的方案以便用於Profile，源欄位的命名空間和目標欄位的主命名空間必須相同。 當您嘗試啟用包含引用標識描述符的不匹配命名空間的架構時，將顯示此錯誤消息。 確保目標方案的標識欄位的xdm:namespace值與源欄位的引用標識描述符中xdm:identityNamespace屬性的值匹配，以解決此問題。

如需支援的身分名稱空間代碼清單，請參閱識別名稱空間概觀中有關標準名稱空間的章節。

接受標題錯誤

Schema Registry API中的大多數GET請求都需要「接受」標題，以便系統決定如何格式化回應。 以下是與「接受」標題相關的常見錯誤清單。 有關不同API請求的相容「接受」標題清單，請參閱方案註冊表開發人員指南中的相應章節。

必須接受標題參數

{
    "type": "/placeholder/type/uri",
    "status": 406,
    "title": "NotAcceptableError",
    "detail": "Accept header parameter is required"
}

當API請求中遺失「接受」標題時，會顯示此錯誤訊息。 在再次嘗試之前，請確定已包含「接受」標題。

未知接受提供的介質

{
    "type": "/placeholder/type/uri",
    "status": 406,
    "title": "NotAcceptableError",
    "detail": "Unknown Accept media supplied: xed+json"
}

當「接受」標題無效時，會顯示此錯誤訊息。 請確定您已正確輸入與您嘗試進行之API要求相容的「接受」標題，然後再再試一次。

可用的未知接受格式

{
    "type": "/placeholder/type/uri",
    "status": 406,
    "title": "NotAcceptableError",
    "detail": "Unknown Accept format available "
}

查找描述符時，如果「接受」標題提供不正確，則會顯示此錯誤消息。 在重試之前，請確保已正確輸入支援的描述符的接受標頭之一。

必須在「接受」標題中提供版本

{
    "type": "/placeholder/type/uri",
    "status": 400,
    "title": "BadRequestError",
    "detail": "version must be supplied in the accept header. Example: 
      application/vnd.adobe.xed-full-notext+json; version=1"
}

當「接受」標題中未包含版本號碼時，會顯示此錯誤訊息。 某些元素（如結構）在查找單個實例時需要指定版本。 包含版本號碼的「接受」標題看起來類似下列：

application/vnd.adobe.xed+json; version=1

如需支援的「接受」標題清單，請參閱Schema Registry開發人員指南中的接受標題一節。

「接受」標題中不能提供版本

{
    "type": "/placeholder/type/uri",
    "status": 400,
    "title": "BadRequestError",
    "detail": "version must not be supplied in the accept header. Example: 
      application/vnd.adobe.xed-full+json"
}

如果您在列出(GET)資源時嘗試在「接受」標題中包含版本，您會收到此錯誤。 只有在單一資源上嘗試查閱請求時，才需要版本。 從「接受」標題移除版本以解決錯誤。