Gestire i valori suggeriti nell’API

Per qualsiasi campo stringa in Experience Data Model (XDM), puoi definire un enum che vincola i valori che il campo può acquisire a un set predefinito. Se tenti di acquisire dati in un campo enum e il valore non corrisponde a nessuno di quelli definiti nella relativa configurazione, l’acquisizione verrà negata.

A differenza degli enum, aggiunta valori consigliati in un campo stringa non vincola i valori che può acquisire. Al contrario, i valori suggeriti influenzano i valori predefiniti disponibili nel Interfaccia utente di segmentazione quando si include il campo stringa come attributo.

NOTA

Si verifica un ritardo di circa cinque minuti perché i valori consigliati aggiornati di un campo si riflettano nell’interfaccia utente Segmentazione.

Questa guida illustra come gestire i valori suggeriti utilizzando API del Registro di sistema dello schema. Per i passaggi da seguire nell’interfaccia utente di Adobe Experience Platform, consulta la sezione Guida all’interfaccia utente per enum e valori consigliati.

Prerequisiti

Questa guida presuppone che tu abbia familiarità con gli elementi della composizione dello schema in XDM e che sia in grado di utilizzare l’API del Registro di sistema dello schema per creare e modificare le risorse XDM. Per un’introduzione, fai riferimento alla seguente documentazione:

Si consiglia inoltre vivamente di rivedere il regole di evoluzione per enum e valori suggeriti se stai aggiornando i campi esistenti. Se gestisci i valori suggeriti per gli schemi che partecipano a un'unione, consulta la sezione regole per l’unione di enum e valori consigliati.

Composizione

Nell’API, i valori vincolati per un enum i campi sono rappresentati da un enum mentre un meta:enum L'oggetto fornisce nomi visualizzati descrittivi per tali valori:

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

Per i campi enum, il Registro di sistema dello schema non consente meta:enum da estendere oltre i valori di cui enum, poiché il tentativo di acquisire valori stringa al di fuori di tali vincoli non passerebbe la convalida.

In alternativa, è possibile definire un campo stringa che non contiene un enum utilizza solo meta:enum oggetto da indicare valori consigliati:

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

Poiché la stringa non ha un enum array per definire vincoli, i relativi meta:enum può essere estesa per includere nuovi valori.

Aggiungere valori consigliati a un campo standard

Per estendere meta:enum di un campo stringa standard, è possibile creare un descrittore del nome descrittivo per il campo in questione in uno schema specifico.

NOTA

I valori consigliati per i campi stringa possono essere aggiunti solo a livello di schema. In altre parole, l'estensione del meta:enum di un campo standard in uno schema non influisce sugli altri schemi che utilizzano lo stesso campo standard.

La seguente richiesta aggiunge valori consigliati allo standard eventType (fornito dal Classe ExperienceEvent XDM) per lo schema identificato in 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"
          }
        }
      }'

Dopo aver applicato il descrittore, il Registro di sistema dello schema risponde con quanto segue durante il recupero dello schema (risposta troncata per lo spazio):

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

Se il campo standard contiene già valori in meta:enum, i nuovi valori del descrittore non sovrascrivono i campi esistenti e vengono aggiunti al loro posto:

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

Gestione dei valori consigliati per un campo personalizzato

Per gestire meta:enum di un campo personalizzato, è possibile aggiornare la classe principale, il gruppo di campi o il tipo di dati del campo tramite una richiesta PATCH.

AVVERTENZA

A differenza dei campi standard, l’ meta:enum di un campo personalizzato influisce su tutti gli altri schemi che utilizzano tale campo. Se non desideri che le modifiche si propaghino tra gli schemi, considera invece la creazione di una nuova risorsa personalizzata:

La seguente richiesta aggiorna il meta:enum di un campo "livello fedeltà" fornito da un tipo di dati personalizzato:

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

Dopo aver applicato la modifica, il Registro di sistema dello schema risponde con quanto segue durante il recupero dello schema (risposta troncata per lo spazio):

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

Passaggi successivi

Questa guida illustra come gestire i valori consigliati per i campi stringa nell’API del Registro di sistema dello schema. Consulta la guida su definizione di campi personalizzati nell’API per ulteriori informazioni su come creare diversi tipi di campi.

In questa pagina