Verwalten von vorgeschlagenen Werten in der API

Für jedes Zeichenfolgenfeld im Experience-Datenmodell (XDM) können Sie einen enum definieren, der die Werte, die das Feld erfassen kann, auf einen vordefinierten Satz beschränkt. Wenn Sie versuchen, Daten in ein Enum-Feld zu erfassen und der Wert mit keinem der in der Konfiguration definierten Werte übereinstimmt, wird die Aufnahme verweigert.

Im Gegensatz zu Auflistungen schränkt das Hinzufügen von empfohlenen Werten zu einem Zeichenfolgenfeld nicht die Werte ein, die aufgenommen werden können. Stattdessen wirken sich die vorgeschlagenen Werte darauf aus, welche vordefinierten Werte in der Segmentierungsbenutzeroberfläche verfügbar sind, wenn das Zeichenfolgenfeld als Attribut eingefügt wird.

In diesem Handbuch wird beschrieben, wie Sie vorgeschlagene Werte mit der Schema Registry-API verwalten. Anweisungen dazu finden Sie in der Benutzeroberfläche von Adobe Experience Platform im UI-Handbuch zu Auflistungen und empfohlenen Werten.

Voraussetzungen

In diesem Handbuch wird davon ausgegangen, dass Sie mit den Elementen der Schemakomposition in XDM und der Verwendung der Schema Registry-API zum Erstellen und Bearbeiten von XDM-Ressourcen vertraut sind. Wenn Sie eine Einführung benötigen, lesen Sie die folgende Dokumentation:

Es wird außerdem dringend empfohlen, die Evolutionsregeln für Auflistungen und empfohlene Werte zu überprüfen, wenn Sie vorhandene Felder aktualisieren. Wenn Sie empfohlene Werte für Schemas verwalten, die an einer Vereinigung teilnehmen, lesen Sie die Regeln für das Zusammenführen von Auflistungen und vorgeschlagenen Werten.

Komposition

In der API werden die eingeschränkten Werte für ein Feld enum durch ein Array enum dargestellt, während ein Objekt meta:enum Anzeigenamen für diese Werte bereitstellt:

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

Bei Enum-Feldern erlaubt die Schema Registry nicht, meta:enum über die unter enum angegebenen Werte hinaus zu erweitern, da der Versuch, Zeichenfolgenwerte außerhalb dieser Begrenzungen zu erfassen, die Validierung nicht bestehen würde.

Alternativ können Sie ein Zeichenfolgenfeld definieren, das kein "enum"-Array enthält und nur das "meta:enum"-Objekt verwendet, um empfohlene Werte zu kennzeichnen:

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

Da die Zeichenfolge nicht über ein enum -Array verfügt, um Begrenzungen zu definieren, kann ihre meta:enum -Eigenschaft um neue Werte erweitert werden.

Hinzufügen empfohlener Werte zu einem Standardfeld add-suggested-standard

Um den meta:enum eines Standard-Zeichenfolgenfelds zu erweitern, können Sie einen Anzeigenamendeskriptor für das betreffende Feld in einem bestimmten Schema erstellen.

Mit der folgenden Anfrage werden dem Standardfeld eventType (bereitgestellt von der XDM ExperienceEvent-Klasse) empfohlene Werte für das unter sourceSchema identifizierte Schema hinzugefügt:

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

Nach Anwendung des Deskriptors antwortet die Schema Registry beim Abrufen des Schemas mit Folgendem (Antwort aus Platzgründen abgeschnitten):

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

Verwalten von vorgeschlagenen Werten für ein benutzerdefiniertes Feld suggested-custom

Um die meta:enum eines benutzerdefinierten Felds zu verwalten, können Sie die übergeordnete Klasse, Feldergruppe oder den Datentyp des Felds über eine PATCH-Anfrage aktualisieren.

Mit der folgenden Anfrage wird der meta:enum eines von einem benutzerdefinierten Datentyp bereitgestellten Felds "Treuestufe"aktualisiert:

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

Nach der Anwendung der Änderung antwortet die Schema Registry beim Abrufen des Schemas mit Folgendem (Antwort aus Platzgründen abgeschnitten):

{
  "$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ächste Schritte

In diesem Handbuch wurde beschrieben, wie Sie empfohlene Werte für Zeichenfolgenfelder in der Schema Registry-API verwalten. Weiterführende Informationen zum Erstellen verschiedener Feldtypen finden Sie im Handbuch zum Definieren benutzerdefinierter Felder in der API .