在結構描述登入API中定義XDM欄位

所有Experience Data Model (XDM)欄位都是使用套用至其欄位型別的標準JSON結構描述限制來定義,以及針對Adobe Experience Platform強制執行的欄位名稱的其他限制。 結構描述登入API可讓您透過使用格式和選用限制來定義結構描述中的自訂欄位。 XDM欄位型別由欄位層級屬性meta:xdmType公開。

NOTE
meta:xdmType是系統產生的值,因此使用API時,您不需要將此屬性新增到欄位的JSON中(除了在建立自訂對應型別時)。 最佳實務是將JSON結構描述型別(例如stringinteger)搭配適當的最小/最大條件約束,如下表所示。

本指南會概述定義不同欄位型別的適當格式,包括那些具有選擇性屬性的欄位型別。 有關選擇性屬性和型別特定關鍵字的詳細資訊,請參閱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"
  }
}
NOTE
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"
}
IMPORTANT
如果未提供default值,且列舉欄位設定為required,則擷取時,遺失此欄位可接受值的任何記錄都將無法驗證。

數字 number

數字欄位由type: number表示,沒有其他必要屬性。

"sampleField": {
  "title": "Sample Number Field",
  "description": "An example number field.",
  "type": "number"
}
NOTE
number型別用於任何數值型別,可以是整數或浮點數,而integer型別則專門用於整數數字。 如需每種型別使用案例的詳細資訊,請參閱數值型別🔗的JSON結構描述檔案。

整數 integer

整數欄位由type: integer表示,沒有其他必要欄位。

"sampleField": {
  "title": "Sample Integer Field",
  "description": "An example integer field.",
  "type": "integer"
}
NOTE
雖然integer型別是專門參照整數型別,但number型別用於任何數值型別,可以是整數或浮點數。 如需每種型別使用案例的詳細資訊,請參閱數值型別🔗的JSON結構描述檔案。

您可以將minimummaximum屬性新增至定義,選擇性地限制整數的範圍。 結構描述產生器UI支援的其他數位型別只有integer個具有特定minimummaximum限制條件的型別,例如LongShortByte

"sampleField": {
  "title": "Sample Integer Field",
  "description": "An example integer field with added constraints.",
  "type": "integer",
  "minimum": 1,
  "maximum": 100
}

long

與透過結構描述產生器UI建立的Long欄位等同的是integer型別欄位,具有特定minimummaximum值(分別為-90071992547409929007199254740992)。

"sampleField": {
  "title": "Sample Long Field",
  "description": "An example long field.",
  "type": "integer",
  "minimum": -9007199254740992,
  "maximum": 9007199254740992
}

短整數 short

與透過結構描述產生器UI建立的Short欄位等同的是integer型別欄位,具有特定minimummaximum值(分別為-3276832768)。

"sampleField": {
  "title": "Sample Short Field",
  "description": "An example short field.",
  "type": "integer",
  "minimum": -32768,
  "maximum": 32768
}

位元組 byte

與透過結構描述產生器UI建立的位元組欄位相當的是integer型別欄位,具有特定的minimummaximum值(分別為-128128)。

"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
}
IMPORTANT
如果未提供default值,且布林欄位設定為required,則擷取時,任何遺失此欄位可接受值的記錄都將無法驗證。

日期 date

日期欄位由type: stringformat: 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: stringformat: 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: arrayitems物件表示,該物件定義陣列將接受的專案結構描述。

您可以使用基本型別(例如字串陣列)來定義陣列專案:

"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型別的欄位,其索引鍵集不受限制。 如同物件,對應有typeobject,但其meta:xdmType已明確設定為map

對應​ 不得 ​定義任何屬性。 它​ 必須 ​定義單一additionalProperties結構描述以說明對應中包含的值型別(每個對應只能包含單一資料型別)。 type值必須是stringinteger

例如,具有字串型別值的對應欄位會定義如下:

"sampleField": {
  "title": "Sample Map Field",
  "description": "An example map field.",
  "type": "object",
  "meta:xdmType": "map",
  "additionalProperties": {
    "type": "string"
  }
}

如需建立自訂對應欄位的詳細資訊,請參閱下節。

建立自訂地圖型別 custom-maps

為了在XDM中有效支援「類似對應」資料,物件可能會被設為mapmeta:xdmType註釋,以明確表示物件應像金鑰集未受限制一樣受到管理。 擷取至對應欄位的資料必須使用字串鍵,而且只能使用字串或整數值(由additionalProperties.type決定)。

XDM對於此儲存提示的使用會設定下列限制:

  • 對應型別必須屬於型別object
  • 對應型別不得有已定義的屬性(換言之,它們會定義「空白」物件)。
  • 對應型別必須包含additionalProperties.type欄位,描述可能放置在對應中的值: stringinteger

請確定您只在絕對必要時才使用對應型別欄位,因為這些欄位具有下列效能缺陷:

Platform使用者介面在擷取對應型別欄位索引鍵的方式上也有限制。 雖然物件型別欄位可以展開,但地圖會顯示為單一欄位。

後續步驟

本指南說明如何在API中定義不同的欄位型別。 如需如何格式化XDM欄位型別的詳細資訊,請參閱XDM欄位型別限制的指南。

recommendation-more-help
62e9ffd9-1c74-4cef-8f47-0d00af32fc07