Documentatie Experience Platform Handleiding voor Experience Data Model (XDM)

Een relatie tussen twee schema's definiëren met de API Schema Registry

Last update: Tue Jul 16 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

Onderwerpen:

Gemaakt voor:

Ontwikkelaar

De mogelijkheid om de relaties tussen uw klanten en hun interactie met uw merk op verschillende kanalen te begrijpen is een belangrijk onderdeel van Adobe Experience Platform. Door deze relaties te definiëren binnen de structuur van uw Experience Data Model (XDM)-schema's kunt u complexe inzichten in uw klantgegevens opdoen.

Hoewel schemarelaties kunnen worden afgeleid door het gebruik van het samenvoegingsschema en Real-Time Customer Profile , geldt dit alleen voor schema's die dezelfde klasse delen. Om een verband tussen twee schema's te vestigen die tot verschillende klassen behoren, moet een specifiek relatiegebied aan a bronschema worden toegevoegd, dat op de identiteit van een afzonderlijk verwijzingsschema wijst.

NOTE

De API van de Registratie van het Schema verwijst naar verwijzingsschema's als "bestemmingsschema's". Deze moeten niet met bestemmingsschema's in de kaartreeksen van Prep van Gegevensof schema's voor bestemmingsverbindingenworden verward.

Dit document verstrekt een zelfstudie voor het bepalen van een één-aan-één verhouding tussen twee schema's die door uw organisatie worden bepaald gebruikend Schema Registry API.

Aan de slag

Deze zelfstudie vereist een goed begrip van Experience Data Model (XDM) en XDM System . Lees de volgende documentatie voordat u met deze zelfstudie begint:

XDM Systeem in Experience Platform: Een overzicht van XDM en zijn implementatie in Experience Platform.
- Grondbeginselen van schemacompositie: Een inleiding van de bouwstenen van schema's XDM.
Real-Time Customer Profile: biedt een uniform, real-time consumentenprofiel dat is gebaseerd op geaggregeerde gegevens van meerdere bronnen.
Sandboxen: Experience Platform verstrekt virtuele zandbakken die één enkele Platform instantie in afzonderlijke virtuele milieu's verdelen helpen digitale ervaringstoepassingen ontwikkelen en ontwikkelen.

Alvorens dit leerprogramma te beginnen, te herzien gelieve de ontwikkelaarsgidsvoor belangrijke informatie die u moet kennen om vraag aan Schema Registry API met succes te maken. Dit omvat uw {TENANT_ID} , het concept "containers" en de vereiste kopteksten voor het indienen van aanvragen (met speciale aandacht voor de header Accept en de mogelijke waarden ervan).

Een bron- en referentieschema definiëren define-schemas

Verwacht wordt dat u reeds de twee schema's hebt gecreeerd die in de verhouding zullen worden bepaald. Dit leerprogramma leidt tot een verband tussen leden van het huidige loyaliteitsprogramma van een organisatie (die in een "Loyalty Members"schema wordt bepaald) en hun favoriete hotels (die in een "Hotels"schema wordt bepaald).

De verhoudingen van het schema worden vertegenwoordigd door a bronschema hebbend een gebied dat naar een ander gebied binnen a verwijzingsschema verwijst. In de stappen die volgen, "Loyalty Members"zal het bronschema zijn, terwijl "Hotels"als verwijzingsschema zal dienst doen.

IMPORTANT

Om een relatie tot stand te brengen, moeten beide schema's primaire identiteiten hebben bepaald en voor Real-Time Customer Profile worden toegelaten. Zie de sectie op toelatend een schema voor gebruik in Profielin het leerprogramma van de schemaverwezenlijking als u begeleiding op hoe te om uw schema's dienovereenkomstig te vormen vereist.

Als u een relatie tussen twee schema's wilt definiëren, moet u eerst de $id -waarden voor beide schema's ophalen. Als u de weergavenamen (title) van de schema's kent, kunt u hun $id -waarden vinden door een aanvraag voor een GET in te dienen bij het /tenant/schemas -eindpunt in de Schema Registry API.

