Het eindpunt van descriptors

De schema's bepalen de structuur van gegevensentiteiten maar specificeren niet hoe om het even welke datasets die van deze schema's worden gecreeerd op elkaar betrekking hebben. In Adobe Experience Platform kunt u beschrijvingen gebruiken om deze relaties te beschrijven en interpreterende metagegevens aan een schema toe te voegen.

Descriptors zijn metagegevensobjecten op huurniveau die op schema's in Adobe Experience Platform zijn toegepast. Ze definiëren structurele relaties, sleutels en gedragsvelden (zoals tijdstempels of versioning) die van invloed zijn op de manier waarop gegevens worden gevalideerd, samengevoegd of downstream worden geïnterpreteerd.

Een schema kan een of meer beschrijvingen bevatten. Elke descriptor definieert een @type en de sourceSchema waarop deze van toepassing is. De beschrijver is automatisch op alle datasets van dat schema van toepassing.

In Adobe Experience Platform is een descriptor metagegevens die gedragsregels of structurele betekenis toevoegen aan een schema.
Er zijn verschillende typen descriptors, waaronder:

Met het eindpunt /descriptors in de Schema Registry API kunt u beschrijvingen programmatisch beheren binnen uw ervaringstoepassing.

Aan de slag

Het eindpunt dat in deze gids wordt gebruikt maakt deel uit van Schema Registry API ​. Alvorens verder te gaan, te herzien gelieve ​ begonnen gids ​ voor verbindingen aan verwante documentatie, een gids aan het lezen van de steekproefAPI vraag in dit document, en belangrijke informatie betreffende vereiste kopballen die nodig zijn om vraag aan om het even welke Experience Platform API met succes te maken.

Naast standaardbeschrijvers, steunt Schema Registry beschrijvingstypes voor relationele schema's, zoals primaire sleutel, versie en timestamp. Deze dwingen eenheid af, controleren versioning, en bepalen tijd-reeksen gebieden op het schemaniveau. Als u niet vertrouwd met relationele schema's bent, herzie het ​ overzicht van Data Mirror ​ en ​ relationele schema's technische verwijzing ​ alvorens verder te gaan.

Een lijst met descriptoren ophalen list

U kunt alle beschrijvingen weergeven die door uw organisatie zijn gedefinieerd door een GET-aanvraag in te dienen bij /tenant/descriptors .

API formaat

GET /tenant/descriptors

Verzoek

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'

De antwoordindeling is afhankelijk van de header Accept die in de aanvraag wordt verzonden. Het eindpunt /descriptors gebruikt Accept headers die verschillen van alle andere eindpunten in de API Schema Registry .

Reactie

Het antwoord bevat een array voor elk beschrijvende type waarvoor beschrijvingen zijn gedefinieerd. Met andere woorden, als er geen beschrijvers van een bepaalde @type gedefinieerd zijn, retourneert het register geen lege array voor dat beschrijvende type.

Wanneer u de header link Accept gebruikt, wordt elke descriptor weergegeven als een arrayitem in de notatie /{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"
  ]
}

Een descriptor opzoeken lookup

Als u de details van een specifieke descriptor wilt bekijken, verzendt u een GET-aanvraag met behulp van de @id .

API formaat

GET /tenant/descriptors/{DESCRIPTOR_ID}

Verzoek

Met de volgende aanvraag wordt een descriptor opgehaald op basis van de waarde @id . Er is geen versiebeheer toegepast op descriptors. Daarom is geen Accept header vereist in het opzoekverzoek.

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

Reactie

Een geslaagde reactie retourneert de details van de descriptor, inclusief de @type en sourceSchema , plus aanvullende informatie die afhankelijk is van het type descriptor. De geretourneerde @id moet overeenkomen met de beschrijving @id in de aanvraag.

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

Een descriptor maken create

U kunt een nieuwe descriptor maken door een POST-aanvraag in te dienen bij het eindpunt van /tenant/descriptors .

API formaat

POST /tenant/descriptors

Verzoek

In het volgende verzoek wordt een identiteitsbeschrijving gedefinieerd in een veld "E-mailadres" in een voorbeeldschema. Dit vertelt Experience Platform om het e-mailadres als herkenningsteken te gebruiken helpen informatie over het individu samenvoegen.

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

Reactie

Een geslaagde reactie retourneert HTTP-status 201 (Gemaakt) en de details van de nieuwe descriptor, inclusief de @id ervan. @id is een alleen-lezen veld dat door Schema Registry is toegewezen en dat wordt gebruikt voor het verwijzen naar de descriptor in de API.

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

Een descriptor bijwerken put

U kunt een descriptor bijwerken door de @id ervan op te nemen in het pad van een PUT-aanvraag.

API formaat

PUT /tenant/descriptors/{DESCRIPTOR_ID}

Verzoek

Met dit verzoek wordt in feite de descriptor herschreven, zodat de aanvraaginstantie alle velden moet bevatten die vereist zijn voor het definiëren van een descriptor van dat type. Met andere woorden, is de verzoeklading om (PUT) een beschrijver bij te werken het zelfde als de nuttige lading aan ​ creeert (POST) een beschrijver ​ van het zelfde type.

