Dokumentation Experience Platform Användarhandbok om XDM (Experience Data Model)

Definiera XDM-fält i API:t för schemaregister

Senast uppdaterad: 29 april 2025

Ämnen:

Skapat för:

Utvecklare

Alla XDM-fält (Experience Data Model) definieras med standardbegränsningarna JSON Schema som gäller för deras fälttyp, med ytterligare begränsningar för fältnamn som används av Adobe Experience Platform. Med API:t för schemaregister kan du definiera anpassade fält i dina scheman genom att använda format och valfria begränsningar. XDM-fälttyper visas av fältnivåattributet, meta:xdmType.

NOTE

meta:xdmType är ett systemgenererat värde och du behöver därför inte lägga till den här egenskapen i JSON för fältet när du använder API:t (förutom när skapar anpassade mappningstyper). Bästa sättet är att använda JSON-schematyper (till exempel string och integer) med rätt min/max-begränsningar enligt definitionen i tabellen nedan.

I den här handboken beskrivs lämplig formatering för att definiera olika fälttyper, inklusive de med valfria egenskaper. Mer information om valfria egenskaper och typspecifika nyckelord finns i dokumentationen för JSON-schemat.

Börja med att hitta önskad fälttyp och använd exempelkoden som anges för att skapa din API-begäran för skapa en fältgrupp eller skapa en datatyp.

String

String fält indikeras av type: string.

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

Du kan också begränsa vilka typer av värden som kan infogas för strängen genom följande ytterligare egenskaper:

pattern: Ett regex-mönster att begränsas av.
minLength: En minimilängd för strängen. Strängar får som standard det lägsta värdet 1.
maxLength: En maximal längd för strängen.

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

URI

URI fält indikeras av type: string med egenskapen format inställd på uri. Inga andra egenskaper accepteras.

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

Enum

Enum-fält måste använda type: string, med uppräkningsvärdena som anges under en enum-array:

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

Du kan också ange kundorienterade etiketter för varje värde under en meta:enum-egenskap, där varje etikett skrivs med ett motsvarande värde under enum.

"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

Värdet meta:enum deklarerar inte en uppräkning eller kör en datavalidering på egen hand. I de flesta fall anges även strängar som anges under meta:enum under enum för att säkerställa att data begränsas. Det finns emellertid vissa användningsfall där meta:enum tillhandahålls utan en motsvarande enum-array. Mer information finns i självstudiekursen Definiera föreslagna värden.

Du kan också ange en default-egenskap för att ange standardvärdet enum som fältet ska använda om inget värde anges.

"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

Om inget default-värde anges och uppräkningsfältet är inställt på required, kommer alla poster som saknar ett godkänt värde för det här fältet att misslyckas vid inmatning.

Number

Nummerfält indikeras av type: number och har inga andra obligatoriska egenskaper.

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

NOTE

number-typer används för alla numeriska typer, antingen heltal eller flyttal, medan integer typeranvänds specifikt för heltal. Mer information om användningsexempel för varje typ finns i dokumentationen för JSON-schemat för numeriska typer.

Integer

Integer fält indikeras av type: integer och har inga andra obligatoriska fält.

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

NOTE

integer-typer refererar specifikt till heltal, men number typeranvänds för alla numeriska typer, antingen heltal eller flyttal. Mer information om användningsexempel för varje typ finns i dokumentationen för JSON-schemat för numeriska typer.

Du kan begränsa heltalets intervall genom att lägga till egenskaperna minimum och maximum i definitionen. Flera andra numeriska typer som stöds av gränssnittet i Schema Builder är bara integer typer med specifika minimum- och maximum-begränsningar, som Long, Short och Byte.

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

Long

Motsvarigheten till ett Long-fält som skapats via Schema Builder-gränssnittet är ett integer typfältmed specifika minimum - och maximum-värden (-9007199254740992 respektive 9007199254740992).

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

Short

