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 delle enumerazioni, aggiungere valori suggeriti in un campo stringa non vincola i valori che può acquisire. I valori suggeriti influiscono invece sui valori predefiniti disponibili nel Interfaccia utente di segmentazione quando si include il campo stringa come attributo.
Questa guida illustra come gestire i valori suggeriti utilizzando API del registro dello schema. Per informazioni su come eseguire questa operazione nell’interfaccia utente di Adobe Experience Platform, consulta Guida dell’interfaccia utente su enum e valori suggeriti.
Prerequisiti
Questa guida presuppone che tu abbia familiarità con gli elementi della composizione dello schema in XDM e su come utilizzare l’API Schema Registry per creare e modificare le risorse XDM. Se hai bisogno di un’introduzione, consulta la seguente documentazione:
Si consiglia inoltre vivamente di rivedere regole di evoluzione per enum e valori suggeriti se stai aggiornando campi esistenti. Se gestisci i valori suggeriti per gli schemi che partecipano a un’unione, consulta la sezione regole per l'unione di enumerazioni e valori suggeriti.
Composizione
Nell’API, i valori vincolati per un’ enum sono rappresentati da un enum , mentre un meta:enum L'oggetto fornisce nomi 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 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 supererebbe la convalida.
In alternativa, è possibile definire un campo stringa che non contiene un enum e utilizza solo il meta:enum oggetto da indicare valori suggeriti:
"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 i vincoli, i relativi meta:enum può essere estesa per includere nuovi valori.
Aggiungere valori suggeriti a un campo standard add-suggested-standard
Per estendere meta:enum di un campo stringa standard, puoi creare un descrittore del nome descrittivo per il campo in questione in uno schema specifico.
meta:enum di un campo standard in uno schema non influisce su altri schemi che utilizzano lo stesso campo standard.La richiesta seguente aggiunge i valori suggeriti allo standard eventType campo (fornito da Classe XDM ExperienceEvent) 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 dello schema risponde con quanto segue durante il recupero dello schema (risposta troncata per motivi di 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"
}
}
}
}
meta:enum, i nuovi valori del descrittore non sovrascrivono i campi esistenti e vengono aggiunti su:| code language-json |
|---|
|
Gestire i valori suggeriti per un campo personalizzato suggested-custom
Per gestire meta:enum di un campo personalizzato, è possibile aggiornare la classe padre, il gruppo di campi o il tipo di dati del campo tramite una richiesta PATCH.
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 schemi, puoi creare una nuova risorsa personalizzata:La richiesta seguente aggiorna il meta:enum di un campo "livello di 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 dello schema risponde con quanto segue durante il recupero dello schema (risposta troncata per motivi di 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 Schema Registry. Consulta la guida su definizione dei campi personalizzati nell’API per ulteriori informazioni su come creare diversi tipi di campi.