Gestire i valori suggeriti nell’API

Ultimo aggiornamento: 16 luglio 2024
  • Argomenti:

Creato per:

  • Sviluppatore

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, l'aggiunta di valori suggeriti a un campo stringa non vincola i valori che può acquisire. Al contrario, i valori suggeriti influiscono sui valori predefiniti disponibili nell'Interfaccia utente segmentazione quando si include il campo stringa come attributo.

NOTE
Nell’interfaccia utente di segmentazione viene rilevato un ritardo di circa cinque minuti rispetto ai valori consigliati aggiornati di un campo.

Questa guida illustra come gestire i valori suggeriti utilizzando l'API Schema Registry. Per informazioni su come eseguire questa operazione nell'interfaccia utente di Adobe Experience Platform, vedere la Guida dell'interfaccia utente sulle enumerazioni e i 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 le regole di evoluzione per le enumerazioni e i valori suggeriti se si stanno aggiornando i campi esistenti. Se gestisci i valori suggeriti per gli schemi che partecipano a un'unione, consulta le regole per unire enum e valori suggeriti.

Composizione

Nell'API, i valori vincolati per un campo enum sono rappresentati da un array enum, mentre un oggetto meta:enum 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 dello schema non consente l'estensione di meta:enum oltre i valori specificati in 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 array enum e utilizza solo l'oggetto meta:enum per indicare valori suggeriti:

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

Poiché la stringa non dispone di un array enum per definire i vincoli, è possibile estendere la relativa proprietà meta:enum per includere nuovi valori.

Aggiungere valori suggeriti a un campo standard

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

NOTE
I valori suggeriti per i campi stringa possono essere aggiunti solo a livello di schema. In altre parole, l'estensione di 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 al campo standard eventType (fornito dalla 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 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"
      }
    }
  }
}
NOTE
Se il campo standard contiene già valori in meta:enum, i nuovi valori del descrittore non sovrascrivono i campi esistenti e vengono aggiunti in:
"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"
   }
}

Gestire i valori suggeriti per un campo personalizzato

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.

WARNING
A differenza dei campi standard, l'aggiornamento di 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 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 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"
      }
    }
  }
}