Motsvarigheten till ett Short-fält som skapats via Schema Builder-gränssnittet är ett integer typfältmed specifika minimum - och maximum-värden (-32768 respektive 32768).

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

Byte

Motsvarigheten till ett Byte-fält som skapats via Schema Builder-gränssnittet är ett integer typfältmed specifika minimum - och maximum-värden (-128 respektive 128).

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

Boolean

Boolean fält indikeras av type: boolean.

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

Du kan också ange ett default-värde som fältet ska använda när inget explicit värde anges vid inmatning.

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

IMPORTANT

Om inget default-värde har angetts och det booleska fältet har värdet required, kommer alla poster som saknar ett godkänt värde för det här fältet att misslyckas med valideringen vid inmatning.

Date

Date fält indikeras av type: string och format: date. Du kan också ange en matris på examples som ska användas om du vill visa en exempeldatumsträng för användare som anger data manuellt.

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

DateTime

DateTime fält indikeras av type: string och format: date-time. Du kan också ange en matris på examples som ska användas om du vill visa en exempelsträng för datum/tid för användare som anger data manuellt.

"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 fält indikeras av type: array och ett items-objekt som definierar schemat för de objekt som arrayen accepterar.

Du kan definiera arrayobjekt med primitiva typer, till exempel en array med strängar:

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

Du kan också definiera arrayobjekten baserat på en befintlig datatyp genom att referera till $id för datatypen via en $ref -egenskap. Följande är en array med Payment Item objekt:

"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 fält indikeras av type: object och ett properties-objekt som definierar underegenskaper för schemafältet.

Varje underfält som definieras under properties kan definieras med hjälp av en primitiv type eller genom att referera till en befintlig datatyp via en $ref -egenskap som pekar på $id för den aktuella datatypen:

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

Du kan också definiera hela objektet genom att referera till en datatyp, förutsatt att datatypen i fråga själv är definierad som 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

Ett kartfält är i princip ett object-typsfältmed en obegränsad uppsättning tangenter. Precis som objekt har kartor värdet type, men meta:xdmType anges uttryckligen till map.object

En karta får inte definiera några egenskaper. Den måste definiera ett enskilt additionalProperties-schema för att beskriva värdetypen som finns i kartan (varje karta kan bara innehålla en enda datatyp). Värdet type måste vara antingen string eller integer.

Ett mappningsfält med strängtypsvärden definieras så här:

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

Mer information om hur du skapar anpassade kartfält finns i avsnittet nedan.

Skapa anpassade mappningstyper

För att ge effektivt stöd för "mappningsliknande" data i XDM kan objekt kommenteras med en meta:xdmType inställd på map för att göra det tydligt att ett objekt ska hanteras som om nyckeluppsättningen var obegränsad. Data som är inkapslade i mappningsfält måste använda strängnycklar och endast sträng- eller heltalsvärden (som bestäms av additionalProperties.type).

XDM har följande begränsningar för användning av detta lagringstips:

Karttyperna MÅSTE vara av typen object.
Karttyper FÅR INTE ha egenskaper definierade (de definierar med andra ord tomma objekt).
Karttyperna MÅSTE innehålla ett additionalProperties.type-fält som beskriver de värden som kan placeras i kartan, antingen string eller integer.

Se till att du bara använder karttypsfält när det är absolut nödvändigt, eftersom de har följande prestandanackdelar:

Svarstiden från Adobe Experience Platform Query Service försämras från tre sekunder till tio sekunder för 100 miljoner poster.
Kartor måste ha färre än 16 tangenter, annars riskerar de att försämras ytterligare.

Experience Platform användargränssnitt har även begränsningar för hur nycklarna för mappningsfält kan extraheras. Objekttypsfält kan expanderas, men kartor visas i stället som ett enda fält.

Nästa steg

I den här handboken beskrivs hur du definierar olika fälttyper i API:t. Mer information om hur XDM-fälttyper formateras finns i handboken om begränsningar för XDM-fälttyper.

recommendation-more-help