Documentatie Experience Platform Handleiding voor Experience Data Model (XDM)

XDM-velden definiëren in de API voor het schemaregister

Last update: Tue Jul 16 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

Onderwerpen:

Gemaakt voor:

Ontwikkelaar

Alle gebieden van de Gegevens van de Ervaring Model (XDM) worden bepaald gebruikend de standaard 🔗 beperkingen van het Schema JSON die op hun gebiedstype van toepassing zijn, met extra beperkingen voor gebiedsnamen die door Adobe Experience Platform worden afgedwongen. Met de API voor het schemaregister kunt u aangepaste velden in uw schema's definiëren met behulp van indelingen en optionele beperkingen. XDM-veldtypen worden weergegeven door het kenmerk op veldniveau, meta:xdmType .

NOTE

meta:xdmType is een systeem-geproduceerde waarde, en daarom wordt u vereist om dit bezit aan JSON voor uw gebied toe te voegen wanneer het gebruiken van API (behalve wanneer het creëren van de types van douanekaart). De beste manier is om JSON-schematypen (zoals string en integer ) te gebruiken met de juiste min/max-beperkingen zoals gedefinieerd in de onderstaande tabel.

In deze handleiding wordt de juiste opmaak beschreven voor het definiëren van verschillende veldtypen, inclusief die met optionele eigenschappen. Meer informatie betreffende facultatieve eigenschappen en type-specifieke sleutelwoorden is beschikbaar door de documentatie van het Schema JSON.

Om te beginnen, het gewenste gebiedstype te vinden en de steekproefcode te gebruiken die wordt verstrekt om uw API verzoek voor te bouwen creërend een gebiedsgroepof creërend een gegevenstype.

String string

String -velden worden aangegeven door type: string .

"sampleField": {
  "title": "Sample String Field",
  "description": "An example string field.",
  "type": "string"
}

U kunt desgewenst beperken welke soorten waarden voor de tekenreeks kunnen worden ingevoerd via de volgende aanvullende eigenschappen:

pattern: Een regex-patroon dat moet worden beperkt.
minLength: een minimumlengte voor de tekenreeks.
maxLength: Een maximumlengte voor de tekenreeks.

"sampleField": {
  "title": "Sample String Field",
  "description": "An example string field with added constraints.",
  "type": "string",
  "pattern": "^[A-Z]{2}$",
  "maxLength": 2
}

URI uri

URI -velden worden aangegeven door type: string met een eigenschap format ingesteld op uri . Er worden geen andere eigenschappen geaccepteerd.

"sampleField": {
  "title": "Sample URI Field",
  "description": "An example URI field.",
  "type": "string",
  "format": "uri"
}

Enum enum

Enum -velden moeten type: string gebruiken, waarbij de opsommingswaarden zelf onder een enum -array worden opgegeven:

"sampleField": {
  "title": "Sample Enum Field",
  "description": "An example enum field.",
  "type": "string",
  "enum": [
      "value1",
      "value2",
      "value3"
  ]
}

U kunt desgewenst labels voor klanten opgeven voor elke waarde onder een eigenschap meta:enum , waarbij elk label onder enum wordt toegepast op een corresponderende waarde.

"sampleField": {
  "title": "Sample Enum Field",
  "description": "An example enum field with customer-facing labels.",
  "type": "string",
  "enum": [
      "value1",
      "value2",
      "value3"
  ],
  "meta:enum": {
      "value1": "Value 1",
      "value2": "Value 2",
      "value3": "Value 3"
  }
}

NOTE

De meta:enum waarde verklaart geen opsomming of drijft om het even welke gegevensbevestiging op zijn. In de meeste gevallen worden onder meta:enum verschafte tekenreeksen ook onder enum opgegeven om ervoor te zorgen dat er beperkingen gelden voor gegevens. Er zijn echter enkele gebruiksgevallen waarin meta:enum wordt geleverd zonder overeenkomende enum -array. Zie het leerprogramma op bepalend gesuggereerde waardenvoor meer informatie.

U kunt desgewenst een eigenschap default opgeven die de standaardwaarde enum aangeeft die het veld gebruikt wanneer geen waarde wordt opgegeven.

"sampleField": {
  "title": "Sample Enum Field",
  "description": "An example enum field with customer-facing labels and a default value.",
  "type": "string",
  "enum": [
      "value1",
      "value2",
      "value3"
  ],
  "meta:enum": {
      "value1": "Value 1",
      "value2": "Value 2",
      "value3": "Value 3"
  },
  "default": "value1"
}

IMPORTANT

