Komma igång med Schema Registry-API:t

Med API:t Schema Registry kan du skapa och hantera olika XDM-resurser (Experience Data Model). Det här dokumentet innehåller en introduktion till de centrala koncept som du behöver känna till innan du försöker anropa API:t Schema Registry.

Förhandskrav

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 starkt att du läser JSON-schemats officiella dokumentation för att få en bättre förståelse för den underliggande tekniken.

Läser exempel-API-anrop

API-dokumentationen för Schema Registry 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 de konventioner som används i dokumentationen för exempel-API-anrop finns i avsnittet Så här läser du exempel-API-anrop i felsökningsguiden för Experience Platform.

Samla in värden för obligatoriska rubriker

För att kunna anropa Platform API:er måste du först slutföra autentiseringssjälvstudiekursen. När du slutför självstudiekursen för autentisering visas värdena för var och en av de obligatoriska rubrikerna i alla Experience Platform API-anrop, vilket visas nedan:

Alla resurser i Experience Platform, inklusive de som tillhör Schema Registry, isoleras till specifika virtuella sandlådor. Alla begäranden till Platform API:er kräver en rubrik som anger namnet på sandlådan som åtgärden ska utföras i:

Alla sökbegäranden (GET) till Schema Registry kräver ytterligare ett Accept-huvud, vars värde bestämmer vilket format som informationen returneras av API:t. Mer information finns i avsnittet Acceptera rubrik nedan.

Alla begäranden som innehåller en nyttolast (POST, PUT, PATCH) kräver ytterligare en rubrik:

Lär känna ditt TENANT_ID know-your-tenant_id

Under 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 godkänt svar returnerar information om din organisations användning av Schema Registry. Detta inkluderar ett tenantId-attribut, vars värde är din 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 förstår container

Anrop till API:t Schema Registry kräver att du använder en CONTAINER_ID. Det finns två behållare som API-anrop kan göras mot: behållaren global och behållaren tenant.

Global behållare

Behållaren global innehåller alla standardklasser som tillhandahålls av Adobe och Experience Platform partner, schemafältgrupper, datatyper och scheman. Du får bara utföra list- och uppslagsbegäranden (GET) mot behållaren global.

Ett exempel på ett anrop som använder behållaren global skulle se ut så här:

GET /global/classes

Klientbehållaren

Behållaren tenant ska inte blandas ihop med din unika TENANT_ID. Den 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 behållaren tenant.

Ett exempel på ett anrop som använder behållaren tenant skulle se ut så här:

POST /tenant/fieldgroups

När du skapar en klass, fältgrupp, schema eller datatyp i behållaren tenant sparas den i Schema Registry och tilldelas en $id URI som innehåller din TENANT_ID. $id används i hela API:t för att referera till specifika resurser. Exempel på $id-värden finns i nästa avsnitt.

Resursidentifiering resource-identification

XDM-resurser identifieras med ett $id-attribut i form av en URI, som i följande exempel:

För att göra URI:n mer REST-vänlig har scheman även en punktnotation-kodning av URI:n i en egenskap med namnet meta:altId:

Anrop till Schema Registry-API:t stöder antingen den URL-kodade $id URI:n eller meta:altId (punktnotation-format). Bästa sättet är att använda den URL-kodade $id-URI:n när du gör ett REST-anrop till API, så här:

Acceptera rubrik accept

När du utför list- och lookup-åtgärder (GET) i API:t Schema Registry krävs en Accept-rubrik för att fastställa formatet för de data som returneras av API:t. När du söker efter specifika resurser måste ett versionsnummer också inkluderas i rubriken Accept.

I följande tabell visas kompatibla rubrikvärden för Accept, inklusive de med versionsnummer, tillsammans med beskrivningar av vad API:t returnerar när de används.

Schemaversion versioning

Schemaversioner refereras av Accept huvuden i API:t för schemaregister och i schemaRef.contentType egenskaper i underordnade API-nyttolaster för plattformstjänster.

För närvarande stöder Platform endast en huvudversion (1) för varje schema. Enligt reglerna för schemautveckling måste varje uppdatering av ett schema vara icke-förstörande, vilket innebär att nya delversioner av ett schema (1.2, 1.3 osv.) är alltid bakåtkompatibla med tidigare mindre versioner. När du anger version=1 returnerar schemaregistret därför alltid schemats senaste huvudversion 1 , vilket innebär att tidigare delversioner inte returneras.

Begränsningar för XDM-fält och bästa praxis

Fälten i ett schema visas 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 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.",
}

Nästa steg

Om du vill börja ringa anrop med API:t Schema Registry väljer du en av de tillgängliga slutpunktsguiderna.