Hantera föreslagna värden i API

För alla strängfält i Experience Data Model (XDM) kan du definiera en enum som begränsar de värden som fältet kan importera till en fördefinierad uppsättning. Om du försöker importera data till ett uppräkningsfält och värdet inte matchar någon av dem som definierats i konfigurationen, nekas intag.

Om du till skillnad från enum lägger till föreslagna värden i ett strängfält begränsas inte de värden som det kan importera. Föreslagna värden påverkar i stället vilka fördefinierade värden som är tillgängliga i segmenteringsgränssnittet när strängfältet inkluderas som ett attribut.

Den här guiden beskriver hur du hanterar föreslagna värden med API:t för schemaregister. Anvisningar om hur du gör detta i Adobe Experience Platform användargränssnitt finns i användargränssnittshandboken på enum och föreslagna värden.

Förhandskrav

I den här handboken förutsätts du känna till elementen i schemakompositionen i XDM och hur du använder API:t för schemaregister för att skapa och redigera XDM-resurser. Om du behöver en introduktion läser du i följande dokumentation:

Vi rekommenderar även att du granskar everingsreglerna för enum och föreslagna värden om du uppdaterar befintliga fält. Om du hanterar föreslagna värden för scheman som deltar i en union läser du reglerna för att sammanfoga enum och föreslagna värden.

Disposition

I API representeras de begränsade värdena för ett enum-fält av en enum-array, medan ett meta:enum-objekt tillhandahåller egna visningsnamn för dessa värden:

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

För uppräkningsfält tillåter schemaregistret inte att meta:enum utökas utöver de värden som anges i enum, eftersom ett försök att importera strängvärden utanför dessa begränsningar inte klarar valideringen.

Du kan också definiera ett strängfält som inte innehåller en enum-array och bara använder meta:enum-objektet för att ange föreslagna värden:

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

Eftersom strängen inte har någon enum-matris för att definiera begränsningar, kan egenskapen meta:enum utökas så att den innehåller nya värden.

Lägga till föreslagna värden i ett standardfält add-suggested-standard

Om du vill utöka meta:enum för ett standardsträngfält kan du skapa en egen namnbeskrivning för fältet i fråga i ett visst schema.

Följande begäran lägger till föreslagna värden i standardfältet eventType (tillhandahålls av klassen XDM ExperienceEvent) för det schema som identifieras under sourceSchema:

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"
          }
        }
      }'

När du har använt beskrivningen svarar schemaregistret med följande när schemat hämtas (svaret trunkeras för utrymme):

{
  "$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"
   }
}

Hantera föreslagna värden för ett anpassat fält suggested-custom

Om du vill hantera meta:enum för ett anpassat fält kan du uppdatera fältets överordnade klass, fältgrupp eller datatyp via en PATCH-begäran.

Följande begäran uppdaterar meta:enum för ett"lojalitetsnivåfält" som tillhandahålls av en anpassad datatyp:

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"
          }
        }
      ]'

När ändringen har tillämpats svarar schemaregistret med följande när schemat hämtas (svaret trunkeras för utrymme):

{
  "$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"
      }
    }
  }
}

Nästa steg

I den här guiden beskrivs hur du hanterar föreslagna värden för strängfält i API:t för schemaregister. Mer information om hur du skapar olika fälttyper finns i guiden definierar anpassade fält i API.