API에서 제안된 값 관리

XDM(Experience Data Model)의 모든 문자열 필드에 대해 필드가 수집할 수 있는 값을 사전 정의된 집합으로 제한하는 enum ​을 정의할 수 있습니다. 열거형 필드에 데이터를 수집하려고 하는데 값이 해당 구성에 정의된 값과 일치하지 않으면 수집이 거부됩니다.

열거형과 달리 문자열 필드에 제안 값 ​을 추가해도 수집할 수 있는 값이 제한되지 않습니다. 대신 제안된 값은 문자열 필드를 특성으로 포함할 때 세그먼테이션 UI에서 사용할 수 있는 사전 정의된 값에 영향을 줍니다.

이 안내서에서는 스키마 레지스트리 API를 사용하여 제안된 값을 관리하는 방법을 다룹니다. Adobe Experience Platform 사용자 인터페이스에서 이 작업을 수행하는 방법에 대한 단계는 열거형 및 제안 값에 대한 UI 안내서를 참조하십시오.

전제 조건

이 안내서에서는 사용자가 XDM의 스키마 구성 요소 및 스키마 레지스트리 API를 사용하여 XDM 리소스를 만들고 편집하는 방법을 잘 알고 있다고 가정합니다. 소개가 필요한 경우 다음 설명서를 참조하십시오.

기존 필드를 업데이트하는 경우 열거형 및 제안 값에 대한 진화 규칙을 검토하는 것이 좋습니다. 유니온에 참여하는 스키마에 대한 제안 값을 관리하는 경우 열거형과 제안 값 병합 규칙을 참조하십시오.

컴포지션

API에서 enum 필드에 대한 제약 조건 값은 enum 배열로 표시되지만 meta:enum 개체는 이러한 값에 대해 친숙한 표시 이름을 제공합니다.

"exampleStringField": {
  "type": "string",
  "enum": [
    "value1",
    "value2",
    "value3"
  ],
  "meta:enum": {
    "value1": "Value 1",
    "value2": "Value 2",
    "value3": "Value 3"
  },
  "default": "value1"
}

열거형 필드의 경우, 해당 제약 조건 외부의 문자열 값을 수집하려고 하면 유효성 검사를 통과하지 못하므로 스키마 레지스트리에서 meta:enum을(를) enum에 제공된 값 이상으로 확장할 수 없습니다.

또는 enum 배열이 포함되지 않고 meta:enum 개체만 사용하여 제안 값 ​을(를) 나타내는 문자열 필드를 정의할 수 있습니다.

"exampleStringField": {
  "type": "string",
  "meta:enum": {
    "value1": "Value 1",
    "value2": "Value 2",
    "value3": "Value 3"
  },
  "default": "value1"
}

문자열에 제약 조건을 정의하는 enum 배열이 없으므로 해당 meta:enum 속성을 확장하여 새 값을 포함할 수 있습니다.

표준 필드에 제안 값 추가 add-suggested-standard

표준 문자열 필드의 meta:enum을(를) 확장하려면 특정 스키마에서 해당 필드에 대한 친숙한 이름 설명자를 만들 수 있습니다.

다음 요청은 sourceSchema에서 식별된 스키마의 표준 eventType 필드(XDM ExperienceEvent 클래스에서 제공)에 제안된 값을 추가합니다.

curl -X POST \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/descriptors \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -H 'Content-Type: application/json' \
  -d '{
        "@type": "xdm:alternateDisplayInfo",
        "sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
        "sourceProperty": "/eventType",
        "title": {
            "en_us": "Enum Event Type"
        },
        "description": {
            "en_us": "Event type field with soft enum values"
        },
        "meta:enum": {
          "eventA": {
            "en_us": "Event Type A"
          },
          "eventB": {
            "en_us": "Event Type B"
          }
        }
      }'

설명자를 적용한 후 스키마를 검색할 때 스키마 레지스트리는 다음과 같이 응답합니다(공간에 대해 잘린 응답).

{
  "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
  "title": "Example Schema",
  "properties": {
    "eventType": {
      "type":"string",
      "title": "Enum Event Type",
      "description": "Event type field with soft enum values.",
      "meta:enum": {
        "customEventA": "Custom Event Type A",
        "customEventB": "Custom Event Type B"
      }
    }
  }
}

"standardField": {
   "type":"string",
   "title": "Example standard enum field",
   "description": "Standard field with existing enum values.",
   "meta:enum": {
       "standardEventA": "Standard Event Type A",
       "standardEventB": "Standard Event Type B",
       "customEventA": "Custom Event Type A",
       "customEventB": "Custom Event Type B"
   }
}

사용자 정의 필드에 대한 제안 값 관리 suggested-custom

사용자 지정 필드의 meta:enum을(를) 관리하려면 PATCH 요청을 통해 필드의 상위 클래스, 필드 그룹 또는 데이터 형식을 업데이트할 수 있습니다.

다음 요청은 사용자 지정 데이터 형식에서 제공한 "충성도 수준" 필드의 meta:enum을(를) 업데이트합니다.

curl -X PATCH \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/datatypes/_{TENANT_ID}.datatypes.8779fd45d6e4eb074300023a439862bbba359b60d451627a \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -H 'Content-Type: application/json' \
  -d '[
        {
          "op": "replace",
          "path": "/loyaltyLevel/meta:enum",
          "value": {
            "ultra-platinum": "Ultra Platinum",
            "platinum": "Platinum",
            "gold": "Gold",
            "silver": "Silver",
            "bronze": "Bronze"
          }
        }
      ]'

변경 사항을 적용한 후 스키마 검색 시 스키마 레지스트리는 다음과 같이 응답합니다(응답은 공백으로 잘림).

{
  "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
  "title": "Example Schema",
  "properties": {
    "loyaltyLevel": {
      "type":"string",
      "title": "Loyalty Level",
      "description": "The loyalty program tier that this customer qualifies for.",
      "meta:enum": {
        "ultra-platinum": "Ultra Platinum",
        "platinum": "Platinum",
        "gold": "Gold",
        "silver": "Silver",
        "bronze": "Bronze"
      }
    }
  }
}

다음 단계

이 안내서에서는 스키마 레지스트리 API의 문자열 필드에 대해 제안된 값을 관리하는 방법을 다룹니다. 다른 필드 형식을 만드는 방법에 대한 자세한 내용은 API에서 사용자 지정 필드 정의에 대한 안내서를 참조하십시오.