API formaat

GET /tenant/schemas

Verzoek

curl -X GET \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/schemas \
  -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.xed-id+json'

NOTE

De Accept header application/vnd.adobe.xed-id+json retourneert alleen de titels, id's en versies van de resulterende schema's.

Reactie

Een geslaagde reactie retourneert een lijst met schema's die door uw organisatie zijn gedefinieerd, inclusief de schema's name , $id , meta:altId en version .

{
    "results": [
        {
            "title": "Newsletter Subscriptions",
            "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/192a66930afad02408429174c311ae73",
            "meta:altId": "_{TENANT_ID}.schemas.192a66930afad02408429174c311ae73",
            "version": "1.2"
        },
        {
            "title": "Loyalty Members",
            "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/2c66c3a4323128d3701289df4468e8a6",
            "meta:altId": "_{TENANT_ID}.schemas.2c66c3a4323128d3701289df4468e8a6",
            "version": "1.5"
        },
        {
            "title": "Hotels",
            "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/d4ad4b8463a67f6755f2aabbeb9e02c7",
            "meta:altId": "_{TENANT_ID}.schemas.d4ad4b8463a67f6755f2aabbeb9e02c7",
            "version": "1.0"
        }
    ],
    "_page": {
        "orderby": "updated",
        "next": null,
        "count": 3
    },
    "_links": {
        "next": null,
        "global_schemas": {
            "href": "https://platform-stage.adobe.io/data/foundation/schemaregistry/global/schemas"
        }
    }
}

Registreer de $id waarden van de twee schema's u een verhouding tussen wilt bepalen. Deze waarden worden in latere stappen gebruikt.

Een referentieveld definiëren voor het bronschema

Binnen Schema Registry, werken de relatiebeschrijvers gelijkaardig aan buitenlandse sleutels in relationele gegevensbestandlijsten: een gebied in het bronschema dienst als verwijzing naar het primaire identiteitsgebied van een verwijzingsschema. Als uw bronschema geen gebied voor dit doel heeft, kunt u een groep van het schemagebied met het nieuwe gebied moeten tot stand brengen en het toevoegen aan het schema. Dit nieuwe veld moet een type waarde string hebben.

IMPORTANT

Het bronschema kan zijn primaire identiteit niet als verwijzingsgebied gebruiken.

In deze zelfstudie, bevat het verwijzingsschema "Hotels"een hotelId gebied dat als primaire identiteit van het schema dient. Nochtans, heeft het bronschema "Loyalty Members"geen specifiek gebied dat als verwijzing naar hotelId moet worden gebruikt, en daarom moet een groep van het douanegebied worden gecreeerd om een nieuw gebied aan het schema toe te voegen: favoriteHotel.

NOTE

Als uw bronschema reeds een specifiek gebied heeft dat u van plan bent als verwijzingsgebied te gebruiken, kunt u vooruit aan de stap overslaan op creërend een verwijzingsbeschrijver.

Een nieuwe veldgroep maken

Als u een nieuw veld aan een schema wilt toevoegen, moet u dit eerst definiëren in een veldgroep. U kunt een nieuwe veldgroep maken door een aanvraag voor een POST in te dienen bij het eindpunt van /tenant/fieldgroups .

API formaat

POST /tenant/fieldgroups

Verzoek

Met de volgende aanvraag wordt een nieuwe veldgroep gemaakt die een veld favoriteHotel onder de naamruimte _{TENANT_ID} toevoegt van een schema waaraan het wordt toegevoegd.