Als er geen default -waarde is opgegeven en het opsommingsveld is ingesteld op required , zal een record waarin een geaccepteerde waarde voor dit veld ontbreekt, de validatie tijdens het invoeren mislukken.

Number number

Nummervelden worden aangegeven door type: number en hebben geen andere vereiste eigenschappen.

"sampleField": {
  "title": "Sample Number Field",
  "description": "An example number field.",
  "type": "number"
}

NOTE

number types worden gebruikt voor om het even welk numeriek type, of gehelen of drijvende puntaantallen, terwijl integer typesspecifiek voor integrale aantallen worden gebruikt. Verwijs naar de documentatie van het Schema JSON over numerieke typesvoor meer informatie over de gebruiksgevallen voor elk type.

Integer integer

Integer -velden worden aangegeven door type: integer en hebben geen andere vereiste velden.

"sampleField": {
  "title": "Sample Integer Field",
  "description": "An example integer field.",
  "type": "integer"
}

NOTE

Hoewel integer types specifiek naar integrale aantallen verwijzen, number typesworden gebruikt voor om het even welk numeriek type, of gehelen of drijvende puntaantallen. Verwijs naar de documentatie van het Schema JSON over numerieke typesvoor meer informatie over de gebruiksgevallen voor elk type.

U kunt optioneel het bereik van het gehele getal beperken door eigenschappen minimum en maximum aan de definitie toe te voegen. Verschillende andere numerieke typen die door de Schema Builder-gebruikersinterface worden ondersteund, zijn integer -typen met specifieke minimum - en maximum -beperkingen, zoals Long , Short en Byte .

"sampleField": {
  "title": "Sample Integer Field",
  "description": "An example integer field with added constraints.",
  "type": "integer",
  "minimum": 1,
  "maximum": 100
}

Long long

Het equivalent van een Long gebied dat door de Bouwer van het Schema UI wordt gecreeerd is een integer typegebiedmet specifieke minimum en maximum waarden (-9007199254740992 en 9007199254740992, respectievelijk).

"sampleField": {
  "title": "Sample Long Field",
  "description": "An example long field.",
  "type": "integer",
  "minimum": -9007199254740992,
  "maximum": 9007199254740992
}

Short short

Het equivalent van een Short gebied dat door de Bouwer van het Schema UI wordt gecreeerd is een integer typegebiedmet specifieke minimum en maximum waarden (-32768 en 32768, respectievelijk).

"sampleField": {
  "title": "Sample Short Field",
  "description": "An example short field.",
  "type": "integer",
  "minimum": -32768,
  "maximum": 32768
}

Byte byte

Het equivalent van een Byte gebied dat door de Bouwer van het Schema UI wordt gecreeerd is een integer typegebiedmet specifieke minimum en maximum waarden (-128 en 128, respectievelijk).

"sampleField": {
  "title": "Sample Byte Field",
  "description": "An example byte field.",
  "type": "integer",
  "minimum": -128,
  "maximum": 128
}

Boolean boolean

Boolean -velden worden aangegeven door type: boolean .

"sampleField": {
  "title": "Sample Boolean Field",
  "description": "An example boolean field.",
  "type": "boolean"
}

U kunt desgewenst een default -waarde opgeven die door het veld wordt gebruikt wanneer tijdens het innemen geen expliciete waarde wordt opgegeven.

"sampleField": {
  "title": "Sample Boolean Field",
  "description": "An example boolean field with a default value.",
  "type": "boolean",
  "default": false
}

IMPORTANT

Als er geen default -waarde is opgegeven en het Booleaanse veld is ingesteld op required , zal een record zonder een geaccepteerde waarde voor dit veld niet worden gevalideerd bij invoer.

Date date

Date -velden worden aangegeven met type: string en format: date . U kunt desgewenst ook een array van examples aan hefboomwerking verstrekken in gevallen waarin u een koord van de steekproefdatum voor gebruikers wilt tonen die de gegevens manueel ingaan.

"sampleField": {
  "title": "Sample Date Field",
  "description": "An example date field with an example array item.",
  "type": "string",
  "format": "date",
  "examples": ["2004-10-23"]
}

DateTime date-time

DateTime -velden worden aangegeven met type: string en format: date-time . U kunt desgewenst ook een array van examples aan hefboomwerking verstrekken in gevallen waar u een steekproefdatetime koord voor gebruikers wilt tonen die de gegevens manueel ingaan.

"sampleField": {
  "title": "Sample Datetime Field",
  "description": "An example datetime field with an example array item.",
  "type": "string",
  "format": "date-time",
  "examples": ["2004-10-23T12:00:00-06:00"]
}

Array array

Array -velden worden aangegeven door type: array en een items -object dat het schema definieert van de items die de array accepteert.

