The Schema Registry Med API kan du skapa och hantera olika XDM-resurser (Experience Data Model). Det här dokumentet innehåller en introduktion till de centrala koncept du behöver känna innan du försöker ringa till Schema Registry API.
För att du ska kunna använda utvecklarhandboken måste du ha en fungerande förståelse för följande komponenter i Adobe Experience Platform:
XDM använder JSON-schemaformatering för att beskriva och validera strukturen för importerade kundupplevelsedata. Vi rekommenderar därför att du granskar officiell dokumentation för JSON-schema för en bättre förståelse av denna underliggande teknik.
The Schema Registry API-dokumentationen innehåller exempel på API-anrop som visar hur du formaterar dina begäranden. Det kan vara sökvägar, obligatoriska rubriker och korrekt formaterade begärandenyttolaster. Ett exempel på JSON som returneras i API-svar finns också. Information om konventionerna som används i dokumentationen för exempel-API-anrop finns i avsnittet om läsa exempel-API-anrop i felsökningsguiden för Experience Platform.
För att ringa Platform API:er måste du först slutföra självstudiekurs om autentisering. När du är klar med självstudiekursen för autentisering visas värdena för var och en av de obligatoriska rubrikerna i alla Experience Platform API-anrop enligt nedan:
Authorization: Bearer {ACCESS_TOKEN}
x-api-key: {API_KEY}
x-gw-ims-org-id: {ORG_ID}
Alla resurser i Experience Platform, inklusive de som tillhör Schema Registry, isoleras till specifika virtuella sandlådor. Alla förfrågningar till Platform API:er kräver en rubrik som anger namnet på sandlådan som åtgärden ska utföras i:
x-sandbox-name: {SANDBOX_NAME}
Mer information om sandlådor i Platform, se sandlådedokumentation.
Alla sökbegäranden (GET) till Schema Registry kräver ytterligare Accept
header, vars värde bestämmer formatet för den information som returneras av API:t. Se Acceptera rubrik för mer information.
Alla begäranden som innehåller en nyttolast (POST, PUT, PATCH) kräver ytterligare en rubrik:
Content-Type: application/json
I hela API-guiderna ser du referenser till en TENANT_ID
. Detta ID används för att säkerställa att de resurser du skapar namnges korrekt och finns i din organisation. Om du inte känner till ditt ID kan du få åtkomst till det genom att utföra följande GET-förfrågan:
API-format
GET /stats
Begäran
curl -X GET \
https://platform.adobe.io/data/foundation/schemaregistry/stats \
-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 svar returnerar information om din organisations användning av Schema Registry. Detta inkluderar tenantId
-attribut, vars värde är ditt TENANT_ID
.
{
"imsOrg":"{ORG_ID}",
"tenantId":"{TENANT_ID}",
"counts": {
"schemas": 4,
"mixins": 3,
"datatypes": 1,
"classes": 2,
"unions": 0,
},
"recentlyCreatedResources": [
{
"title": "Sample Field Group",
"description": "New Sample Field Group.",
"meta:resourceType": "mixins",
"meta:created": "Sat Feb 02 2019 00:24:30 GMT+0000 (UTC)",
"version": "1.1"
},
{
"$id": "https://ns.adobe.com/{TENANT_ID}/classes/5bdb5582be0c0f3ebfc1c603b705764f",
"title": "Tenant Class",
"description": "Tenant Defined Class",
"meta:resourceType": "classes",
"meta:created": "Fri Feb 01 2019 22:46:21 GMT+0000 (UTC)",
"version": "1.0"
}
],
"recentlyUpdatedResources": [
{
"title": "Sample Field Group",
"description": "New Sample Field Group.",
"meta:resourceType": "mixins",
"meta:updated": "Sat Feb 02 2019 00:34:06 GMT+0000 (UTC)",
"version": "1.1"
},
{
"title": "Data Schema",
"description": "Schema for Data Information",
"meta:resourceType": "schemas",
"meta:updated": "Fri Feb 01 2019 23:47:43 GMT+0000 (UTC)",
"meta:class": "https://ns.adobe.com/{TENANT_ID}/classes/47b2189fc135e03c844b4f25139d10ab",
"meta:classTitle": "Sample Class",
"version": "1.1"
}
],
"classUsage": {
"https://ns.adobe.com/{TENANT_ID}/classes/47b2189fc135e03c844b4f25139d10ab": [
{
"$id": "https://ns.adobe.com/{TENANT_ID}/schemas/274f17bc5807ff307a046bab1489fb18",
"title": "Tenant Data Schema",
"description": "Schema for tenant-specific data."
}
],
"https://ns.adobe.com/xdm/context/profile": [
{
"$id": "https://ns.adobe.com/{TENANT_ID}/schemas/3ac6499f0a43618bba6b138226ae3542",
"title": "Simple Profile",
"description": "A simple profile schema."
},
{
"$id": "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
"title": "Program Schema",
"description": "Schema for program-related data."
},
{
"$id": "https://ns.adobe.com/{TENANT_ID}/schemas/4025a705890c6d4a4a06b16f8cf6f4ca",
"title": "Sample Schema",
"description": "A sample schema."
}
]
}
}
CONTAINER_ID
Anropar Schema Registry API kräver att en CONTAINER_ID
. Det finns två behållare som API-anrop kan göras mot: den global
behållare och tenant
behållare.
The global
behållaren innehåller alla Adobe och Experience Platform partnertillhandahållna klasser, schemafältgrupper, datatyper och scheman. Du får endast utföra list- och sökbegäranden (GET) mot global
behållare.
Ett exempel på ett anrop som använder global
container skulle se ut så här:
GET /global/classes
Inte för att förväxlas med din unika TENANT_ID
, tenant
behållare innehåller alla klasser, fältgrupper, datatyper, scheman och beskrivningar som definierats av en organisation. De är unika för varje organisation, vilket innebär att de inte är synliga eller hanterbara av andra organisationer. Du kan utföra alla CRUD-åtgärder (GET, POST, PUT, PATCH, DELETE) mot resurser som du skapar i dialogrutan tenant
behållare.
Ett exempel på ett anrop som använder tenant
container skulle se ut så här:
POST /tenant/fieldgroups
När du skapar en klass, fältgrupp, schema eller datatyp i tenant
behållaren sparas den i Schema Registry och har tilldelats en $id
URI som innehåller TENANT_ID
. Detta $id
används i hela API:t för att referera till specifika resurser. Exempel på $id
värden anges i nästa avsnitt.
XDM-resurser identifieras med en $id
i form av en URI, som följande exempel:
https://ns.adobe.com/xdm/context/profile
https://ns.adobe.com/{TENANT_ID}/schemas/7442343-abs2343-21232421
För att göra URI:n mer REST-vänlig har scheman även en punktnotation-kodning av URI:n i en egenskap som kallas meta:altId
:
_xdm.context.profile
_{TENANT_ID}.schemas.7442343-abs2343-21232421
Anropar Schema Registry API har stöd för antingen URL-kodad $id
URI eller meta:altId
(punktnotationsformat). Det bästa sättet är att använda den URL-kodade $id
URI när du gör ett REST-anrop till API:
https%3A%2F%2Fns.adobe.com%2Fxdm%2Fcontext%2Fprofile
https%3A%2F%2Fns.adobe.com%2F{TENANT_ID}%2Fschemas%2F7442343-abs2343-21232421
När du utför list- och uppslagsåtgärder (GET) i Schema Registry API, och Accept
måste anges för att formatet för de data som returneras av API:t ska kunna fastställas. När du söker efter specifika resurser måste ett versionsnummer också inkluderas i Accept
header.
I följande tabell visas kompatibla Accept
rubrikvärden, inklusive de med versionsnummer, tillsammans med beskrivningar av vad API:t returnerar när de används.
Acceptera | Beskrivning |
---|---|
application/vnd.adobe.xed-id+json |
Returnerar endast en lista med ID:n. Detta används oftast för att lista resurser. |
application/vnd.adobe.xed+json |
Returnerar en lista med det fullständiga JSON-schemat med det ursprungliga $ref och allOf ingår. Detta används för att returnera en lista med fullständiga resurser. |
application/vnd.adobe.xed+json; version=1 |
Raw XDM med $ref och allOf . Har rubriker och beskrivningar. |
application/vnd.adobe.xed-full+json; version=1 |
$ref attribut och allOf löstes. Har rubriker och beskrivningar. |
application/vnd.adobe.xed-notext+json; version=1 |
Raw XDM med $ref och allOf . Inga rubriker eller beskrivningar. |
application/vnd.adobe.xed-full-notext+json; version=1 |
$ref attribut och allOf löstes. Inga rubriker eller beskrivningar. |
application/vnd.adobe.xed-full-desc+json; version=1 |
$ref attribut och allOf löstes. Beskrivningar ingår. |
application/vnd.adobe.xed-deprecatefield+json; version=1 |
$ref och allOf har åtgärdats, har rubriker och beskrivningar. Föråldrade fält indikeras med en meta:status attribut för deprecated . |
Plattformen har för närvarande bara stöd för en huvudversion för varje schema (1
). Därför är värdet för version
måste alltid vara 1
när sökningar utförs för att returnera den senaste delversionen av schemat. Mer information om schemaversion finns i underavsnittet nedan.
Schemaversioner refereras av Accept
rubriker i API:t för schemaregister och i schemaRef.contentType
egenskaper i API-nyttolaster för underordnade plattformstjänster.
För närvarande stöder Platform endast en större version (1
) för varje schema. Enligt regler för schemautvecklingmåste varje uppdatering av ett schema vara icke-förstörande, vilket innebär att nya mindre versioner av ett schema (1.2
, 1.3
, osv.) är alltid bakåtkompatibla med tidigare mindre versioner. Därför, när du anger version=1
returnerar schemaregistret alltid senaste huvudversion 1
för ett schema, vilket innebär att tidigare delversioner inte returneras.
Det icke-förstörande kravet för schemautveckling framtvingas först efter att schemat har refererats av en datauppsättning och ett av följande fall är sant:
Om schemat inte har associerats med en datauppsättning som uppfyller något av ovanstående villkor, kan alla ändringar göras i det. I samtliga fall gäller dock att version
finns fortfarande kvar på 1
.
Fälten i ett schema listas i dess properties
-objekt. Varje fält är i sig ett objekt som innehåller attribut som beskriver och begränsar de data som fältet kan innehålla. Se guiden på definiera anpassade fält i API för kodexempel och valfria begränsningar för de vanligaste datatyperna.
I följande exempelfält visas ett korrekt formaterat XDM-fält, med mer information om namnbegränsningar och de bästa metoderna som anges nedan. Dessa metoder kan också användas när du definierar andra resurser som innehåller liknande attribut.
"fieldName": {
"title": "Field Name",
"type": "string",
"format": "date-time",
"examples": [
"2004-10-23T12:00:00-06:00"
],
"description": "Full sentence describing the field, using proper grammar and punctuation.",
}
fieldName
, field_name2
, Field-Name
, field-name_3
_fieldName
fieldName
title
, skrivet i Title Case. Exempel: Field Name
type
.
format
.examples
kan läggas till som en array.description
I förklaras fältet och relevant information om fältdata. Det bör skrivas i fullständiga meningar med tydligt språk så att alla som använder schemat kan förstå fältets avsikt.Börja ringa samtal med Schema Registry API: välj en av de tillgängliga slutpunktsguiderna.