curl -X POST\
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/fieldgroups \
  -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 'content-type: application/json' \
  -d '{
        "type": "object",
        "title": "Favorite Hotel",
        "meta:intendedToExtend": ["https://ns.adobe.com/xdm/context/profile"],
        "description": "Favorite hotel field group for the Loyalty Members schema.",
        "definitions": {
            "favoriteHotel": {
              "properties": {
                "_{TENANT_ID}": {
                  "type":"object",
                  "properties": {
                    "favoriteHotel": {
                      "title": "Favorite Hotel",
                      "type": "string",
                      "description": "Favorite hotel for a Loyalty Member."
                    }
                  }
                }
              }
            }
        },
        "allOf": [
            {
              "$ref": "#/definitions/favoriteHotel"
            }
        ]
      }'

Reactie

Een geslaagde reactie retourneert de details van de nieuwe veldgroep.

{
    "$id": "https://ns.adobe.com/{TENANT_ID}/mixins/3387945212ad76ee59b6d2b964afb220",
    "meta:altId": "_{TENANT_ID}.mixins.3387945212ad76ee59b6d2b964afb220",
    "meta:resourceType": "mixins",
    "version": "1.0",
    "type": "object",
    "title": "Favorite Hotel",
    "meta:intendedToExtend": [
        "https://ns.adobe.com/xdm/context/profile"
    ],
    "description": "Favorite hotel field group for the Loyalty Members schema.",
    "definitions": {
        "favoriteHotel": {
            "properties": {
                "_{TENANT_ID}": {
                    "type": "object",
                    "properties": {
                        "favoriteHotel": {
                            "title": "Favorite Hotel",
                            "type": "string",
                            "description": "Favorite hotel for a Loyalty Member.",
                            "meta:xdmType": "string"
                        }
                    },
                    "meta:xdmType": "object"
                }
            },
            "type": "object",
            "meta:xdmType": "object"
        }
    },
    "allOf": [
        {
            "$ref": "#/definitions/favoriteHotel"
        }
    ],
    "meta:xdmType": "object",
    "meta:abstract": true,
    "meta:extensible": true,
    "meta:containerId": "tenant",
    "meta:tenantNamespace": "_{TENANT_ID}",
    "meta:registryMetadata": {
        "eTag": "quM2aMPyb2NkkEiZHNCs/MG34E4=",
        "palm:sandboxName": "prod"
    }
}

Eigenschap

Beschrijving

$id

De alleen-lezen, door het systeem gegenereerde unieke id van de nieuwe veldgroep. De vorm van een URI.

Neem de $id URI van de veldgroep op, die moet worden gebruikt in de volgende stap bij het toevoegen van de veldgroep aan het bronschema.

De veldgroep toevoegen aan het bronschema

Nadat u een veldgroep hebt gemaakt, kunt u deze toevoegen aan het bronschema door een PATCH-aanvraag in te dienen bij het /tenant/schemas/{SCHEMA_ID} -eindpunt.

API formaat

PATCH /tenant/schemas/{SCHEMA_ID}

Parameter

Beschrijving

{SCHEMA_ID}

De URL-gecodeerde $id URI of meta:altId van het bronschema.

Verzoek

Het volgende verzoek voegt de "Favorite Hotel"gebiedsgroep aan het "Loyalty Members"schema toe.

curl -X PATCH \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/schemas/_{TENANT_ID}.schemas.533ca5da28087c44344810891b0f03d9 \
  -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 '[
    {
      "op": "add",
      "path": "/allOf/-",
      "value":  {
        "$ref": "https://ns.adobe.com/{TENANT_ID}/mixins/3387945212ad76ee59b6d2b964afb220"
      }
    }
  ]'

Eigenschap

Beschrijving

op

De uit te voeren PATCH-bewerking. In deze aanvraag wordt de bewerking add gebruikt.

path

De weg aan het schemagebied waar het nieuwe middel zal worden toegevoegd. Wanneer u veldgroepen aan schema's toevoegt, moet de waarde "/allOf/-" zijn.

value.$ref

De $id van de veldgroep die moet worden toegevoegd.

Reactie

Een geslaagde reactie retourneert de details van het bijgewerkte schema, dat nu de $ref -waarde van de toegevoegde veldgroep onder de allOf -array bevat.