U kunt array-items definiëren met behulp van primitieve typen, zoals een array van tekenreeksen:

"sampleField": {
  "title": "Sample Array Field",
  "description": "An example array field using a primitive type.",
  "type": "array",
  "items": {
    "type": "string"
  }
}

U kunt de array-items ook definiëren op basis van een bestaand gegevenstype door via een eigenschap $ref naar de eigenschap $id van het gegevenstype te verwijzen. Hieronder ziet u een array van Payment Item -objecten:

"sampleField": {
  "title": "Sample Array Field",
  "description": "An example array field using a data type reference.",
  "type": "array",
  "items": {
    "$ref": "https://ns.adobe.com/xdm/data/paymentitem"
  }
}

Object object

Object -velden worden aangegeven door type: object en een properties -object dat subeigenschappen voor het schemaveld definieert.

Het subveld dat onder properties wordt gedefinieerd, kan worden gedefinieerd met elke primitieve waarde type of door te verwijzen naar een bestaand gegevenstype via een eigenschap $ref die verwijst naar de eigenschap $id van het gegevenstype in kwestie:

"sampleField": {
  "title": "Sample Object Field",
  "description": "An example object field.",
  "type": "object",
  "properties": {
    "field1": {
      "type": "string"
    },
    "field2": {
      "$ref": "https://ns.adobe.com/xdm/common/measure"
    }
  }
}

U kunt ook het gehele object definiëren door naar een gegevenstype te verwijzen, op voorwaarde dat het gegevenstype in kwestie zelf is gedefinieerd als type: object :

"sampleField": {
  "title": "Sample Object Field",
  "description": "An example object field using a data type reference.",
  "$ref": "https://ns.adobe.com/xdm/common/phoneinteraction"
}

Map map

Een kaartgebied is hoofdzakelijk een object - type gebiedmet een onbeperkte reeks sleutels. Kaarten hebben net als objecten de waarde type object , maar hun meta:xdmType is expliciet ingesteld op map .

Een kaart moet geen eigenschappen bepalen. Het moet één enkel additionalProperties schema bepalen om het type van waarden te beschrijven binnen de kaart (elke kaart kan slechts één enkel gegevenstype bevatten). De type -waarde moet string of integer zijn.

Een kaartveld met tekenreekswaarden wordt bijvoorbeeld als volgt gedefinieerd:

"sampleField": {
  "title": "Sample Map Field",
  "description": "An example map field.",
  "type": "object",
  "meta:xdmType": "map",
  "additionalProperties": {
    "type": "string"
  }
}

Zie de onderstaande sectie voor meer informatie over het maken van aangepaste kaartvelden.

Aangepaste toewijzingstypen maken custom-maps

Om 'map-like' gegevens efficiënt te ondersteunen in XDM, kunnen objecten worden voorzien van een annotatie meta:xdmType ingesteld op map om duidelijk te maken dat een object moet worden beheerd alsof de toetsenset onbeperkt is. Gegevens die in kaartvelden worden ingevoerd, moeten tekenreekssleutels gebruiken en alleen tekenreeks- of gehele-getalwaarden (zoals bepaald door additionalProperties.type ).

XDM stelt de volgende beperkingen op het gebruik van deze opslagwenk:

Kaarttypen MOETEN van het type object zijn.
Voor typen toewijzingen MOET GEEN eigenschap zijn gedefinieerd (met andere woorden, ze definiëren "lege" objecten).
Kaarttypen MOETEN een additionalProperties.type -veld bevatten dat de waarden beschrijft die binnen de kaart kunnen worden geplaatst, string of integer .

Zorg ervoor dat u kaart-type gebieden wanneer absoluut noodzakelijk slechts gebruikt, aangezien zij de volgende prestatiesnadelen dragen:

De tijd van de reactie van de Dienst van de Vraag van Adobe Experience Platformdegradeert van drie seconden aan tien seconden voor 100 miljoen verslagen.
Kaarten moeten minder dan 16 sleutels hebben of anders risico op verdere afbraak.

De gebruikersinterface van het Platform heeft ook beperkingen in hoe het de sleutels van kaart-type gebieden kan halen. Terwijl objecttekstvelden kunnen worden uitgebreid, worden kaarten als één veld weergegeven.

Volgende stappen

In deze handleiding wordt beschreven hoe u verschillende veldtypen in de API definieert. Voor meer informatie hoe de XDM gebiedstypes geformatteerd zijn, zie de gids op XDM gebiedstype beperkingen.

recommendation-more-help

62e9ffd9-1c74-4cef-8f47-0d00af32fc07