설명서 Experience Platform 경험 데이터 모델(XDM) 안내서

스키마 레지스트리 API에서 XDM 필드 정의

Last update: Wed Mar 15 2023 00:00:00 GMT+0000 (Coordinated Universal Time)

주제:
Schemas

작성 대상:

Developer

모든 XDM(경험 데이터 모델) 필드는 표준을 사용하여 정의됩니다 JSON 스키마 해당 필드 유형에 적용되는 제약 조건(Adobe Experience Platform에서 적용하는 필드 이름에 대한 추가 제약 조건 포함). 스키마 레지스트리 API를 사용하면 형식 및 선택적 제약 조건을 사용하여 스키마에서 사용자 지정 필드를 정의할 수 있습니다. XDM 필드 유형은 필드 수준 속성에 의해 노출됩니다. meta:xdmType.

NOTE

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: 를 제한하는 정규 표현식 패턴입니다.
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

While integer 형식은 특히 정수를 참조합니다. number 유형 정수 또는 부동 소수점 숫자 등 모든 숫자 유형에 사용됩니다. 다음을 참조하십시오. 숫자 유형에 대한 JSON 스키마 설명서 각 유형의 사용 사례에 대한 자세한 정보를 제공합니다.

을 추가하여 정수 범위를 선택적으로 제한할 수 있습니다 minimum 및 maximum 속성을 정의로 설정합니다. 스키마 빌더 UI에서 지원하는 몇 가지 다른 숫자 유형은 다음과 같습니다 integer 특정 유형 minimum 및 maximum 제한(예: ) 길게, 짧음, 및 바이트.

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

길게 long

의 등가물 길게 스키마 빌더 UI를 통해 생성된 필드는 integer 필드 입력 특정하게 minimum 및 maximum 값 (-9007199254740992 및 9007199254740992, 각각 참조).

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

짧음 short

의 등가물 짧음 스키마 빌더 UI를 통해 생성된 필드는 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
}

IMPORTANT

없는 경우 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"]
}

DateTime date-time

DateTime 필드는 로 표시됩니다. 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"
  }
}

를 참조하여 기존 데이터 유형을 기반으로 배열 항목을 정의할 수도 있습니다. $id 다음을 통해 데이터 유형: $ref 속성. 다음은 배열입니다 결제 항목 개체:

"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 및 a properties 스키마 필드의 하위 속성을 정의하는 개체입니다.

아래에 정의된 각 하위 필드 properties 모든 기본 항목을 사용하여 정의할 수 있습니다. type 또는 를 통해 기존 데이터 유형 참조 $ref 을(를) 가리키는 속성 $id 해당 데이터 유형:

"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 필드 제한 없는 키 세트 포함 오브젝트와 마찬가지로, 지도에 type 값 object, 그러나 해당 meta:xdmType 이(가) 명시적으로 다음으로 설정됨: map.

맵 은(는) 해서는 안 됨 속성을 정의합니다. It 필수 단일 정의 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에서 "맵과 유사한" 데이터를 효율적으로 지원하기 위해 개체에는 meta:xdmType 을 로 설정 map 키 세트가 구속되지 않은 것처럼 객체를 관리해야 한다는 점을 명확히 하기 위해 맵 필드에 수집되는 데이터는 문자열 키를 사용해야 하며 문자열 또는 정수 값(에 의해 결정됨)만 사용해야 합니다. additionalProperties.type).

XDM에서는 이 스토리지 힌트의 사용에 대해 다음과 같은 제한 사항을 적용합니다.

맵 유형은 유형이어야 합니다. object.
맵 유형에는 속성이 정의되지 않아야 합니다(즉, "빈" 개체를 정의함).
맵 유형에 다음을 포함해야 함: additionalProperties.type 맵 내에 배치할 수 있는 값을 설명하는 필드 string 또는 integer.

맵 유형 필드는 다음과 같은 성능 단점이 있으므로 반드시 필요한 경우에만 사용해야 합니다.

다음에서의 응답 시간: Adobe Experience Platform 쿼리 서비스 1억 개의 레코드에 대해 3초에서 10초로 감소합니다.
맵의 키가 16개 미만이어야 합니다. 그렇지 않으면 더 이상 성능이 저하될 수 있습니다.

Platform 사용자 인터페이스에서도 맵 유형 필드의 키를 추출하는 방법에 제한이 있습니다. 개체 유형 필드는 확장할 수 있지만 맵은 대신 단일 필드로 표시됩니다.

다음 단계

이 안내서에서는 API에서 다양한 필드 유형을 정의하는 방법을 다룹니다. XDM 필드 유형의 서식이 지정되는 방법에 대한 자세한 내용은 XDM 필드 유형 제약 조건.

recommendation-more-help

62e9ffd9-1c74-4cef-8f47-0d00af32fc07