In het volgende voorbeeld wordt een identiteitsdescriptor bijgewerkt om naar een andere xdm:sourceProperty (mobile phone ) te verwijzen en wordt de waarde xdm:namespace in Phone gewijzigd.

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

Reactie

Een geslaagde reactie retourneert HTTP-status 201 (Gemaakt) en de @id van de bijgewerkte descriptor (die moet overeenkomen met de @id die in de aanvraag is verzonden).

{
    "@id": "f3a1dfa38a4871cf4442a33074c1f9406a593407"
}

Het uitvoeren van het verzoek van de a ​ raadpleging (GET) ​ om de beschrijver te bekijken toont aan dat de gebieden nu zijn bijgewerkt om op de veranderingen te wijzen die in het verzoek van PUT worden verzonden.

Een descriptor verwijderen delete

Soms moet u een descriptor verwijderen die u in de Schema Registry hebt gedefinieerd. Hiervoor doet u een DELETE-aanvraag die verwijst naar @id van de descriptor die u wilt verwijderen.

API formaat

DELETE /tenant/descriptors/{DESCRIPTOR_ID}

Verzoek

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

Reactie

Een geslaagde reactie retourneert HTTP-status 204 (Geen inhoud) en een lege hoofdtekst.

Om de beschrijver te bevestigen is geschrapt, kunt u a ​ raadplegingsverzoek ​ tegen de beschrijver @id uitvoeren. De reactie retourneert HTTP-status 404 (Niet gevonden) omdat de descriptor is verwijderd uit de Schema Registry .

Bijlage appendix

In de volgende sectie vindt u aanvullende informatie over het werken met descriptoren in de API van Schema Registry .

descriptoren definiëren defining-descriptors

In de volgende secties vindt u een overzicht van de beschikbare descriptortypen, inclusief de vereiste velden voor het definiëren van een descriptor voor elk type.

Identiteitsbeschrijving identity-descriptor

Een identiteitsbeschrijver signaleert dat "sourceProperty"van "sourceSchema"een Identity gebied is zoals die door ​ wordt beschreven de Dienst van de Identiteit van Experience Platform ​.

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

Beschrijvende naam friendly-name

Met beschrijvingen van vriendschappelijke namen kan een gebruiker de waarden title , description en meta:enum van de kernvelden van het bibliotheekschema wijzigen. Dit is vooral handig wanneer u werkt met "eVars" en andere "generieke" velden die u wilt labelen voor informatie die specifiek is voor uw organisatie. De gebruikersinterface kan deze gebruiken om een vriendelijkere naam weer te geven of om alleen velden weer te geven die een vriendelijke naam hebben.

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

Relatiebeschrijving relationship-descriptor

Relationship-descriptors beschrijven een relatie tussen twee verschillende schema's, die u hebt afgesloten op de eigenschappen die worden beschreven in xdm:sourceProperty en xdm:destinationProperty . Zie het leerprogramma op ​ bepalend een verband tussen twee schema's ​ voor meer informatie.

Gebruik deze eigenschappen om te verklaren hoe een brongebied (buitenlandse sleutel) op een bestemmingsgebied (​ primaire sleutel ​ of kandidaat sleutel) betrekking heeft.

De API ondersteunt twee patronen:

Eén-op-één relatie (standaardschema's)

Gebruik dit wanneer het handhaven van bestaande standaard-schema-integraties die reeds op xdm:descriptorOneToOne steunen.

{
  "@type": "xdm:descriptorOneToOne",
  "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/{SOURCE_SCHEMA_ID}",
  "xdm:sourceVersion": 1,
  "xdm:sourceProperty": "/parentField/subField",
  "xdm:destinationSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/{DEST_SCHEMA_ID}",
  "xdm:destinationVersion": 1,
  "xdm:destinationProperty": "/parentField/subField"
}

In de volgende tabel worden de velden beschreven die nodig zijn om een één-op-één relatiebeschrijving te definiëren.

Algemene relatie (relationele schema's en aanbevolen voor nieuwe projecten)

Gebruik deze descriptor voor alle nieuwe implementaties en voor relationele schema's. Het staat u toe om de kardinaliteit van de verhouding (zoals één-aan-één of vele-aan-één) te bepalen, relatienamen te specificeren, en verbinding aan een bestemmingsgebied te verbinden dat niet de primaire sleutel (niet-primaire sleutel) is.

In de volgende voorbeelden ziet u hoe u een algemene relatiebeschrijving definieert.

Minimaal voorbeeld:

Dit minimale voorbeeld omvat slechts de vereiste gebieden om een vele-aan-één verhouding tussen twee schema's te bepalen.

{
  "@type": "xdm:descriptorRelationship",
  "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/{SOURCE_SCHEMA_ID}",
  "xdm:sourceProperty": "/customer_ref",
  "xdm:sourceVersion": 1,
  "xdm:destinationSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/{DEST_SCHEMA_ID}",
  "xdm:cardinality": "M:1"
}

Voorbeeld met alle facultatieve gebieden:

Dit voorbeeld bevat alle optionele velden, zoals relatienamen, weergavettels en een expliciet doelveld voor een niet-primaire sleutel.

{
  "@type": "xdm:descriptorRelationship",
  "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/{SOURCE_SCHEMA_ID}",
  "xdm:sourceVersion": 1,
  "xdm:sourceProperty": "/customer_ref",
  "xdm:destinationSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/{DEST_SCHEMA_ID}",
  "xdm:destinationProperty": "/customer_id",
  "xdm:sourceToDestinationName": "CampaignToCustomer",
  "xdm:destinationToSourceName": "CustomerToCampaign",
  "xdm:sourceToDestinationTitle": "Customer campaigns",
  "xdm:destinationToSourceTitle": "Campaign customers",
  "xdm:cardinality": "M:1"
}

Een relatiebeschrijving kiezen

Gebruik de volgende richtlijnen om te beslissen welke relatiebeschrijving u wilt toepassen:

Capaciteitsvergelijking

In de volgende tabel worden de mogelijkheden van de twee descriptortypen vergeleken:

Beperkingen en validatie

Volg deze vereisten en aanbevelingen wanneer het bepalen van een algemene relatiebeschrijver:

Descriptor primaire sleutel primary-key-descriptor

De primaire zeer belangrijke beschrijver (xdm:descriptorPrimaryKey) dwingt uniciteit en niet-krachtbeperkingen op één of meerdere gebieden in een schema af.

{
  "@type": "xdm:descriptorPrimaryKey",
  "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
  "xdm:sourceProperty": ["/orderId", "/orderLineId"]
}

Versiebeschrijving version-descriptor

De versiedescriptor (xdm:descriptorVersion) wijst een gebied aan om conflicten van uit-van-orde veranderingsgebeurtenissen te ontdekken en te verhinderen.

{
  "@type": "xdm:descriptorVersion",
  "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
  "xdm:sourceProperty": "/versionNumber"
}

Tijdstempelbeschrijving timestamp-descriptor

In de tijdstempeldescriptor (xdm:descriptorTimestamp) wordt een datum-tijdveld aangewezen als tijdstempel voor schema's met "meta:behaviorType": "time-series" .

{
  "@type": "xdm:descriptorTimestamp",
  "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
  "xdm:sourceProperty": "/eventTime"
}

B2B-relatiebeschrijving B2B-relationship-descriptor

De Real-Time CDP B2B edition introduceert een alternatieve manier om relaties tussen schema's te definiëren, die vele-op-één relaties mogelijk maakt. Deze nieuwe relatie moet het @type: xdm:descriptorRelationship type hebben en de lading moet meer gebieden dan de @type: xdm:descriptorOneToOne verhouding omvatten. Zie het leerprogramma op ​ bepalend een schemaverhouding voor B2B edition ​ voor meer informatie.

{
   "@type": "xdm:descriptorRelationship",
   "xdm:sourceSchema" : "https://ns.adobe.com/{TENANT_ID}/schemas/9f2b2f225ac642570a110d8fd70800ac0c0573d52974fa9a",
   "xdm:sourceVersion" : 1,
   "xdm:sourceProperty" : "/person-ref",
   "xdm:destinationSchema" : "https://ns.adobe.com/{TENANT_ID/schemas/628427680e6b09f1f5a8f63ba302ee5ce12afba8de31acd7",
   "xdm:destinationVersion" : 1,
   "xdm:destinationProperty": "/personId",
   "xdm:destinationNamespace" : "People",
   "xdm:destinationToSourceTitle" : "Opportunity Roles",
   "xdm:sourceToDestinationTitle" : "People",
   "xdm:cardinality": "M:1"
}

Referentie-identiteitsdescriptor

De identiteitsbeschrijvers van de verwijzing verstrekken een verwijzingscontext aan de primaire identiteit van een schemagebied, toelatend het om door gebieden in andere schema's worden van verwijzingen voorzien. In het referentieschema moet al een primair identiteitsveld zijn gedefinieerd voordat naar het kan worden verwezen door andere schema's via dit beschrijvingsbestand.

{
  "@type": "xdm:descriptorReferenceIdentity",
  "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/78bab6346b9c5102b60591e15e75d254",
  "xdm:sourceVersion": 1,
  "xdm:sourceProperty": "/parentField/subField",
  "xdm:identityNamespace": "Email"
}

Vervangen velddescriptor

U kunt ​ een gebied binnen een douaneXDM middel ​ verwerpen door a meta:status attributen toe te voegen die aan deprecated aan het betrokken gebied worden geplaatst. Als u velden die worden verschaft door standaard XDM-bronnen in uw schema's wilt vervangen, kunt u echter een vervangen velddescriptor toewijzen aan het desbetreffende schema om hetzelfde effect te bereiken. Gebruikend ​ correcte Accept kopbal ​, kunt u dan bekijken welke standaardgebieden voor een schema verouderd zijn wanneer het omhoog kijken in API.

{
  "@type": "xdm:descriptorDeprecated",
  "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/c65ddf08cf2d4a2fe94bd06113bf4bc4c855e12a936410d5",
  "xdm:sourceVersion": 1,
  "xdm:sourceProperty": "/faxPhone"
}