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.

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}

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

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}

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
}

Egen namnbeskrivning friendly-name

Med egna namnbeskrivningar kan användaren ändra title, descriptionoch 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"
  }
}

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

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

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