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 den sourceSchema som den gäller för. När dessa beskrivningar har tillämpats gäller de alla datauppsättningar som har skapats med schemat.

Med slutpunkten /descriptors i API:t Schema Registry kan du programmässigt hantera beskrivningar i ditt 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 läsa kom igång-guiden för att få länkar till relaterad dokumentation, en guide till hur du läser exempelanropen för API i det här dokumentet och viktig information om vilka huvuden som krä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å det Accept-huvud som skickas i begäran. Observera att slutpunkten /descriptors använder Accept rubriker som skiljer sig från alla andra slutpunkter i API:t Schema Registry.

Svar

Svaret innehåller en array för varje beskrivningstyp som har definierade beskrivningar. Om det inte finns några beskrivningar av en viss @type definierad returnerar registret alltså inte en tom matris för den beskrivningstypen.

När du använder rubriken link Accept 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 slå upp (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, därför krävs ingen Accept-rubrik i sökningsbegä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 som 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 slutpunkten /tenant/descriptors.

API-format

POST /tenant/descriptors

Begäran

Följande begäran definierar en identitetsbeskrivning i ett e-postadressfält i ett exempelschema. Detta anger för Experience Platform att använda e-postadressen som en identifierare för att hjälpa till att sammanfoga information om 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 @id. @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 ta med dess @id i sökvägen för en PUT-begäran.

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 som ska uppdatera (PUT) en beskrivning densamma som nyttolasten för att 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 xdm:namespace ändras 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 som skickades i begäran).

{
    "@id": "f3a1dfa38a4871cf4442a33074c1f9406a593407"
}

Om du utför en sökbegäran (GET) för att visa beskrivningen visas 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 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 uppslagsbegäran mot beskrivningen @id. Svaret returnerar HTTP-status 404 (Hittades inte) eftersom beskrivningen har tagits bort från Schema Registry.

Bilaga

Följande avsnitt innehåller ytterligare information om hur du arbetar med beskrivningar i API:t Schema Registry.

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 identitetsbeskrivare signalerar att sourceProperty för sourceSchema är ett Identity-fält enligt beskrivningen i 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 en användare ändra värdena title, description och meta:enum 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, som är aktiverade för egenskaperna som beskrivs i sourceProperty och destinationProperty. Mer information finns i självstudiekursen om hur du definierar en relation mellan två scheman.

{
  "@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 ett meta:status-attribut med värdet deprecated i 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. Med korrekt Accept header kan 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"
}