{
    "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/2c66c3a4323128d3701289df4468e8a6",
    "meta:altId": "_{TENANT_ID}.schemas.2c66c3a4323128d3701289df4468e8a6",
    "meta:resourceType": "schemas",
    "version": "1.1",
    "type": "object",
    "title": "Loyalty Members",
    "description": "",
    "allOf": [
        {
            "$ref": "https://ns.adobe.com/xdm/context/profile"
        },
        {
            "$ref": "https://ns.adobe.com/xdm/context/profile-person-details"
        },
        {
            "$ref": "https://ns.adobe.com/xdm/context/profile-personal-details"
        },
        {
            "$ref": "https://ns.adobe.com/{TENANT_ID}/mixins/ec16dfa484358f80478b75cde8c430d3"
        },
        {
            "$ref": "https://ns.adobe.com/xdm/context/identitymap"
        },
        {
            "$ref": "https://ns.adobe.com/{TENANT_ID}/mixins/3387945212ad76ee59b6d2b964afb220"
        }
    ],
    "meta:containerId": "tenant",
    "meta:class": "https://ns.adobe.com/xdm/context/profile",
    "meta:abstract": false,
    "meta:extensible": false,
    "meta:tenantNamespace": "_{TENANT_ID}",
    "imsOrg": "{ORG_ID}",
    "meta:extends": [
        "https://ns.adobe.com/xdm/context/profile",
        "https://ns.adobe.com/xdm/data/record",
        "https://ns.adobe.com/xdm/context/identitymap",
        "https://ns.adobe.com/xdm/common/extensible",
        "https://ns.adobe.com/xdm/common/auditable",
        "https://ns.adobe.com/xdm/context/profile-person-details",
        "https://ns.adobe.com/xdm/context/profile-personal-details",
        "https://ns.adobe.com/{TENANT_ID}/mixins/ec16dfa484358f80478b75cde8c430d3",
        "https://ns.adobe.com/{TENANT_ID}/mixins/61969bc646b66a6230a7e8840f4a4d33"
    ],
    "meta:xdmType": "object",
    "meta:registryMetadata": {
        "repo:createdDate": 1557525483804,
        "repo:lastModifiedDate": 1566419670915,
        "xdm:createdClientId": "{API_KEY}",
        "xdm:lastModifiedClientId": "{CLIENT_ID}",
        "eTag": "ITNzu8BVTO5pw9wfCtTTpk6U4WY="
    }
}

Een beschrijving voor een referentie-id maken reference-identity

Op schemavelden moet een identiteitsbeschrijving van de referentie zijn toegepast als deze worden gebruikt als een verwijzing naar een ander schema in een relatie. Aangezien het veld favoriteHotel in "Loyalty Members" verwijst naar het veld hotelId in "Hotels", moet aan favoriteHotel een identiteitsbeschrijvingsreferentie worden gegeven.

Creeer een verwijzingsbeschrijver voor het bronschema door een verzoek van de POST aan het /tenant/descriptors eindpunt te doen.

API formaat

POST /tenant/descriptors

Verzoek

Met de volgende aanvraag wordt een verwijzingsdescriptor gemaakt voor het veld favoriteHotel in het bronschema "Loyalty Members".

curl -X POST \
  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 'Content-Type: application/json' \
  -d '{
    "@type": "xdm:descriptorReferenceIdentity",
    "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/533ca5da28087c44344810891b0f03d9",
    "xdm:sourceVersion": 1,
    "xdm:sourceProperty": "/_{TENANT_ID}/favoriteHotel",
    "xdm:identityNamespace": "Hotel ID"
  }'

Parameter

Beschrijving

@type

Het type descriptor dat wordt gedefinieerd. Voor verwijzingsbeschrijvingen moet de waarde xdm:descriptorReferenceIdentity zijn.

xdm:sourceSchema

De $id URL van het bronschema.

xdm:sourceVersion

Het versienummer van het bronschema.

sourceProperty

Het pad naar het veld in het bronschema dat wordt gebruikt om naar de primaire identiteit van het referentieschema te verwijzen.

