Aan de slag met de Schema Registry API

Met de API van Schema Registry kunt u verschillende XDM-bronnen (Experience Data Model) maken en beheren. Dit document bevat een inleiding op de kernconcepten die u moet kennen voordat u de API van Schema Registry aanroept.

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 sterk geadviseerd dat u de officiële documentatie van het Schema JSONvoor een beter inzicht in deze onderliggende technologie herziet.

API-voorbeeldaanroepen lezen

De API-documentatie van Schema Registry 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 overeenkomsten die in documentatie voor steekproef API vraag worden gebruikt, zie de sectie op hoe te om voorbeeld API vraagin de het oplossen van problemengids van het Experience Platform te lezen.

Waarden verzamelen voor vereiste koppen

Om vraag aan Platform APIs te maken, moet u het authentificatieleerprogrammaeerst voltooien. Als u de zelfstudie over verificatie voltooit, krijgt u de waarden voor elk van de vereiste headers in alle API-aanroepen van Experience Platform , zoals hieronder wordt getoond:

Alle bronnen in Experience Platform, inclusief de bronnen die tot de Schema Registry behoren, zijn geïsoleerd naar specifieke virtuele sandboxen. Alle aanvragen naar Platform API's vereisen een header die de naam van de sandbox opgeeft waarin de bewerking plaatsvindt:

Voor alle opzoekverzoeken (GET) naar de Schema Registry is een extra Accept -header nodig, waarvan de waarde de indeling van de informatie bepaalt die door de API wordt geretourneerd. Zie kopbalhieronder sectie goedkeuren voor meer details.

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 weergegeven. 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 formaat

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

Reactie

Een geslaagde reactie geeft informatie over het gebruik van Schema Registry door uw organisatie. Dit omvat een tenantId -kenmerk, waarvan de waarde uw TENANT_ID is.

{
  "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 CONTAINER_ID container

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

Algemene container

De container global bevat alle standaard Adobe en door Experience Platform verschafte klassen, groepen met schemavelden, gegevenstypen en schema's. U kunt alleen lijst- en opzoekverzoeken (GET) uitvoeren in de global -container.

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

GET /global/classes

Trekcontainer

De tenant -container bevat alle klassen, veldgroepen, gegevenstypen, schema's en beschrijvingen die door een organisatie zijn gedefinieerd, zodat deze niet worden verward met uw unieke TENANT_ID -container. 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 de tenant -container.

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

POST /tenant/fieldgroups

Wanneer u een klasse, veldgroep, schema of gegevenstype maakt in de tenant -container, wordt deze opgeslagen in de Schema Registry en toegewezen aan een $id -URI die de TENANT_ID -container bevat. Deze $id wordt in de gehele API gebruikt om naar specifieke bronnen te verwijzen. In de volgende sectie vindt u voorbeelden van $id -waarden.

Bronidentificatie resource-identification

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

Om de URI REST-vriendelijker te maken, hebben schema's ook een punt-aantekening het coderen van URI in een bezit genoemd meta:altId:

Oproepen aan de Schema Registry API zullen of URL-Gecodeerde $id URI of meta:altId (punt-aantekening formaat) steunen. De beste manier is om de URL-gecodeerde $id URI te gebruiken wanneer u een REST-aanroep naar de API uitvoert, zoals:

Koptekst accepteren accept

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

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

Schema versioning versioning

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

Momenteel, steunt het Platform slechts één enkele belangrijkste versie (1) voor elk schema. Volgens de regels van schemaevolutie, moet elke update aan een schema niet-destructief zijn, betekenend dat nieuwe minder belangrijke versies van een schema (1.2, 1.3, enz.) zijn altijd achterwaarts compatibel met eerdere secundaire versies. Daarom wanneer het specificeren van version=1, keert de Registratie van het Schema altijd de recentste belangrijkste versie 1 van een schema terug, betekenend dat de vorige minder belangrijke versies niet zijn teruggekeerd.

Beperkingen en aanbevolen procedures voor XDM-velden

De velden van een schema worden vermeld in het bijbehorende properties -object. Elk veld is zelf een object dat kenmerken bevat voor het beschrijven en beperken van de gegevens die het veld kan bevatten. Verwijs naar de gids op bepalend douanegebieden in APIvoor codesteekproeven en facultatieve beperkingen voor de het 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

Selecteer een van de beschikbare eindpunthulplijnen als u wilt beginnen met het aanroepen van de API Schema Registry .