Beskrivningsslutpunkt
Scheman definierar en statisk vy av datatabeller, men ger inga specifika detaljer om hur data som baseras på dessa scheman (till exempel datauppsättningar) kan relateras till varandra. Med Adobe Experience Platform kan du beskriva dessa relationer och andra tolka metadata om ett schema med hjälp av beskrivningar.
Schemabeskrivare är metadata på tenant-nivå, vilket innebär att de är unika för din organisation och att alla beskrivningsåtgärder utförs i innehavarbehållaren.
Varje schema kan ha en eller flera schemabeskrivningsentiteter tillämpade. Varje schemabeskrivningsentitet innehåller en beskrivning @type
och sourceSchema
som den är tillämplig på. När dessa beskrivningar har tillämpats gäller de alla datauppsättningar som har skapats med schemat.
The /descriptors
slutpunkt i Schema Registry Med API kan ni programmässigt hantera beskrivningar i ert upplevelseprogram.
Komma igång
Slutpunkten som används i den här guiden ingår i Schema Registry API. Innan du fortsätter bör du granska komma igång-guide för länkar till relaterad dokumentation, en guide till hur du läser exempelanrop till API:er i det här dokumentet och viktig information om vilka huvuden som behövs för att kunna anropa ett Experience Platform-API.
Hämta en lista med beskrivningar list
Du kan visa alla beskrivningar som har definierats av din organisation genom att göra en GET-förfrågan till /tenant/descriptors
.
API-format
GET /tenant/descriptors
Begäran
curl -X GET \
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 'Accept: application/vnd.adobe.xdm-link+json'
Svarsformatet beror på Accept
huvud som skickades i begäran. Observera att /descriptors
slutpunktsanvändning Accept
huvuden som skiljer sig från andra slutpunkter i Schema Registry API.
Accept
rubriker som ersätter xed
med xdm
och erbjuder link
som är unikt för beskrivare. Den rätta Accept
rubrikerna har tagits med i exempelanropen nedan, men var extra försiktig för att se till att rätt rubriker används när du arbetar med beskrivningar.Accept
headerapplication/vnd.adobe.xdm-id+json
application/vnd.adobe.xdm-link+json
application/vnd.adobe.xdm+json
application/vnd.adobe.xdm-v2+json
Accept
sidhuvudet måste användas för att sidindelningsfunktionerna ska kunna användas.Svar
Svaret innehåller en array för varje beskrivningstyp som har definierade beskrivningar. Med andra ord, om det inte finns några beskrivningar av en viss @type
definierade returnerar registret inte en tom array för den beskrivningstypen.
När du använder link
Accept
header visas varje beskrivning som ett arrayobjekt i formatet /{CONTAINER}/descriptors/{DESCRIPTOR_ID}
{
"xdm:alternateDisplayInfo": [
"/tenant/descriptors/85dc1bc8b91516ac41163365318e38a9f1e4f351",
"/tenant/descriptors/49bd5abb5a1310ee80ebc1848eb508d383a462cf",
"/tenant/descriptors/b3b3e548f1c653326bcf5459ceac4140fc0b9e08"
],
"xdm:descriptorIdentity": [
"/tenant/descriptors/f7a4bc25429496c4740f8f9a7a49ba96862c5379"
],
"xdm:descriptorOneToOne": [
"/tenant/descriptors/cb509fd6f8ab6304e346905441a34b58a0cd481a"
]
}
Söka efter en beskrivning lookup
Om du vill visa information om en viss beskrivning kan du söka efter (GET) en enskild beskrivning med hjälp av dess @id
.
API-format
GET /tenant/descriptors/{DESCRIPTOR_ID}
{DESCRIPTOR_ID}
@id
för den beskrivning som du vill söka efter.Begäran
Följande begäran hämtar en beskrivning med dess @id
värde. Beskrivningar har ingen version och därför behöver de inte Accept
header krävs i sökbegäran.
curl -X GET \
https://platform.adobe.io/data/foundation/schemaregistry/tenant/descriptors/f3a1dfa38a4871cf4442a33074c1f9406a593407 \
-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}'
Svar
Ett lyckat svar returnerar information om beskrivningen, inklusive dess @type
och sourceSchema
samt ytterligare information som varierar beroende på typen av beskrivning. Den returnerade @id
ska matcha beskrivningen @id
anges i begäran.
{
"@type": "xdm:descriptorIdentity",
"xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
"xdm:sourceVersion": 1,
"xdm:sourceProperty": "/personalEmail/address",
"xdm:namespace": "Email",
"xdm:property": "xdm:code",
"xdm:isPrimary": false,
"createdUser": "{CREATED_USER}",
"imsOrg": "{ORG_ID}",
"createdClient": "{CREATED_CLIENT}",
"updatedUser": "{UPDATED_USER}",
"created": 1548899346989,
"updated": 1548899346989,
"meta:containerId": "tenant",
"@id": "f3a1dfa38a4871cf4442a33074c1f9406a593407"
}
Skapa en beskrivning create
Du kan skapa en ny beskrivning genom att göra en POST-förfrågan till /tenant/descriptors
slutpunkt.
API-format
POST /tenant/descriptors
Begäran
Följande begäran definierar en identitetsbeskrivning i ett e-postadressfält i ett exempelschema. Det här säger Experience Platform om du vill använda e-postadressen som en identifierare för att sammanfoga information om den enskilda personen.
curl -X POST \
https://platform.adobe.io/data/foundation/schemaregistry/tenant/descriptors \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '
{
"@type": "xdm:descriptorIdentity",
"xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
"xdm:sourceVersion": 1,
"xdm:sourceProperty": "/personalEmail/address",
"xdm:namespace": "Email",
"xdm:property": "xdm:code",
"xdm:isPrimary": false
}'
Svar
Ett lyckat svar returnerar HTTP-status 201 (Skapad) och information om den nyskapade beskrivningen, inklusive dess @id
. The @id
är ett skrivskyddat fält som tilldelats av Schema Registry och används för att referera till beskrivningen i API:t.
{
"@type": "xdm:descriptorIdentity",
"xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
"xdm:sourceVersion": 1,
"xdm:sourceProperty": "/personalEmail/address",
"xdm:namespace": "Email",
"xdm:property": "xdm:code",
"xdm:isPrimary": false,
"meta:containerId": "tenant",
"@id": "f3a1dfa38a4871cf4442a33074c1f9406a593407"
}
Uppdatera en beskrivning put
Du kan uppdatera en beskrivning genom att inkludera dess @id
på sökvägen till en begäran från PUT.
API-format
PUT /tenant/descriptors/{DESCRIPTOR_ID}
{DESCRIPTOR_ID}
@id
för den beskrivning som du vill uppdatera.Begäran
Denna begäran skriver i princip om beskrivningen, så begärandetexten måste innehålla alla fält som krävs för att definiera en beskrivning av den typen. Med andra ord är nyttolasten för begäran om att uppdatera (PUT) en beskrivning samma som nyttolasten som skapa (POST) en beskrivning av samma typ.
I följande exempel uppdateras en identitetsbeskrivning så att den refererar till en annan xdm:sourceProperty
(mobile phone
) och ändra xdm:namespace
till Phone
.
curl -X PUT \
https://platform.adobe.io/data/foundation/schemaregistry/tenant/descriptors/f3a1dfa38a4871cf4442a33074c1f9406a593407 \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '{
"@type": "xdm:descriptorIdentity",
"xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
"xdm:sourceVersion": 1,
"xdm:sourceProperty": "/mobilePhone/number",
"xdm:namespace": "Phone",
"xdm:property": "xdm:code",
"xdm:isPrimary": false
}'
Svar
Ett lyckat svar returnerar HTTP-status 201 (Skapad) och @id
för den uppdaterade beskrivningen (som ska matcha @id
skickas i begäran).
{
"@id": "f3a1dfa38a4871cf4442a33074c1f9406a593407"
}
Utföra en sökbegäran (GET) för att visa beskrivningen visar att fälten nu har uppdaterats för att återspegla de ändringar som skickats i PUT-begäran.
Ta bort en beskrivning delete
Ibland kan du behöva ta bort en beskrivning som du har definierat från Schema Registry. Detta görs genom att en DELETE-begäran som refererar till @id
för den beskrivning som du vill ta bort.
API-format
DELETE /tenant/descriptors/{DESCRIPTOR_ID}
{DESCRIPTOR_ID}
@id
för den beskrivning som du vill ta bort.Begäran
curl -X DELETE \
https://platform.adobe.io/data/foundation/schemaregistry/tenant/descriptors/ca921946fb5281cbdb8ba5e07087486ce531a1f2 \
-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}'
Svar
Ett lyckat svar returnerar HTTP-status 204 (inget innehåll) och en tom brödtext.
Om du vill bekräfta att beskrivningen har tagits bort kan du utföra en sökförfrågan mot beskrivningen @id
. Svaret returnerar HTTP-status 404 (Hittades inte) eftersom beskrivningen har tagits bort från Schema Registry.
Bilaga
I följande avsnitt finns ytterligare information om hur du arbetar med beskrivningar i Schema Registry API.
Definiera beskrivningar defining-descriptors
I följande avsnitt ges en översikt över tillgängliga beskrivningstyper, inklusive de fält som krävs för att definiera en beskrivning av varje typ.
Identitetsbeskrivare
En identitetsbeskrivning signalerar attsourceProperty" i "sourceSchema" är en Identity fält enligt beskrivning Adobe Experience Platform Identity Service.
{
"@type": "xdm:descriptorIdentity",
"xdm:sourceSchema":
"https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
"xdm:sourceVersion": 1,
"xdm:sourceProperty": "/personalEmail/address",
"xdm:namespace": "Email",
"xdm:property": "xdm:code",
"xdm:isPrimary": false
}
@type
xdm:descriptorIdentity
.xdm:sourceSchema
$id
URI för schemat där beskrivningen definieras.xdm:sourceVersion
xdm:sourceProperty
xdm:namespace
id
eller code
identitetsnamnutrymmets värde. En lista med namnutrymmen finns med Identity Service API.xdm:property
xdm:id
eller xdm:code
, beroende på xdm:namespace
används.xdm:isPrimary
Egen namnbeskrivning friendly-name
Med egna namnbeskrivningar kan användaren ändra title
, description
och meta:enum
värden för huvudbibliotekets schemafält. Detta är särskilt användbart när du arbetar med"eVars" och andra"generiska" fält som du vill märka som innehåller information som är specifik för din organisation. Gränssnittet kan använda dessa för att visa ett mer användarvänligt namn eller för att endast visa fält som har ett eget namn.
{
"@type": "xdm:alternateDisplayInfo",
"xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/274f17bc5807ff307a046bab1489fb18",
"xdm:sourceVersion": 1,
"xdm:sourceProperty": "/xdm:eventType",
"xdm:title": {
"en_us": "Event Type"
},
"xdm:description": {
"en_us": "The type of experience event detected by the system."
},
"meta:enum": {
"click": "Mouse Click",
"addCart": "Add to Cart",
"checkout": "Cart Checkout"
},
"xdm:excludeMetaEnum": {
"web.formFilledOut": "Web Form Filled Out",
"media.ping": "Media ping"
}
}
@type
xdm:alternateDisplayInfo
.xdm:sourceSchema
$id
URI för schemat där beskrivningen definieras.xdm:sourceVersion
xdm:sourceProperty
/
) och inte sluta med en. Inkludera inte properties
i sökvägen (använd till exempel /personalEmail/address
i stället för /properties/personalEmail/properties/address
).xdm:title
xdm:description
meta:enum
xdm:sourceProperty
är ett strängfält, meta:enum
kan användas för att lägga till föreslagna värden för fältet i segmenteringsgränssnittet. Det är viktigt att notera att meta:enum
deklarerar inte en uppräkning eller tillhandahåller någon datavalidering för XDM-fältet.Detta ska endast användas för XDM-fält som definieras av Adobe. Om egenskapen source är ett anpassat fält som definieras av din organisation bör du i stället redigera fältets
meta:enum
direkt via en PATCH-begäran till fältets överordnade resurs.meta:excludeMetaEnum
xdm:sourceProperty
är ett strängfält som har befintliga föreslagna värden som anges under en meta:enum
kan du inkludera det här objektet i en egen namnbeskrivning för att utesluta vissa eller alla värden från segmenteringen. Nyckeln och värdet för varje post måste matcha de som ingår i originalet meta:enum
av fältet för att bidraget ska kunna uteslutas.Relationsbeskrivning
Relationsbeskrivare beskriver en relation mellan två olika scheman, aktiverade för egenskaperna som beskrivs i sourceProperty
och destinationProperty
. Se självstudiekursen om definiera en relation mellan två scheman för mer information.
{
"@type": "xdm:descriptorOneToOne",
"xdm:sourceSchema":
"https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
"xdm:sourceVersion": 1,
"xdm:sourceProperty": "/parentField/subField",
"xdm:destinationSchema":
"https://ns.adobe.com/{TENANT_ID}/schemas/78bab6346b9c5102b60591e15e75d254",
"xdm:destinationVersion": 1,
"xdm:destinationProperty": "/parentField/subField"
}
@type
xdm:descriptorOneToOne
.xdm:sourceSchema
$id
URI för schemat där beskrivningen definieras.xdm:sourceVersion
xdm:sourceProperty
xdm:destinationSchema
$id
URI för referensschemat som den här beskrivningen definierar en relation med.xdm:destinationVersion
xdm:destinationProperty
Referens för identitetsbeskrivning
Referensidentitetsbeskrivningar ger en referenskontext till den primära identiteten för ett schemafält, vilket gör att det kan refereras till av fält i andra scheman. Referensschemat måste redan ha ett primärt identitetsfält definierat innan det kan refereras till av andra scheman via den här beskrivningen.
{
"@type": "xdm:descriptorReferenceIdentity",
"xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/78bab6346b9c5102b60591e15e75d254",
"xdm:sourceVersion": 1,
"xdm:sourceProperty": "/parentField/subField",
"xdm:identityNamespace": "Email"
}
@type
xdm:descriptorReferenceIdentity
.xdm:sourceSchema
$id
URI för schemat där beskrivningen definieras.xdm:sourceVersion
xdm:sourceProperty
/personalEmail/address
i stället för /properties/personalEmail/properties/address
).xdm:identityNamespace
Borttagen fältbeskrivning
Du kan ta bort ett fält i en anpassad XDM-resurs genom att lägga till en meta:status
attribut inställt på deprecated
till fältet i fråga. Om du vill ta bort fält från standard-XDM-resurser i dina scheman kan du tilldela schemat en inaktuell fältbeskrivning för att uppnå samma effekt. Använda korrigera Accept
headerkan du sedan visa vilka standardfält som är inaktuella för ett schema när du söker efter det i API:t.
{
"@type": "xdm:descriptorDeprecated",
"xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/c65ddf08cf2d4a2fe94bd06113bf4bc4c855e12a936410d5",
"xdm:sourceVersion": 1,
"xdm:sourceProperty": "/faxPhone"
}
@type
xdm:descriptorDeprecated
.xdm:sourceSchema
$id
för det schema som du använder beskrivningen på.xdm:sourceVersion
1
.xdm:sourceProperty
["/firstName", "/lastName"]
).