在結構描述登入API中定義XDM欄位
所有Experience Data Model (XDM)欄位都是使用套用至其欄位型別的標準JSON結構描述限制來定義，以及針對Adobe Experience Platform強制執行的欄位名稱的其他限制。 結構描述登入API可讓您透過使用格式和選用限制來定義結構描述中的自訂欄位。 XDM欄位型別由欄位層級屬性meta:xdmType公開。
meta:xdmType是系統產生的值，因此使用API時，您不需要將此屬性新增到欄位的JSON中（除了在建立自訂對應型別時）。 最佳實務是將JSON結構描述型別（例如string和integer）搭配適當的最小/最大條件約束，如下表所示。本指南會概述定義不同欄位型別的適當格式，包括那些具有選擇性屬性的欄位型別。 有關選擇性屬性和型別特定關鍵字的詳細資訊，請參閱JSON結構描述檔案。
若要開始，請尋找所需的欄位型別，並使用提供的範常式式碼來建置您的API要求，以便建立欄位群組或建立資料型別。
字串 string
字串欄位由type: string表示。
"sampleField": {
"title": "Sample String Field",
"description": "An example string field.",
"type": "string"
}
您可選擇透過下列其他屬性，限制可為字串輸入哪些型別的值：
pattern：要限制的Regex模式。minLength：字串的最小長度。maxLength：字串的長度上限。
"sampleField": {
"title": "Sample String Field",
"description": "An example string field with added constraints.",
"type": "string",
"pattern": "^[A-Z]{2}$",
"maxLength": 2
}
URI uri
URI欄位由type: string表示，其中format屬性設定為uri。 不接受其他任何屬性。
"sampleField": {
"title": "Sample URI Field",
"description": "An example URI field.",
"type": "string",
"format": "uri"
}
列舉 enum
列舉欄位必須使用type: string，列舉值本身則在enum陣列下提供：
"sampleField": {
"title": "Sample Enum Field",
"description": "An example enum field.",
"type": "string",
"enum": [
"value1",
"value2",
"value3"
]
}
您可以選擇為meta:enum屬性下的每個值提供面向客戶的標籤，每個標籤都與enum下的對應值連線。
"sampleField": {
"title": "Sample Enum Field",
"description": "An example enum field with customer-facing labels.",
"type": "string",
"enum": [
"value1",
"value2",
"value3"
],
"meta:enum": {
"value1": "Value 1",
"value2": "Value 2",
"value3": "Value 3"
}
}
meta:enum值 不會 自行宣告列舉或驅動任何資料驗證。 在大多數情況下，meta:enum下提供的字串也會在enum下提供，以確保資料受到限制。 但是，在某些情況下，提供meta:enum時沒有對應的enum陣列。 如需詳細資訊，請參閱有關定義建議值的教學課程。您可以選擇提供default屬性，以指出若未提供值，欄位將會使用的預設enum值。
"sampleField": {
"title": "Sample Enum Field",
"description": "An example enum field with customer-facing labels and a default value.",
"type": "string",
"enum": [
"value1",
"value2",
"value3"
],
"meta:enum": {
"value1": "Value 1",
"value2": "Value 2",
"value3": "Value 3"
},
"default": "value1"
}
default值，且列舉欄位設定為required，則擷取時，遺失此欄位可接受值的任何記錄都將無法驗證。數字 number
數字欄位由type: number表示，沒有其他必要屬性。
"sampleField": {
"title": "Sample Number Field",
"description": "An example number field.",
"type": "number"
}
整數 integer
整數欄位由type: integer表示，沒有其他必要欄位。
"sampleField": {
"title": "Sample Integer Field",
"description": "An example integer field.",
"type": "integer"
}
您可以將minimum和maximum屬性新增至定義，選擇性地限制整數的範圍。 結構描述產生器UI支援的其他數位型別只有integer個具有特定minimum和maximum限制條件的型別，例如Long、Short和Byte。
"sampleField": {
"title": "Sample Integer Field",
"description": "An example integer field with added constraints.",
"type": "integer",
"minimum": 1,
"maximum": 100
}
長 long
與透過結構描述產生器UI建立的Long欄位等同的是integer型別欄位，具有特定minimum和maximum值（分別為-9007199254740992和9007199254740992）。
"sampleField": {
"title": "Sample Long Field",
"description": "An example long field.",
"type": "integer",
"minimum": -9007199254740992,
"maximum": 9007199254740992
}
短整數 short
與透過結構描述產生器UI建立的Short欄位等同的是integer型別欄位，具有特定minimum和maximum值（分別為-32768和32768）。
"sampleField": {
"title": "Sample Short Field",
"description": "An example short field.",
"type": "integer",
"minimum": -32768,
"maximum": 32768
}
位元組 byte
與透過結構描述產生器UI建立的位元組欄位相當的是integer型別欄位，具有特定的minimum和maximum值（分別為-128和128）。
"sampleField": {
"title": "Sample Byte Field",
"description": "An example byte field.",
"type": "integer",
"minimum": -128,
"maximum": 128
}
布林值 boolean
布林值欄位由type: boolean表示。
"sampleField": {
"title": "Sample Boolean Field",
"description": "An example boolean field.",
"type": "boolean"
}
您可以選擇提供當擷取期間未提供明確值時，欄位將使用的default值。
"sampleField": {
"title": "Sample Boolean Field",
"description": "An example boolean field with a default value.",
"type": "boolean",
"default": false
}
default值，且布林欄位設定為required，則擷取時，任何遺失此欄位可接受值的記錄都將無法驗證。日期 date
日期欄位由type: string和format: date表示。 您也可選擇提供examples陣列，以便在您想要為手動輸入資料的使用者顯示範例日期字串時運用。
"sampleField": {
"title": "Sample Date Field",
"description": "An example date field with an example array item.",
"type": "string",
"format": "date",
"examples": ["2004-10-23"]
}
日期時間 date-time
日期時間欄位由type: string和format: date-time表示。 您也可以選擇提供examples陣列，以便在您要顯示手動輸入資料之使用者的範例日期時間字串時運用。
"sampleField": {
"title": "Sample Datetime Field",
"description": "An example datetime field with an example array item.",
"type": "string",
"format": "date-time",
"examples": ["2004-10-23T12:00:00-06:00"]
}
陣列 array
陣列欄位由type: array和items物件表示，該物件定義陣列將接受的專案結構描述。
您可以使用基本型別（例如字串陣列）來定義陣列專案：
"sampleField": {
"title": "Sample Array Field",
"description": "An example array field using a primitive type.",
"type": "array",
"items": {
"type": "string"
}
}
您也可以透過$ref屬性參照資料型別的$id，根據現有的資料型別定義陣列專案。 下列是付款專案物件的陣列：
"sampleField": {
"title": "Sample Array Field",
"description": "An example array field using a data type reference.",
"type": "array",
"items": {
"$ref": "https://ns.adobe.com/xdm/data/paymentitem"
}
}
物件 object
物件欄位由type: object和定義結構描述欄位子屬性的properties物件表示。
在properties下定義的每個子欄位都可以使用任何基本值type來定義，或是透過指向相關資料型別$id的$ref屬性來參考現有的資料型別：
"sampleField": {
"title": "Sample Object Field",
"description": "An example object field.",
"type": "object",
"properties": {
"field1": {
"type": "string"
},
"field2": {
"$ref": "https://ns.adobe.com/xdm/common/measure"
}
}
}
您也可以透過參考資料型別來定義整個物件，前提是相關資料型別本身定義為type: object：
"sampleField": {
"title": "Sample Object Field",
"description": "An example object field using a data type reference.",
"$ref": "https://ns.adobe.com/xdm/common/phoneinteraction"
}
地圖 map
對應欄位基本上是object型別的欄位，其索引鍵集不受限制。 如同物件，對應有type值object，但其meta:xdmType已明確設定為map。
對應 不得 定義任何屬性。 它 必須 定義單一additionalProperties結構描述以說明對應中包含的值型別（每個對應只能包含單一資料型別）。 type值必須是string或integer。
例如，具有字串型別值的對應欄位會定義如下：
"sampleField": {
"title": "Sample Map Field",
"description": "An example map field.",
"type": "object",
"meta:xdmType": "map",
"additionalProperties": {
"type": "string"
}
}
如需建立自訂對應欄位的詳細資訊，請參閱下節。
建立自訂地圖型別 custom-maps
為了在XDM中有效支援「類似對應」資料，物件可能會被設為map的meta:xdmType註釋，以明確表示物件應像金鑰集未受限制一樣受到管理。 擷取至對應欄位的資料必須使用字串鍵，而且只能使用字串或整數值（由additionalProperties.type決定）。
XDM對於此儲存提示的使用會設定下列限制：
- 對應型別必須屬於型別
object。 - 對應型別不得有已定義的屬性（換言之，它們會定義「空白」物件）。
- 對應型別必須包含
additionalProperties.type欄位，描述可能放置在對應中的值：string或integer。
請確定您只在絕對必要時才使用對應型別欄位，因為這些欄位具有下列效能缺陷：
- 來自Adobe Experience Platform查詢服務的回應時間，1億筆記錄會從3秒降低到10秒。
- 地圖必須少於16個索引鍵，否則可能會進一步降低。
Platform使用者介面在擷取對應型別欄位索引鍵的方式上也有限制。 雖然物件型別欄位可以展開，但地圖會顯示為單一欄位。