Aan de slag met de Schema Registry API

De Schema Registry Met API kunt u verschillende XDM-bronnen (Experience Data Model) maken en beheren. Dit document verstrekt een inleiding aan de kernconcepten u moet kennen alvorens te proberen vraag aan te maken Schema Registry API.

Vereisten

Voor het gebruik van de handleiding voor ontwikkelaars is een goed begrip van de volgende onderdelen van Adobe Experience Platform vereist:

XDM gebruikt het formatteren van het Schema JSON om de structuur van ingebedde gegevens van de klantenervaring te beschrijven en te bevestigen. Daarom wordt u ten zeerste aangeraden de Officiële JSON-schemadocumentatie voor een beter inzicht in deze onderliggende technologie.

API-voorbeeldaanroepen lezen

De Schema Registry API-documentatie biedt voorbeeld-API-aanroepen om aan te tonen hoe uw aanvragen moeten worden opgemaakt. Dit zijn paden, vereiste kopteksten en correct opgemaakte ladingen voor aanvragen. Voorbeeld-JSON die wordt geretourneerd in API-reacties, wordt ook verschaft. Voor informatie over de conventies die worden gebruikt in documentatie voor voorbeeld-API-aanroepen raadpleegt u de sectie over voorbeeld-API-aanroepen lezen in de gids voor het oplossen van problemen met Experience Platforms.

Waarden verzamelen voor vereiste koppen

Om vraag te maken aan Platform API's, moet u eerst de verificatiezelfstudie. Het voltooien van de zelfstudie over verificatie biedt de waarden voor elk van de vereiste kopteksten in alle Experience Platform API-aanroepen, zoals hieronder wordt getoond:

Alle bronnen in Experience Platform, met inbegrip van die welke tot de Schema Registry, geïsoleerd naar specifieke virtuele sandboxen. Alle verzoeken aan Platform API's vereisen een header die de naam aangeeft van de sandbox waarin de bewerking plaatsvindt:

Alle opzoekverzoeken (GET) aan de Schema Registry aanvullende Accept header, wiens waarde de indeling van de informatie bepaalt die door de API wordt geretourneerd. Zie de Koptekst accepteren voor meer informatie hieronder.

Alle verzoeken die een nuttige lading (POST, PUT, PATCH) bevatten vereisen een extra kopbal:

Weet uw TENANT_ID know-your-tenant_id

In de API-hulplijnen worden verwijzingen naar een TENANT_ID. Deze id wordt gebruikt om ervoor te zorgen dat bronnen die u maakt, op de juiste wijze worden benoemd en zich binnen uw organisatie bevinden. Als u uw id niet kent, kunt u deze openen door de volgende GET-aanvraag uit te voeren:

API-indeling

GET /stats

Verzoek

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

Antwoord

Een succesvolle reactie keert informatie betreffende het gebruik van uw organisatie van terug Schema Registry. Dit omvat een tenantId attribuut, waarvan de waarde uw is 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."
      }
    ]
  }
 }

Begrijp het CONTAINER_ID container

verzoekt de Schema Registry API vereist het gebruik van een CONTAINER_ID. Er zijn twee containers waartegen API-aanroepen kunnen worden uitgevoerd: de global en de tenant container.

Algemene container

De global houder bevat alle standaard Adobe en Experience Platform de partner verstrekte klassen, de groepen van het schemagebied, gegevenstypes, en schema's. U kunt lijst en raadpleging (GET) verzoeken tegen slechts uitvoeren global container.

Een voorbeeld van een vraag die gebruikt global de container ziet er als volgt uit:

GET /global/classes

Trekcontainer

Niet verward met je unieke TENANT_IDde tenant container bevat alle klassen, veldgroepen, gegevenstypen, schema's en descriptoren die door een organisatie zijn gedefinieerd. Deze zijn uniek voor elke organisatie, die betekent zij niet zichtbaar of handelbaar door andere organisaties zijn. U kunt alle CRUD-bewerkingen (GET, POST, PUT, PATCH, DELETE) uitvoeren tegen bronnen die u maakt in het dialoogvenster tenant container.

Een voorbeeld van een vraag die gebruikt tenant de container ziet er als volgt uit:

POST /tenant/fieldgroups

Wanneer u een klasse, veldgroep, schema of gegevenstype maakt in het dialoogvenster tenant container, wordt het opgeslagen in de Schema Registry en een $id URI die uw TENANT_ID. Dit $id wordt in de gehele API gebruikt om naar specifieke bronnen te verwijzen. Voorbeelden van $id waarden worden gegeven in de volgende sectie.

Bronidentificatie resource-identification

XDM-bronnen worden geïdentificeerd met een $id attribuut in de vorm van URI, zoals de volgende voorbeelden:

Om URI meer REST-vriendelijk te maken, hebben de schema's ook een punt-aantekening codering van URI in een genoemd bezit meta:altId:

verzoekt de Schema Registry API ondersteunt de URL-codering $id URI of de meta:altId (puntnotatie). U kunt het beste de URL-codering gebruiken $id URI wanneer het maken van een REST vraag aan API, als zo:

Koptekst accepteren accept

Wanneer u lijst- en opzoekbewerkingen (GET) uitvoert in het dialoogvenster Schema Registry API, en Accept header is vereist om de indeling van de gegevens te bepalen die door de API worden geretourneerd. Wanneer u specifieke bronnen opzoekt, moet u ook een versienummer opnemen in het dialoogvenster Accept header.

De volgende tabel bevat compatibele Accept headerwaarden, inclusief waarden met versienummers, samen met beschrijvingen van wat de API retourneert wanneer deze worden gebruikt.

Schema versioning versioning

Er wordt naar schemaversies verwezen door Accept headers in de Schema Registry API en in schemaRef.contentType eigenschappen in downstream Platform service-API-ladingen.

Platform ondersteunt momenteel slechts één hoofdversie (1) voor elk schema. Volgens de regels voor schemaontwikkeling, moet elke update van een schema niet-destructief zijn, wat betekent dat nieuwe kleine versies van een schema (1.2, 1.3, enz.) zijn altijd achterwaarts compatibel met eerdere secundaire versies. Daarom bij het specificeren van version=1, retourneert het Schemaregister altijd de nieuwste hoofdversie 1 van een schema, wat betekent dat vorige secundaire versies niet worden geretourneerd.

Beperkingen en aanbevolen procedures voor XDM-velden

De velden van een schema worden weergegeven binnen het schema properties object. Elk veld is zelf een object dat kenmerken bevat voor het beschrijven en beperken van de gegevens die het veld kan bevatten. Raadpleeg de handleiding op aangepaste velden in de API definiëren voor codesteekproeven en facultatieve beperkingen voor de meest algemeen gebruikte gegevenstypes.

In het volgende voorbeeldveld wordt een correct opgemaakt XDM-veld weergegeven met nadere informatie over de naamgevingsbeperkingen en de onderstaande aanbevolen procedures. Deze praktijken kunnen ook worden toegepast wanneer het bepalen van andere middelen die gelijkaardige attributen bevatten.

"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.",
}

Volgende stappen

Beginnen het maken vraag gebruikend Schema Registry API, selecteert u een van de beschikbare eindpunthulplijnen.