Het eindpunt van descriptors

De schema's bepalen een statische mening van gegevensentiteiten, maar verstrekken geen specifieke details over hoe gegevens die op deze regelingen (datasets, bijvoorbeeld) worden gebaseerd op elkaar kunnen betrekking hebben. Met Adobe Experience Platform kunt u deze relaties en andere interpreterende metagegevens over een schema beschrijven aan de hand van beschrijvingen.

De beschrijvers van het schema zijn huurdersvlakke meta-gegevens, betekenend zij aan uw organisatie uniek zijn en alle beschrijvingsverrichtingen vinden in de huurderscontainer plaats.

Op elk schema kunnen een of meer schemabeschrijvingsentiteiten zijn toegepast. Elke schemadescriptorentiteit bevat een descriptor @type en de sourceSchema waarop deze van toepassing is. Zodra toegepast, zullen deze beschrijvers op alle datasets van toepassing zijn die gebruikend het schema worden gecreeerd.

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 gidsvoor 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 welk Experience Platform API met succes te maken.

Een lijst met descriptoren ophalen list

U kunt alle beschrijvingen weergeven die door uw organisatie zijn gedefinieerd door een aanvraag voor een GET 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, kunt u een afzonderlijke descriptor opzoeken (GET) met de bijbehorende @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 beschrijver tot stand brengen door een verzoek van de POST aan het /tenant/descriptors eindpunt te doen.

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 beschrijvervan 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 a raadpleging (GET) verzoekom de beschrijver te bekijken toont aan dat de gebieden nu zijn bijgewerkt om op de veranderingen te wijzen die in het verzoek van de PUT worden verzonden.

Een descriptor verwijderen delete

Soms moet u een descriptor verwijderen die u in de Schema Registry hebt gedefinieerd. Dit wordt gedaan door een verzoek van de DELETE te doen van verwijzingen @id van de beschrijver die u wenst te 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 raadplegingsverzoektegen de beschrijver @id uitvoeren. De reactie retourneert HTTP-status 404 (Niet gevonden) omdat de descriptor is verwijderd uit de Schema Registry .

Bijlage

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

Een identiteitsbeschrijver signaleert dat "sourceProperty"van "sourceSchema"een Identity gebied is zoals die door wordt beschreven de Dienst van de Identiteit van Adobe 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-descriptors beschrijven een relatie tussen twee verschillende schema's, die u hebt afgesloten op de eigenschappen die worden beschreven in sourceProperty en destinationProperty . Zie het leerprogramma op bepalend een verband tussen twee schema'svoor meer informatie.

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

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