xdm:identityNamespace

De naamruimte van de identiteit van het verwijzingsveld. Dit moet dezelfde naamruimte zijn als de primaire identiteit van het referentieschema. Zie het overzicht van identiteitskaart namespacevoor meer informatie.

Reactie

Een succesvol antwoord retourneert de details van de zojuist gemaakte verwijzingsdescriptor voor het bronveld.

{
    "@type": "xdm:descriptorReferenceIdentity",
    "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/533ca5da28087c44344810891b0f03d9",
    "xdm:sourceVersion": 1,
    "xdm:sourceProperty": "/_{TENANT_ID}/favoriteHotel",
    "xdm:identityNamespace": "Hotel ID",
    "meta:containerId": "tenant",
    "@id": "53180e9f86eed731f6bf8bf42af4f59d81949ba6"
}

Relatiebeschrijvingen maken create-descriptor

Relatiebeschrijvingen maken een één-op-één relatie tussen een bronschema en een referentieschema. Zodra u een beschrijver van de verwijzingsidentiteit voor het aangewezen gebied in het bronschema hebt bepaald, kunt u een nieuwe relatiebeschrijver tot stand brengen door een verzoek van de POST aan het /tenant/descriptors eindpunt te doen.

API formaat

POST /tenant/descriptors

Verzoek

Het volgende verzoek leidt tot een nieuwe relatiebeschrijver, met "Loyalty Members"als bronschema en "Hotels"als verwijzingsschema.

curl -X POST \
  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 'Content-Type: application/json' \
  -d '{
    "@type": "xdm:descriptorOneToOne",
    "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/2c66c3a4323128d3701289df4468e8a6",
    "xdm:sourceVersion": 1,
    "xdm:sourceProperty": "/_{TENANT_ID}/favoriteHotel",
    "xdm:destinationSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/d4ad4b8463a67f6755f2aabbeb9e02c7",
    "xdm:destinationVersion": 1,
    "xdm:destinationProperty": "/_{TENANT_ID}/hotelId"
  }'

Parameter

Beschrijving

@type

Het type descriptor dat moet worden gemaakt. De @type -waarde voor relatiebeschrijvingen is xdm:descriptorOneToOne .

xdm:sourceSchema

De $id URL van het bronschema.

xdm:sourceVersion

Het versienummer van het bronschema.

xdm:sourceProperty

Het pad naar het verwijzingsveld in het bronschema.

xdm:destinationSchema

De $id URL van het referentieschema.

xdm:destinationVersion

The version number of the reference schema.

xdm:destinationProperty

Het pad naar het primaire identiteitsveld in het referentieschema.

Antwoord

Een succesvolle reactie retourneert de details van de zojuist gemaakte relatiebeschrijving.

{
    "@type": "xdm:descriptorOneToOne",
    "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/2c66c3a4323128d3701289df4468e8a6",
    "xdm:sourceVersion": 1,
    "xdm:sourceProperty": "/_{TENANT_ID}/favoriteHotel",
    "xdm:destinationSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/d4ad4b8463a67f6755f2aabbeb9e02c7",
    "xdm:destinationVersion": 1,
    "xdm:destinationProperty": "/_{TENANT_ID}/hotelId",
    "meta:containerId": "tenant",
    "@id": "76f6cc7105f4eaab7eb4a5e1cb4804cadc741669"
}

Volgende stappen

Door deze zelfstudie te volgen, hebt u met succes een één-op-één verhouding tussen twee schema's gecreeerd. Voor meer informatie bij het werken met beschrijvers die Schema Registry API gebruiken, zie de de ontwikkelaarsgids van de Registratie van het Schema. Voor stappen op hoe te om schemaverhoudingen in UI te bepalen, zie het leerprogramma op bepalend schemaverhoudingen gebruikend de Redacteur van het Schema.

recommendation-more-help

62e9ffd9-1c74-4cef-8f47-0d00af32fc07