Event Streams-schemaregistry Verwenden
Die Schemaregistry stellt ein zentrales Repository für die Verwaltung und Validierung von Schemas bereit. Schemas in einer Schemaregistry stellen den expliziten Vertrag bereit, den ein Programm, das ein Ereignis generiert, für andere Programme bereitstellt, die diese Ereignisse verarbeiten.
Übersicht über Schemas
Apache Kafka kann beliebige Daten handhaben, validiert jedoch die Informationen in den Nachrichten nicht. Allerdings erfordert eine effiziente Handhabung von Daten häufig, dass diese Daten bestimmte Informationen in einem bestimmten Format einschließen. Mithilfe von Schemas können Sie die Struktur der Daten in einer Nachricht definieren und dadurch sicherstellen, dass sowohl Producer als auch Consumer die korrekte Struktur verwenden.
Durch Schemas werden Producer bei der Erstellung von Daten, die einer vordefinierten Struktur entsprechen, dadurch unterstützt, dass in ihnen die Felder, die vorhanden sein müssen, und der Typ jedes Felds definiert werden. Diese Definition hilft den Konsumenten, diese Daten zu analysieren und richtig zu interpretieren. Der Event Streams Enterprise-Plan unterstützt Schemas und enthält eine Schemaregistry für die Verwendung und Verwaltung von Schemas.
Gängigerweise verwenden alle Nachrichten für ein Topic dasselbe Schema. Der Schlüssel und der Wert einer Nachricht kann jeweils durch ein Schema beschrieben werden.
Übersichtsdiagramm für
Schemaregistry
Schemas werden in der Event Streams-Schemaregistry gespeichert. Neben der Speicherung eines versionierten Verlaufsprotokolls stellt die Schemaregistry eine Schnittstelle zum Abrufen der Schemas bereit. Jede Event Streams-Instanz mit Enterprise-Plan besitzt eine eigene Schemaregistry. In einer Unternehmensinstanz können maximal 1000 Schemas gespeichert werden.
Hersteller und Verbraucher validieren die Daten anhand des angegebenen Schemas, das im Schema-Register gespeichert ist (zusätzlich zur Überprüfung durch Kafka-Broker). Die Schemas müssen auf diese Weise nicht in den Nachrichten übertragen werden, sodass Nachrichten kleiner sein können.
Apache Avro-Datenformat
Schemas werden mithilfe von Apache Avro definiert, einer Open-Source-Datenserialisierungstechnologie, die im Allgemeinen mit Apache Kafkaverwendet wird. Apache Avro stellt ein effizientes Datencodierformat entweder durch ein kompaktes Binärformat oder durch ein ausführlicheres und benutzerlesbares JSON-Format bereit.
Die Event Streams-Schemaregistry arbeitet mit Apache Avro-Datenformaten. Wenn Nachrichten im Avro-Format gesendet werden, enthalten sie die Daten und die eindeutige ID für das verwendete Schema. Die ID gibt das Schema in der Registry an, das für die Nachricht zu verwenden ist.
Avro enthält Unterstützung für eine breite Auswahl von Datentypen, zu denen primitive Datentypen (null, boolean, int, long, float, double, bytes und string) und komplexe Datentypen (record, enum, array, map, union und fixed) gehören.
Serialisierung und Deserialisierung
Eine produzierende Anwendung verwendet einen Serializer, um Nachrichten zu erstellen, die einem bestimmten Schema entsprechen. Wie zuvor erwähnt, enthält die Nachricht die Daten im Avro-Format und die Schema-ID.
Eine konsumierende Anwendung verwendet dann einen Deserializer, um Nachrichten zu konsumieren, die unter Verwendung desselben Schemas serialisiert wurden. Wenn ein Verbraucher eine Nachricht liest, die im Avro-Format gesendet wurde, findet der Deserializer den Bezeichner des Schemas in der Nachricht und ruft das Schema aus der Schema-Registry ab, um die Daten zu deserialisieren.
Dieser Prozess bietet eine effiziente Möglichkeit, um sicherzustellen, dass die Daten in den Nachrichten der erforderlichen Struktur entsprechen.
Das Event Streams Schema-Register unterstützt den Kafka AVRO-Serializer und -Deserializer.
Versionen und Kompatibilität
Wenn Sie ein Schema und nachfolgende Versionen desselben Schemas hinzufügen, kann Event Streams das Format automatisch validieren und das Schema ablehnen, wenn Probleme auftreten. Sie können Ihre Schemas mit der Zeit weiterentwickeln, um geänderten Anforderungen Rechnung zu tragen. Erstellen Sie eine neue Version eines vorhandenen Schemas, und die Schema-Registrierung stellt sicher, dass die neue Version mit der vorhandenen Version kompatibel ist, d. h., dass Hersteller und Verbraucher, die die vorhandene Version verwenden, durch die neue Version nicht beeinträchtigt werden.
Schemata werden verglichen, um die Erstellung doppelter Schemata zu vermeiden, bei denen sich die Schemata nur auf eine Weise unterscheiden, die sich nicht auf die Semantik des Schemas auswirkt. In manchen Fällen kann die Reihenfolge der JSON-Eigenschaften innerhalb eines Schemas entscheidend dafür sein, wie das Schema für die Codierung und Decodierung von Daten verwendet wird, aber in anderen Fällen sind sie möglicherweise nicht relevant.
Beispielsweise wird die Eigenschaft name eines Datensatzschemas nicht als Teil des Codierungs-und Decodierungsprozesses verwendet, sodass Sie sie an einer beliebigen Stelle im JSON-Datensatzobjekt positionieren können. Alle diese
Varianten werden als dasselbe Schema betrachtet.
Die Eigenschaft fields in der JSON eines Datensatzschemas ist ein Fall, bei dem die Reihenfolge wichtig ist. Die Avro-Spezifikation erfordert, dass die Felder eines Datensatzes in der Reihenfolge codiert und decodiert werden, in
der sie in dem Schema erscheinen, das für die Codierungs-und Decodieroperation verwendet wird.
Betrachten Sie als Beispiel die folgenden drei Schemata.
Schema 1
{
"type": "record",
"name": "book",
"fields": [
{
"name": "title",
"type": "string"
},
{
"name": "author",
"type": "string"
}
]
}
Schema 2
{
"type": "record",
"name": "book",
"fields": [
{
"name": "author",
"type": "string"
},
{
"name": "title",
"type": "string"
}
]
}
Schema 3
{
"type": "record",
"name": "book",
"fields": [
{
"type": "string"
"name": "author",
},
{
"type": "string"
"name": "title",
}
]
}
Schema 1 und Schema 2 sind unterschiedliche Schemata und die Registry speichert sie als separate Schemata. Sie können nicht austauschbar verwendet werden, weil sie die Felder author und title in einer anderen Reihenfolge
auflisten. Mit Schema 1 codierte Daten werden nicht korrekt decodiert, wenn der Decodierungsprozess Schema 2 verwendet.
Wenn Sie das SerDes verwenden, um das neue Schema in der Reihenfolge Schema 1, Schema 2 und Schema 3 zu erstellen, erhalten Sie zwei neue Schemas. Schema 1 und Schema 2 unterscheiden sich, aber Schema 3 entspricht Schema 2.
Wenn Sie Schemas mithilfe der REST-API erstellen, werden Schemas nur dann als übereinstimmend betrachtet, wenn sie textgleich sind, einschließlich aller Attributsortierungs-und beschreibenden Felder. Dies gilt für den Fall, dass Schema 3 ein anderes Schema sein soll.
Schemaregistry aktivieren
Die Schemaregistry wird für Event Streams-Serviceinstanzen des Enterprise-Plans standardmäßig aktiviert. Die Schemaregistry ist für andere Event Streams-Pläne nicht verfügbar.
Auf die Schemaregistry zugreifen
Um auf das Schema-Register zuzugreifen, benötigen Sie die URL des Schema-Registers, die sich in den Dienstanmeldeinformationen Ihres Dienstes befindet. Um diese Anmeldedaten in der Benutzeroberfläche anzuzeigen, klicken Sie auf Ihre Service-Instanz, wählen Sie im linken Navigationsbereich "Service-Anmeldedaten" aus und klicken Sie dann auf den Link "Anmeldedaten anzeigen " neben einer der in der Tabelle aufgeführten Service-Anmeldedaten:
Diagramm der
Der Wert von kafka_http_url ist auch der URL des Schema-Registers.
Authentifizierung
Für den Zugriff auf die Schemaregistry benötigen Sie außerdem eine Gruppe von Berechtigungsnachweisen, die für die Authentifizierung bei der Registry verwendet werden können. Es gibt zwei Optionen: Basisauthentifizierung mit einem API-Schlüssel oder Trägertokenauthentifizierung.
Die Beispiele in diesem Dokument zeigen die Verwendung des API-Schlüssels, aber es können beide Optionen verwendet werden.
Authentifizierung mit API-Schlüssel
Die Serviceberechtigungsnachweise verfügen über eine apikey, die Sie als Berechtigungsnachweis für die Authentifizierung bei der Schemaregistry verwenden können.
Sie können sich auch mit einem API-Schlüssel authentifizieren, der von einer Service-ID vergeben wurde, vorausgesetzt, die Service-ID verfügt über eine Richtlinie, die mindestens den Zugriff auf die Event Streams-Instanz in der Rolle "Leser" zulässt. Dieses Konzept ist flexibler und eine bessere Wahl, wenn Sie den Zugriff mehreren Personen oder Teams erteilen. Lesen Sie die weiteren Informationen im Hilfethema Zugriff auf Ihre Event Streams-Ressourcen verwalten.
Der API-Schlüssel wird als Passwort-Teil eines HTTP-Basisauthentifizierungs-Headers bereitgestellt. Der Benutzernamensteil des Headers ist das Wort "token".
Der zu verwendende curl-Befehl lautet wie folgt, wobei $APIKEY durch Ihren API-Schlüssel ersetzt wird:
curl -u token:$APIKEY ...
Authentifizierung mit Trägertoken
Es ist auch möglich, einen Träger-Token für eine System-ID oder einen Benutzer als Berechtigungsnachweis zu verwenden. Dies ist im Allgemeinen ein sicherer Ansatz, da es weniger Potenzial für die Bereitstellung des API-Schlüssels hat und das Trägertoken nach einiger Zeit automatisch abläuft.
Um ein Token abzurufen, verwenden Sie den Befehl IBM Cloud CLI ibmcloud iam oauth-tokens, um das Token zu generieren. Fügen Sie dieses Token in eine HTTP-Kopfzeile im Format "Authorization: Bearer $TOKEN" ein, wobei
$TOKEN das Bearer-Token ist:
curl -H "Authorization: Bearer $TOKEN" ...
Daten aus anderen Schemaregistern importieren
Sie können Daten in das Schema-Registry importieren, die aus anderen Schema-Registrys exportiert wurden. Wenn Daten importiert werden, wird die globale ID, die jeder Artefaktversion zugeordnet ist, beibehalten. Dies bedeutet, dass Sie weiterhin Daten verwenden können, die bereits in Kafka mit denselben Werten für die globale Schema-ID gespeichert sind.
Die Event Streams-CLI unterstützt den Import von Daten im Import-und Exportformat der Apicurio-Registry wie im folgenden Beispiel.
ibmcloud es schema-import import.zip
Sie können die zu importierenden Daten mit dem Apicurio-Registry-Dienstprogramm exportConfluent generieren, das Daten aus einer Confluent-Schemaregistry exportiert. Event Streams wurde getestet mit Version 2.6.x dieses Dienstprogramms.
Wenn die Schemaregistry von Event Streams bereits über einen Eintrag mit derselben globalen ID wie eine Artefaktversion verfügt, die importiert wird, schlägt die Importoperation fehl und Sie werden zum Entfernen der Artefaktversion aufgefordert, wenn Sie fortfahren möchten.
REST-Endpunkte für die Schemaregistry
Die REST-API stellt vier Hauptfunktionen bereit:
- Schemas erstellen, lesen und löschen
- Einzelne Versionen eines Schemas erstellen, lesen und löschen
- Globale Kompatibilitätsregel für die Registry lesen und aktualisieren
- Kompatibilitätsregeln für einzelne Schemas erstellen, lesen, aktualisieren und löschen
Für Aktionen, die die Schemaversion ändern, wie zum Beispiel das Erstellen, Aktualisieren oder Löschen von Artefakten, Artefaktversionen und Regeln, wird ein Activity Tracker-Ereignis generiert, um die Aktion zu melden. Weitere Informationen finden Sie unter Activity Tracker-Ereignisse.
Fehler
Wenn ein Fehlerzustand auftritt, gibt die Schema-Registrierung einen non-2XX-Bereich HTTP-Statuscode zurück. Der Hauptteil der Antwort enthält ein JSON-Objekt in der folgenden Form:
{
"error_code":404,
"message":"No artifact with id 'my-schema' might be found."
}
Die Eigenschaften des JSON-Fehlerobjekts sind folgende:
| Eigenschaftsname | Beschreibung |
|---|---|
| error_code | Der HTTP-Statuscode der Antwort. |
| Nachricht | Eine Beschreibung der Problemursache. |
| Vorfall | Dieses Feld ist nur enthalten, wenn der Fehler das Resultat eines Problems mit der Schemaregistry ist. Anhand dieses Werts kann vom IBM Service eine Anforderung mit Diagnoseinformationen korreliert werden, die durch die Registry erfasst werden. |
Schemastatus festlegen
Dieser Endpunkt wird verwendet, um den Status eines Schemas in der Registry auf ENABLED oder DISABLED zu setzen. Der Status eines Schemas kann durch Absetzen einer PUT-Anforderung an den Endpunkt /artifacts/{schema-id}/state festgelegt werden (dabei ist {schema-id} die ID des Schemas). Wenn die Anfrage erfolgreich ist, wird eine leere Antwort und ein Statuscode von 204 (kein Inhalt) zurückgegeben.
Beispiel für curl-Anforderung:
curl -u token:$APIKEY –X PUT $URL/artifacts/my-schema/state -d '{"state": "DISABLED"}'
Das Festlegen eines Schemastatus erfordert Folgendes:
- Zugriff auf die Schema-Ressource, die dem geänderten Schema entspricht, für Manager-Rollen.
Schemaversionsstatus festlegen
Dieser Endpunkt wird verwendet, um den Status einer Schemaversion in der Registry auf ENABLED oder DISABLED zu setzen. Der Status einer Schemaversion kann durch Absetzen einer PUT-Anforderung an den Endpunkt /artifacts/{schema-id}/versions/{version}/state festgelegt werden (dabei ist {schema-id} die ID des Schemas und {version} die Versionsnummer der Schemaversion). Wenn die Anfrage erfolgreich ist, wird eine leere Antwort und ein Statuscode von 204 (kein Inhalt) zurückgegeben.
Beispiel für curl-Anforderung:
curl -u token:$APIKEY –X PUT $URL/artifacts/my-schema/versions/1/state -d '{"state": "DISABLED"}'
Das Festlegen eines Schemaversionsstatus erfordert Folgendes:
- Zugriff auf die Schema-Ressource, die dem zu ändernden Schema entspricht, für Manager-Rollen.
Schema erstellen
Dieser Endpunkt wird zum Speichern eines Schemas in der Registry verwendet. Die Schemadaten werden im Hauptteil der POST-Anforderung gesendet. Eine ID für das Schema kann über den Anforderungsheader ‘X-Registry-ArtifactId' hinzugefügt werden. Wenn dieser Header in der Anfrage nicht vorhanden ist, wird eine ID generiert. Der Inhaltstypheader ('Content-Type') muss auf den Wert “application/json” gesetzt werden.
Beispiel für curl-Anforderung:
curl -u token:$APIKEY -H 'Content-Type: application/json' -H 'X-Registry-ArtifactId: my-schema' $URL/artifacts -d '{"type":"record","name":"Citizen","fields":[{"name": "firstName","type":"string"},{"name":"lastName","type":"string"},{"name":"age","type":"int"},{"name":"phoneNumber","type":"string"}]}'
Beispielantwort:
{"id":"my-schema","type":"AVRO","version":1,"createdBy":"","createdOn":1579267788258,"modifiedBy":"","modifiedOn":1579267788258,"globalId":75}
Für das Erstellen eines Schemas sind mindestens die beiden folgenden Zugriffsrollen erforderlich:
- Rolle eines Leseberechtigten für den Zugriff auf den Ressourcentyp des Event Streams-Clusters
- Zugriff des Writer-Rollen auf die Schema-Ressource, die dem erstellten Schema entspricht.
Es wird ein Activity Tracker-Ereignis generiert, um die Aktion zu melden. Weitere Informationen finden Sie unter Activity Tracker-Ereignisse.
Schemas auflisten
Sie können eine Liste der IDs aller Schemata erstellen, die in der Registrierung gespeichert sind, indem Sie eine GET-Anfrage an den Endpunkt /artifacts senden. Sie können die Antwort mit dem Parameter jsonformat formatieren (nur
die Formate string und object werden unterstützt). Das Zeichenfolgeformat ist der Standardwert und gibt ein Array von Artefakt-IDs (Zeichenfolgen) zurück. Wenn diese Optionen festgelegt sind, werden nur aktivierte
Artefakte in das Array eingeschlossen. Das Objektformat gibt ein JSON-Objekt zurück, das ein Array enthält, wobei jeder Eintrag im Array einem Artefakt in der Registry entspricht. Sowohl aktivierte als auch inaktivierte Artefakte werden
zurückgegeben, wenn diese Option festgelegt ist.
Beispiel für curl-Anforderung:
curl -u token:$APIKEY $URL/artifacts
oder
curl -u token:$APIKEY $URL/artifacts?jsonformat=string
oder
curl -u token:$APIKEY $URL/artifacts?jsonformat=object
Beispielantwort, wenn jsonformat string ist oder nicht angegeben wird (standardmäßig wird string verwendet):
["my-schema-2","my-schema-4"]
Beispielantwort, wenn jsonformat object ist:
{"artifacts":[{"id":"my-schema","state":"DISABLED"},{"id":"my-schema-2","state":"ENABLED"},{"id":"my-schema-3","state":"DISABLED"},{"id":"my-schema-4","state":"ENABLED"}],"count":4}
Zum Auflisten von Schemas ist mindestens die folgende Zugriffsrolle erforderlich:
- Rolle eines Leseberechtigten für den Zugriff auf den Ressourcentyp des Event Streams-Clusters
Status und Löschung von Schemas
Das Löschen eines Schemas ist ein zweistufiger Prozess. In der ersten Phase des Löschvorgangs wird das Schema in der Registry beibehalten, aber vor einigen Operationen ausgeblendet. Die zweite Stufe entfernt das Schema permanent, kann aber nur nach der ersten Stufe angewendet werden. Der zweistufige Löschprozess gilt auf Artefaktebene und auch auf Versionsebene.
Die beiden Phasen des Löschens werden ausgeführt, indem sowohl Artefakten als auch Versionen (erste Stufe) der Status 'Aktiviert' oder 'Inaktiviert' zugeordnet wird und indem APIs für Ressourcen und Versionen (zweite Stufe) gelöscht werden.
Ein Artefakt oder eine Version, die inaktiviert wurde, kann mithilfe einer Eigenschaft 'state' erkannt werden, die von Operationen zurückgegeben wird, die Artefakte oder Versionen auflisten, oder indem die Details eines Artefakts oder einer Version abgerufen werden. Inaktivierte Schemas werden für das Schemakontingent von 1000 Schemas pro Unternehmensinstanz gezählt.
Schema löschen
Schemas werden aus der Registrierung gelöscht, indem eine DELETE-Anfrage an den Endpunkt /artifacts/{schema-id} gesendet wird (wobei {schema-id} die ID des Schemas ist). Bei erfolgreicher Ausführung wird eine leere Antwort und
der Statuscode 204 (kein Inhalt) zurückgegeben.
Beispiel für curl-Anforderung:
curl -u token:$APIKEY -X DELETE $URL/artifacts/my-schema
Für das Löschen eines Schemas sind mindestens die beiden folgenden Zugriffsrollen erforderlich:
- Rolle eines Leseberechtigten für den Zugriff auf den Ressourcentyp des Event Streams-Clusters
- Zugriff auf die Schema-Ressource, die dem gelöschten Schema entspricht, für Manager-Rollen.
Es wird ein Activity Tracker-Ereignis generiert, um die Aktion zu melden. Weitere Informationen finden Sie unter Activity Tracker-Ereignisse.
Neue Version eines Schemas erstellen
Um eine neue Version eines Schemas zu erstellen, senden Sie eine POST-Anfrage an den Endpunkt /artifacts/{schema-id}/versions (wobei {schema-id} die ID des Schemas ist). Der Hauptteil der Anforderung muss die neue Version des
Schemas enthalten.
Wenn die Anfrage erfolgreich ist, wird das neue Schema als neueste Version des Schemas mit einer entsprechenden Versionsnummer erstellt und eine Antwort mit dem Statuscode 200 (OK) und einer Nutzlast, die Metadaten zur Beschreibung der neuen Version (einschließlich der Versionsnummer) enthält, zurückgegeben.
Beispiel für curl-Anforderung:
curl -u token:$APIKEY -H 'Content-Type: application/json' $URL/artifacts/my-schema/versions -d '{"type":"record","name":"Citizen","fields":[{"name": "firstName","type":"string"},{"name":"lastName","type":"string"},{"name":"age","type":"int"},{"name":"phoneNumber","type":"string"}]}'
Beispielantwort:
{"id":"my-schema","type":"AVRO","version":2,"createdBy":"","createdOn": 1579267978382,"modifiedBy":"","modifiedOn":1579267978382,"globalId":83}
Für das Erstellen einer neuen Version eines Schemas sind mindestens die beiden folgenden Zugriffsrollen erforderlich:
- Rolle eines Leseberechtigten für den Zugriff auf den Ressourcentyp des Event Streams-Clusters
- Zugriff der Rolle "Writer" auf die Schemaressource, die dem Schema entspricht, das eine neue Version erhält.
Es wird ein Activity Tracker-Ereignis generiert, um die Aktion zu melden. Weitere Informationen finden Sie unter Activity Tracker-Ereignisse.
Neueste Version eines Schemas abrufen
Um die neueste Version eines bestimmten Schemas abzurufen, senden Sie eine GET-Anfrage an den Endpunkt /artifacts/{schema-id} (wobei {schema-id} die ID des Schemas ist). Ist die Anforderung erfolgreich, wird die neueste Version
des Schemas in den Nutzdaten der Antwort zurückgegeben.
Beispiel für curl-Anforderung:
curl -u token:$APIKEY $URL/artifacts/my-schema
Beispielantwort:
{"type":"record","name":"Citizen","fields":[{"name": "firstName","type":"string"},{"name":"lastName","type":"string"},{"name":"age","type":"int"},{"name":"phoneNumber","type":"string"}]}
Für den Abruf der neuesten Version eines Schemas sind mindestens die beiden folgenden Zugriffsrollen erforderlich:
- Rolle eines Leseberechtigten für den Zugriff auf den Ressourcentyp des Event Streams-Clusters
- Zugriff der Reader-Rolle auf die Schemaressource, die dem abgerufenen Schema entspricht.
Bestimmte Version eines Schemas abrufen
Um eine bestimmte Version eines Schemas abzurufen, senden Sie eine GET-Anfrage an den Endpunkt /artifacts/{schema-id}/versions/{version} (wobei {schema-id} die ID des Schemas und {version} die Versionsnummer der spezifischen Version
ist, die Sie abrufen möchten). Ist die Anforderung erfolgreich, wird die angegebene Version des Schemas in den Nutzdaten der Antwort zurückgegeben.
Beispiel für die Curl-Anforderung:
curl -u token:$APIKEY $URL/artifacts/my-schema/versions/3
Beispielantwort:
{"type":"record","name":"Citizen","fields":[{"name": "firstName","type":"string"},{"name":"lastName","type":"string"},{"name":"age","type":"int"},{"name":"phoneNumber","type":"string"}]}
Für den Abruf der neuesten Version eines Schemas sind mindestens die beiden folgenden Zugriffsrollen erforderlich:
- Rolle eines Leseberechtigten für den Zugriff auf den Ressourcentyp des Event Streams-Clusters
- Zugriff der Reader-Rolle auf die Schemaressource, die dem abgerufenen Schema entspricht.
Alle Versionen eines Schemas auflisten
Um alle Versionen eines Schemas aufzulisten, die derzeit in der Registrierung gespeichert sind, senden Sie eine GET-Anfrage an den Endpunkt /artifacts/{schema-id}/versions (wobei {schema-id} die ID des Schemas ist). Ist die Anforderung
erfolgreich, wird eine Liste aller aktuellen Versionsnummern für das Schema in den Nutzdaten der Antwort zurückgegeben. Sie können die Antwort mit dem Parameter jsonformat formatieren (nur die Formate number und object werden unterstützt). Wenn Sie 'number' (Standardwert) angeben, ist die Antwort ein Array numerischer Werte, die aktivierten Versionen des Artefakts entsprechen (inaktivierte Versionen werden übergangen). Es hat dasselbe Format wie der momentan
generierte Endpunkt. Wenn Sie 'object' angeben, ist die Antwort ein JSON-Objekt, das ein Array von JSON-Objekten enthält, die Versionen des Artefakts darstellen. Sowohl aktivierte als auch inaktivierte Versionen sind im Array enthalten.
Beispiel für curl-Anforderung:
curl -u token:$APIKEY $URL/artifacts/my-schema/versions
oder
curl -u token:$APIKEY $URL/artifacts/my-schema/versions?jsonformat=number
oder
curl -u token:$APIKEY $URL/artifacts/my-schema/versions?jsonformat=object
Beispielantwort, wenn jsonformat number ist oder nicht angegeben wird (standardmäßig wird number verwendet):
[1,3,4,6,7]
Beispielantwort, wenn jsonformat object ist:
{"versions":[{"id":1,"state":"ENABLED"},{"id":2,"state":"DISABLED"},{"id":3,"state":"ENABLED"},{"id":4,"state":"ENABLED"},{"id":5,"state":"DISABLED"},{"id":6,"state":"ENABLED"},{"id":7,"state":"ENABLED"}],"count":7}
Für den Abruf der Liste der verfügbaren Versionen eines Schemas sind mindestens die beiden folgenden Zugriffsrollen erforderlich:
- Rolle eines Leseberechtigten für den Zugriff auf den Ressourcentyp des Event Streams-Clusters
- Zugriff der Reader-Rolle auf die Schemaressource, die dem abgerufenen Schema entspricht.
Version eines Schemas löschen
Schema-Versionen werden aus der Registrierung gelöscht, indem eine DELETE-Anfrage an den Endpunkt /artifacts/{schema-id}/versions/{version} gesendet wird (wobei {schema-id} die ID des Schemas und {version} die Versionsnummer der
Schema-Version ist). Bei erfolgreicher Ausführung wird eine leere Antwort und der Statuscode 204 (kein Inhalt) zurückgegeben. Wenn die einzige verbleibende Version eines Schemas gelöscht wird, wird auch das Schema gelöscht.
Beispiel für curl-Anforderung:
curl -u token:$APIKEY -X DELETE $URL/artifacts/my-schema/versions/3
Für das Löschen einer Schemaversion sind mindestens die beiden folgenden Zugriffsrollen erforderlich:
- Rolle eines Leseberechtigten für den Zugriff auf den Ressourcentyp des Event Streams-Clusters
- Zugriff auf die Schema-Ressource, die dem gelöschten Schema entspricht, für Manager-Rollen.
Es wird ein Activity Tracker-Ereignis generiert, um die Aktion zu melden. Weitere Informationen finden Sie unter Activity Tracker-Ereignisse.
Bestimmte globale eindeutige ID einer Schemaversion abrufen
Um eine bestimmte globale eindeutige ID einer Schemaversion abzurufen, senden Sie eine GET-Anfrage an den Endpunkt /artifacts/{artifactId}/versions/{version}/meta (wobei {artifactId} die ID des Artefakts und {version} die Versionsnummer
der spezifischen Version ist, die Sie abrufen möchten). Bei erfolgreicher Ausführung wird die spezifische globale eindeutige ID einer Schemaversion in den Nutzdaten der Antwort zurückgegeben.
Beispiel für curl-Anforderung:
curl -u token:$APIKEY $URL/artifacts/9030f450-45fb-4750-bb37-771ad49ee0e8/versions/1/meta
Beispielantwort:
{"id":"9030f450-45fb-4750-bb37-771ad49ee0e8","type":"AVRO","version":1,"createdOn":1682340169202,"modifiedOn":1682340169202,"globalId":1}
Zum Abrufen der globalen eindeutigen ID einer Schemaversion sind mindestens die folgenden Zugriffstypen erforderlich:
- Rolle eines Leseberechtigten für den Zugriff auf den Ressourcentyp des Event Streams-Clusters
- Zugriff der Reader-Rolle auf die Schemaressource, die dem abgerufenen Schema entspricht.
Globale Regel aktualisieren
Globale Kompatibilitätsregeln können aktualisiert werden, indem eine PUT-Anfrage an den Endpunkt /rules/ {rule-type} gesendet wird (wobei {rule-type} den Typ der zu aktualisierenden globalen Regel angibt – derzeit wird nur der Typ COMPATIBILITY unterstützt), wobei die neue Regelkonfiguration im Textkörper der Anfrage enthalten ist. Wenn die Anforderung erfolgreich ist, wird die neu aktualisierte Regelkonfiguration ('config') in den Nutzdaten der Antwort zusammen mit dem Statuscode 200 (OK) zurückgegeben.
Das im Textkörper der Anfrage gesendete JSON-Dokument muss folgende Eigenschaften aufweisen:
| Eigenschaftsname | Beschreibung |
|---|---|
| Typ | Muss immer auf den Wert COMPATIBILITY gesetzt werden. |
| Konfiguration | Muss auf einen der folgenden Werte gesetzt werden: NONE, BACKWARD, BACKWARD_TRANSITIVE, FORWARD, FORWARD_TRANSITIVE, FULL oder FULL_TRANSITIVE. (Der Abschnitt zu Kompatibilitätsregeln enthält Details zu jedem dieser Werte.) |
Beispiel für curl-Anforderung:
curl -u token:$APIKEY -X PUT $URL/rules/COMPATIBILITY -d '{"type":"COMPATIBILITY","config":"BACKWARD"}'
Beispielantwort:
{"type":"COMPATIBILITY","config":"BACKWARD"}
Für das Aktualisieren einer globalen Regelkonfiguration ist mindestens die folgende Zugriffsrolle erforderlich:
- Rolle eines Managers für den Zugriff auf den Ressourcentyp des Event Streams-Clusters
Es wird ein Activity Tracker-Ereignis generiert, um die Aktion zu melden. Weitere Informationen finden Sie unter Activity Tracker-Ereignisse.
Aktuellen Wert einer globalen Regel abrufen
Der aktuelle Wert einer globalen Regel wird durch eine GET-Anfrage an den Endpunkt /rules/ {rule-type} abgerufen (wobei {rule-type} der Typ der abzurufenden globalen Regel ist – derzeit wird nur der Typ COMPATIBILITY unterstützt). Wenn die Anforderung erfolgreich ist, wird die aktuelle Regelkonfiguration in den Nutzdaten der Antwort zusammen mit dem Statuscode 200 (OK) zurückgegeben.
Beispiel für curl-Anforderung:
curl -u token:$APIKEY $URL/rules/COMPATIBILITY
Beispielantwort:
{"type":"COMPATIBILITY","config":"BACKWARD"}
Für den Abruf der globalen Regelkonfiguration ist mindestens die folgende Zugriffsrolle erforderlich:
- Rolle eines Leseberechtigten für den Zugriff auf den Ressourcentyp des Event Streams-Clusters
Regel für bestimmtes Schema erstellen
Regeln können auf ein bestimmtes Schema angewendet werden und dabei alle festgelegten globalen Regeln überschreiben, indem eine POST-Anfrage an den Endpunkt /artifacts/{schema-id}/rules gesendet wird (wobei {schema-id} die ID
des Schemas ist), wobei der Typ und der Wert der neuen Regel im Textkörper der Anfrage enthalten sind (derzeit wird nur der Typ COMPATIBILITY unterstützt). Bei erfolgreicher Ausführung wird eine leere Antwort und der Statuscode 204 (kein
Inhalt) zurückgegeben.
Beispiel für curl-Anforderung:
curl -u token:$APIKEY $URL/artifacts/my-schema/rules -d '{"type":"COMPATIBILITY","config":"FORWARD"}'
Für das Erstellen von Regeln für bestimmte Schemas sind mindestens die folgenden Zugriffsrollen erforderlich:
- Rolle eines Leseberechtigten für den Zugriff auf den Ressourcentyp des Event Streams-Clusters
- Zugriff auf die Schema-Ressource, für die die Regel gilt, für die Rolle "Manager".
Es wird ein Activity Tracker-Ereignis generiert, um die Aktion zu melden. Weitere Informationen finden Sie unter Activity Tracker-Ereignisse.
Regel für bestimmtes Schema abrufen
Um den aktuellen Wert eines Regeltyps abzurufen, der auf ein bestimmtes Schema angewendet wird, wird eine GET-Anfrage an den Endpunkt /artifacts/{schema-id}/rules/{rule-type} gesendet (wobei {schema-id} die ID des Schemas und
{rule-type} der Typ der abzurufenden globalen Regel ist – derzeit wird nur der Typ COMPATIBILITY unterstützt). Wenn die Anforderung erfolgreich ist, wird der aktuelle Regelwert in den Nutzdaten der Antwort zusammen mit dem Statuscode 200
(OK) zurückgegeben.
Beispiel für curl-Anforderung:
curl -u token:$APIKEY $URL/artifacts/my-schema/rules/COMPATIBILITY
Beispielantwort:
{"type":"COMPATIBILITY","config":"FORWARD"}
Für den Abruf von Regeln für bestimmte Schemas sind mindestens die folgenden Zugriffsrollen erforderlich:
- Rolle eines Leseberechtigten für den Zugriff auf den Ressourcentyp des Event Streams-Clusters
- Rolle eines Leseberechtigten für den Zugriff auf die Schemaressource, auf die die Regel angewendet wird.
Regel für bestimmtes Schema aktualisieren
Die für ein bestimmtes Schema geltenden Regeln werden durch eine PUT-Anfrage an den Endpunkt /artifacts/{schema-id}/rules/{rule-type} geändert (wobei {schema-id} die ID des Schemas und {rule-type} der Typ der abzurufenden globalen
Regel ist – derzeit wird nur der Typ COMPATIBILITY unterstützt). Wenn die Anforderung erfolgreich ist, wird die neu aktualisierte Regelkonfiguration ('config') in den Nutzdaten der Antwort zusammen mit dem Statuscode 200 (OK) zurückgegeben.
Beispiel für curl-Anforderung:
curl -u token:$APIKEY -X PUT $URL/artifacts/my-schema/rules/COMPATIBILITY -d '{"type":"COMPATIBILITY","config":"BACKWARD"}'
Beispielantwort:
{"type":"COMPATIBILITY","config":"BACKWARD"}
Für das Aktualisieren einer Regel für ein bestimmtes Schema sind mindestens die folgenden Zugriffsrollen erforderlich:
- Rolle eines Leseberechtigten für den Zugriff auf den Ressourcentyp des Event Streams-Clusters
- Rolle eines Managers für den Zugriff auf die Schemaressource, auf die die Regel angewendet wird.
Es wird ein Activity Tracker-Ereignis generiert, um die Aktion zu melden. Weitere Informationen finden Sie unter Activity Tracker-Ereignisse.
Regel für bestimmtes Schema löschen
Die für ein bestimmtes Schema geltenden Regeln werden gelöscht, indem eine DELETE-Anfrage an den Endpunkt /artifacts/{schema-id}/rules/{rule-type} gesendet wird (wobei {schema-id} die ID des Schemas und {rule-type} der Typ der
abzurufenden globalen Regel ist – derzeit wird nur der Typ COMPATIBILITY unterstützt). Wenn die Anforderung erfolgreich ist, wird eine leere Antwort mit dem Statuscode 204 (kein Inhalt) zurückgegeben.
Beispiel für curl-Anforderung:
curl -u token:$APIKEY -X DELETE $URL/artifacts/my-schema/rules/COMPATIBILITY
Für das Löschen einer Regel für ein bestimmtes Schema sind mindestens die folgenden Zugriffsrollen erforderlich:
- Rolle eines Leseberechtigten für den Zugriff auf den Ressourcentyp des Event Streams-Clusters
- Rolle eines Managers für den Zugriff auf die Schemaressource, auf die die Regel angewendet wird.
Es wird ein Activity Tracker-Ereignis generiert, um die Aktion zu melden. Weitere Informationen finden Sie unter Activity Tracker-Ereignisse.
Kompatibilitätsregeln auf neue Versionen von Schemas anwenden
Das Schema-Register unterstützt die Durchsetzung von Kompatibilitätsregeln, wenn Sie eine neue Version eines Schemas erstellen. Wenn eine Anforderung zum Erstellen einer neuen Schemaversion ausgeführt wird, die nicht der erforderlichen Kompatibilitätsregel entspricht, weist die Registry die Anforderung zurück. Die folgenden Regeln werden unterstützt:
| Kompatibilitätsregel | Testet | Beschreibung |
|---|---|---|
| Keine | Nicht zutreffend | Es wird keine Kompatibilitätsprüfung durchgeführt, wenn eine neue Schemaversion erstellt wird. |
| BACKWARD | Letzte Version des Schemas | Eine neue Version des Schemas kann Felder weglassen, die in der vorhandenen Version des Schemas enthalten sind. |
| BACKWARD_TRANSITIVE | Alle Versionen des Schemas | Eine neue Version des Schemas kann optionale Felder hinzufügen, die in der vorhandenen Version des Schemas nicht enthalten sind. |
| FORWARD | Letzte Version des Schemas | Eine neue Version des Schemas kann Felder hinzufügen, die in der vorhandenen Version des Schemas nicht enthalten sind. |
| FORWARD_TRANSITIVE | Alle Versionen des Schemas | Eine neue Version des Schemas kann optionale Felder weglassen, die in der vorhandenen Version des Schemas enthalten sind. |
| FULL | Letzte Version des Schemas | Eine neue Version des Schemas kann optionale Felder hinzufügen, die in der vorhandenen Version des Schemas nicht enthalten sind. |
| FULL_TRANSITIVE | Alle Versionen des Schemas | Eine neue Version des Schemas kann optionale Felder weglassen, die in der vorhandenen Version des Schemas enthalten sind. |
Diese Regeln können auf zwei Geltungsbereiche angewendet werden:
- Auf den globalen Geltungsbereich. Dies ist der verwendete Standardbereich, wenn eine neue Schemaversion erstellt wird.
- Auf den Bereich der Schemaebene. Wenn eine Regel auf Schemaebene definiert wird, überschreibt sie die globale Standardregel für das betreffende Schema.
Standardmäßig hat die Registry die Einstellung NONE für die globale Kompatibilitätsregel. Es müssen Regeln auf Schemaebene definiert werden, andernfalls verwendet das Schema standardmäßig die globale Einstellung.
Vollständige Beschreibung der API
Eine Beschreibung der REST-API mit Beispielen finden Sie unter Event Streams schema-registry-rest.
Die vollständigen Spezifikationen für die API können Sie aus der Schema-Registry-REST-API-YAML-Datei von Event Streams herunterladen. Um die Swagger-Datei anzuzeigen, verwenden Sie Swagger-Tools, z. B. den Swagger-Editor.
Weitere Informationen zum Zugriff auf die Schemaregistry über ein SDK finden Sie unter Event Streams Schema Registry REST-API.
Informationen zu Event Streams-Ressourcen und -Datenquellen in Terraform finden Sie unter Ressourcen und Datenquellen.
Verwendung des Schema-Registers mit dem Drittanbieter SerDes
Schema Registry unterstützt die Verwendung der folgenden Drittanbieter- SerDes:
- Confluent SerDes
Zur Konfiguration von Confluent SerDes für die Verwendung der Schemaregistry müssen Sie zwei Eigenschaften in der Konfiguration Ihres Kafka-Clients angeben:
| Eigenschaftsname | Wert |
|---|---|
| SCHEMA_REGISTRY_URL_CONFIG | Setzen Sie diese Eigenschaft auf die URL der Schemaregistry und geben Sie Ihre Berechtigungsnachweise zur Basisauthentifizierung sowie den Pfad /confluent an. Wenn beispielsweise $APIKEY der zu verwendende API-Schlüssel
ist und $HOST der Host aus dem Feld kafka_http_url auf der Registerkarte "Service Credentials" ist, hat der Wert die Form: https://token:{$APIKEY}@{$HOST}/{confluent} |
| BASIC_AUTH_CREDENTIALS_SOURCE | Wird auf URL festgelegt. Dies weist den SerDes an, die HTTP-Basisauthentifizierung mit den Berechtigungsnachweisen zu verwenden, die in der URL für die Schemaregistry angegeben werden. |
Sie können optional auch die folgenden Eigenschaften angeben, um die Schemaauswahl zu steuern (Subjektbenennungsstrategie):
| Eigenschaftsname | Wert |
|---|---|
| WERT_SUBJEKT_NAME_STRATEGIE | TopicNameStrategy(Standardwert), RecordNameStrategyundTopicRecordNameStrategy werden unterstützt. Um beispielsweise anzugeben, dass das Schema für den Nachrichtenwert mithilfe von TopicRecordNameStrategy ausgewählt wird, können Sie die folgenden Client-Eigenschaften verwenden: configs.put ( KafkaAvroSerializerConfig.VALUE_SUBJECT_NAME_STRATEGY, TopicRecordNameStrategy.class.getName( )); |
| SCHLÜSSELSUBJEKTNAME_STRATEGIE | TopicNameStrategy(Standardwert), RecordNameStrategyund TopicRecordNameStrategywerden unterstützt. Ein Beispiel finden Sie unter VALUE_SUBJECT_NAME_STRATEGY. |
Das folgende Diagramm zeigt ein Beispiel für die Eigenschaften, die erforderlich sind, um einen Kafka-Produzenten zu erstellen, der Confluent SerDes verwendet und mit dem Event Streams-Dienst verbunden werden kann:
Wenn eine Nachricht unter Verwendung eines Schemas gesendet wird, das nicht in der Registrierung enthalten ist, versucht SerDes, das neue Schema oder die Version des Schemas in der Registrierung zu erstellen. Wenn dieses Verhalten nicht erforderlich ist, kann es deaktiviert werden, indem die Schreibberechtigung für Schemaressourcen aus der Anwendung entfernt wird. Siehe Zugriff auf Schemaregistry verwalten.
Die Option Normalisieren für Schemasuchvorgänge und die Registrierung wird nicht unterstützt.
Schema-Registry mit Tools verwenden, die die Confluent-Registry-API verwenden
Die Schema-Registry unterstützt eine Untergruppe der API, die von Version 7.2 der Confluent-Schema-Registry bereitgestellt wird. Dies soll eine eingeschränkte Kompatibilität mit Tools ermöglichen, die für die Arbeit mit der Confluent Schema Registry konzipiert wurden. Nur der REST-Endpunkt HTTP mit den folgenden Pfaden ist implementiert:
- Kompatibilität
- konfigurieren
- Schemata
- Subjekte
Um eine Anwendung für die Verwendung dieser Kompatibilitäts-API zu konfigurieren, geben Sie den Schema-Registry-Endpunkt im folgenden Format an:
https://token:{$APIKEY}@{$HOST}/{confluent}
Dabei gilt:
$APIKEYist der API-Schlüssel, der auf der Registerkarte Serviceberechtigungsnachweise verwendet wird.$HOSTist der Host aus dem Feldkafka_http_urlauf der Registerkarte Serviceberechtigungsnachweise.
Verwendung der Schema-Registry mit Drittanbieter-Tools
Das Schema-Register kann mit Drittanbieter-Tools wie kafka-avro-console-producer.sh und kafka-avro-console-consumer.sh getestet werden, die das Testen der Schemakonformität mit Confluent SerDes ermöglichen.
Um entweder das Produzenten- oder das Konsumenten-Tool auszuführen, ist eine gemeinsame Eigenschaft mit den Verbindungsoptionen für die Event Streams Enterprise-Instanz erforderlich.
sasl.jaas.config=org.apache.kafka.common.security.plain.PlainLoginModule required username="token" password="apikey";
security.protocol=SASL_SSL
sasl.mechanism=PLAIN
ssl.protocol=TLSv1.2
ssl.enabled.protocols=TLSv1.2
ssl.endpoint.identification.algorithm=HTTPS
Producer- und Consumer-Tools der Avro-Konsole
Sie können die Producer- und Consumer-Tools der Kafka-Avro-Konsole mit Event Streams verwenden. Sie müssen ein Client-Objekt bereitstellen und zusätzlich müssen die Verbindungsmethode und die Anmeldeinformationen für die Schema-Registrierung
als Befehlszeilenargumente für --property angegeben werden. Es gibt zwei Verbindungsmethoden, indem Sie eine Anmeldeinformationsquelle von USER_INFO oder von URL verwenden.
Verwenden Sie den folgenden Code, um die Anmeldeinformationen über die Quellmethode von URL auszuführen.
./kafka-avro-console-[producer|consumer] --broker-list $BOOTSTRAP_ENDPOINTS --topic schema-test --property schema.registry.url=$SCHEMA_REGISTRY_URL --property value.schema='{"type":"record","name":"myrecord","fields":[{"name":"f1","type":"string"}]}' --property basic.auth.credentials.source=URL --producer.config $CONFIG_FILE
Ersetzen Sie die folgenden Variablen im Beispiel durch Ihre eigenen Werte.
- BOOTSTRAP_ENDPOINTS mit dem Wert aus der Registerkarte Event Streams Serviceberechtigungsnachweise in der IBM Cloud-Konsole als Liste Ihrer Bootstrap-Server.
- SCHEMA_REGISTRY_URL mit dem Wert
kafka_http_urlvon Ihrer Event Streams Serviceberechtigungsnachweise -Registerkarte in der IBM Cloud -Konsole mit dem Benutzernamentokenund dem API-Schlüssel zusammen mit dem Pfad/confluent(z. B.https://{token}:{apikey}@{kafka_http_url}/{confluent}). - Ersetzen Sie CONFIG_FILE durch den Pfad der Konfigurationsdatei.
Verwenden Sie den folgenden Code, um die Anmeldeinformationen über die Quellmethode USER_INFO zu verwenden.
./kafka-avro-console-[producer|consumer] --broker-list $BOOTSTRAP_ENDPOINTS --topic schema-test --property schema.registry.url=$SCHEMA_REGISTRY_URL --property value.schema='{"type":"record","name":"myrecord","fields":[{"name":"f1","type":"string"}]}' --property basic.auth.credentials.source=USER_INFO --property basic.auth.user.info=token:apikey --producer.config $CONFIG_FILE
Ersetzen Sie die folgenden Variablen im Beispiel durch Ihre eigenen Werte.
- BOOTSTRAP_ENDPOINTS mit dem Wert aus der Registerkarte Event Streams Serviceberechtigungsnachweise in der IBM Cloud-Konsole als Liste Ihrer Bootstrap-Server.
- SCHEMA_REGISTRY_URL mit dem Wert
kafka_http_urlvon Ihrer Event Streams Serviceberechtigungsnachweise -Registerkarte in der IBM Cloud -Konsole mit dem Pfad/confluent(z. B.https://{kafka_http_url}/{confluent}). - Ersetzen Sie CONFIG_FILE durch den Pfad der Konfigurationsdatei.