Utilisation du registre de schéma Event Streams

Schema Registry fournit un référentiel centralisé pour la gestion et la validation des schémas. Les schémas d'un registre de schémas fournissent le contrat explicite qu'un programme générant un événement fournit à d'autres programmes qui consomment ces événements.

Présentation des schémas

Apache Kafka peut traiter toutes les données, mais ne valide pas les informations contenues dans les messages. Toutefois, les données doivent souvent inclure des informations spécifiques dans un certain format pour pouvoir être traitées efficacement. Vous pouvez définir la structure des données d'un message à l'aide de schémas et ainsi garantir que les producteurs et les consommateurs utilisent la structure appropriée.

Les schémas permettent aux producteurs de créer des données conformes à une structure prédéfinie en définissant les zones qui doivent être présentes ainsi que le type de chaque zone. Cette définition aide ensuite les consommateurs à analyser les données et à les interpréter correctement. Le plan Enterprise de Event Streams prend en charge les schémas et comprend un registre de schéma pour utiliser et gérer les schémas.

Il est courant que tous les messages d'une rubrique utilisent le même schéma. La clé et la valeur d'un message peuvent être toutes deux décrites par un schéma.

Diagramme de présentation des schémas. — Présentation des schémas

Registre de schémas

Les schémas sont stockés dans le registre de schémas de Event Streams. En plus de contenir un historique versionné des schémas, il fournit une interface permettant de récupérer ces derniers. Chaque instance de plan Event Streams Enterprise possède son propre registre de schémas. Un maximum de 1000 schémas peuvent être stockés dans une instance Enterprise.

Les producteurs et les consommateurs valident les données par rapport au schéma spécifié qui est stocké dans le registre de schémas (en plus de passer par des courtiers d' Kafka ). Il n'est pas nécessaire de transférer les schémas dans les messages de cette manière, ce qui signifie que les messages peuvent être plus petits.

Schéma de l'architecture du registre. — Architecture du registre de schémas

Format de données Apache Avro

Les schémas sont définis à l'aide d' Apache Avro, une technologie de sérialisation de données open source couramment utilisée avec Apache Kafka. Elle fournit un format de codage des données efficace en utilisant le format binaire compact ou un format JSON plus détaillé mais lisible par l'utilisateur.

Le registre de schémas de Event Streams utilise des formats de données Apache Avro. Lorsque des messages sont envoyés au format Avro, ils contiennent les données et l'identificateur unique pour le schéma utilisé. L'identificateur indique quel schéma du registre sera utilisé pour le message.

Avro prend en charge un large éventail de types de données, y compris les types primitifs (null, boolean, int, long, float, double, bytes et string) et les types complexes (record, enum, array, map, union et fixed).

Diagramme de format Avro. — Format de message Avro

Sérialisation et désérialisation

Une application de production utilise un sérialiseur pour produire des messages conformes à un schéma spécifique. Comme indiqué précédemment, le message contient les données au format Avro ainsi que l'identificateur du schéma.

Une application consommatrice utilise ensuite un désérialiseur pour consommer des messages qui ont été sérialisés en utilisant le même schéma. Lorsqu'un consommateur lit un message envoyé au format Avro, le désérialiseur trouve l'identifiant du schéma dans le message et récupère le schéma dans le registre de schémas pour désérialiser les données.

Ce processus permet de garantir de manière efficace que les données contenues dans les messages sont conformes à la structure requise.

Le registre de schémas ( Event Streams ) prend en charge le sérialiseur et le désérialiseur AVRO(Kafka ).

Diagramme de sérialisation et de désérialisation. — Sérialiseur et désérialiseur

Schéma de compatibilité et de versions. — Compatibilité et versions

Versions et compatibilité

Chaque fois que vous ajoutez un schéma, et toutes les versions ultérieures du même schéma, Event Streams peut valider automatiquement le format et rejeter le schéma s'il y a des problèmes. Vous pouvez faire évoluer vos schémas au fil du temps de manière à répondre aux changements d'exigences. Créer une nouvelle version d'un schéma existant, et le registre de schémas s'assure que la nouvelle version est compatible avec la version existante, ce qui signifie que les producteurs et les consommateurs qui utilisent la version existante ne sont pas perturbés par la nouvelle version.

Les schémas sont comparés pour éviter de créer des schémas en double dans lesquels les schémas diffèrent uniquement d'une manière qui n'affecte pas la sémantique du schéma. Dans certains cas, l'ordre des propriétés JSON dans un schéma peut être crucial pour la façon dont le schéma est utilisé pour le codage et le décodage des données, mais dans d'autres cas, il peut ne pas être pertinent.

Par exemple, la propriété name d'un schéma d'enregistrement n'est pas utilisée dans le cadre du processus de codage et de décodage, de sorte que vous pouvez la positionner n'importe où dans l'objet JSON d'enregistrement. Toutes ces variantes sont considérées comme le même schéma.

La propriété fields dans le JSON d'un schéma d'enregistrement est un cas où son ordre est important. La spécification Avro requiert que les champs d'un enregistrement soient codés et décodés dans l'ordre dans lequel ils apparaissent dans le schéma utilisé pour l'opération de codage et de décodage.

Prenons par exemple les trois schémas suivants.

Schéma 1

{
  "type": "record",
  "name": "book",
  "fields": [
    {
      "name": "title",
      "type": "string"
    },
    {
      "name": "author",
      "type": "string"
    }
  ]
}

Schéma 2

{
  "type": "record",
  "name": "book",
  "fields": [
    {
      "name": "author",
      "type": "string"
    },
    {
      "name": "title",
      "type": "string"
    }
  ]
}

Schéma 3

{
  "type": "record",
  "name": "book",
  "fields": [
    {
      "type": "string"
      "name": "author",
    },
    {
      "type": "string"
      "name": "title",
    }
  ]
}

Le schéma 1 et le schéma 2 sont des schémas distincts et le registre les stocke en tant que schémas distincts. Ils ne peuvent pas être utilisés de manière interchangeable car ils répertorient les zones author et title dans un ordre différent. Les données codées avec le schéma 1 ne seraient pas décodées correctement si le processus de décodage utilisait le schéma 2.

Lorsque vous utilisez SerDes pour créer le nouveau schéma dans l'ordre Schéma 1, Schéma 2 et Schéma 3, le résultat est deux nouveaux schémas. Le schéma 1 et le schéma 2 sont différents mais le schéma 3 est l'équivalent du schéma 2.

Lorsque vous créez des schémas à l'aide de l'API REST, les schémas ne sont considérés comme correspondants que s'ils sont textuellement identiques, y compris tous les champs descriptifs et de classement des attributs. Cela permet de prendre en compte le cas où vous souhaitez que le schéma 3 soit un schéma différent.

Activation du registre de schémas

Le registre de schémas est activé par défaut pour les instances de service du plan Event Streams Enterprise. Le registre de schémas n'est pas disponible pour les autres plans Event Streams.

Accès au registre de schémas

Pour accéder au registre de schémas, vous avez besoin de l' URL e du registre de schémas, qui se trouve dans les informations d'identification de votre service. Pour afficher ces informations d'identification dans l'interface utilisateur, cliquez sur votre instance de service, sélectionnez Informations d'identification du service dans le volet de navigation de gauche, puis cliquez sur le lien Afficher les informations d'identification situé à côté de l'une des informations d'identification de service répertoriées dans le tableau :

Diagramme des données d'identification du service. — Kafka

La valeur de kafka_http_url est également l' URL e du registre de schéma.

Authentification

Pour accéder au registre de schéma, vous avez également besoin d'un ensemble de données d'identification qui peuvent être utilisées pour l'authentification auprès du registre. Il existe deux options: l'authentification de base avec une clé d'API ou l'authentification par jeton bearer.

Les exemples de ce document montrent l'utilisation de la clé d'API, mais l'une ou l'autre option peut être utilisée.

Authentification avec la clé d'API

Les données d'identification du service comportent un apikey que vous pouvez utiliser comme données d'identification pour l'authentification avec le registre de schéma.

Vous pouvez également vous authentifier à l'aide d'une clé API qui a été accordée à partir d'un identifiant de service, à condition que l'identifiant de service dispose d'une politique qui lui permette au moins un accès de rôle « lecteur » à l'instance Event Streams. Cette approche est plus flexible et constitue un meilleur choix si vous octroyez l'accès à plusieurs autres personnes ou équipes. Pour plus d'informations, voir la rubrique d'aide Gestion de l'accès à vos ressources Event Streams.

La clé API est fournie en tant que partie mot de passe d'un en-tête d'authentification de base HTTP. La partie nom d'utilisateur de l'en-tête est le mot "token".

La commande curl à utiliser est la suivante, où $APIKEY est remplacé par votre clé d'API:

curl -u token:$APIKEY ...

Authentification avec jeton bearer

Il est également possible d'utiliser un jeton au porteur pour un identifiant système ou un utilisateur en tant qu'identifiant. Il s'agit généralement d'une approche plus sécurisée, car elle a moins de chances d'exposer la clé d'API, et le jeton bearer expire automatiquement après un certain temps.

Pour obtenir un jeton, utilisez la commande IBM Cloud CLI ibmcloud iam oauth-tokens pour générer le jeton. Inclure ce jeton dans un en-tête d' HTTP, au format « Authorization: Bearer $TOKEN », où $TOKEN est le jeton porteur :

curl -H "Authorization: Bearer $TOKEN" ...

Importation de données à partir d'autres registres de schéma

Vous pouvez importer des données dans le registre de schéma qui a été exporté à partir d'autres registres de schéma. Lorsque les données sont importées, l'ID global associé à chaque version d'artefact est conservé. Cela signifie que vous pouvez continuer à utiliser des données qui sont déjà stockées dans Kafka à l'aide des mêmes valeurs d'ID global de schéma.

L'interface de ligne de commande Event Streams prend en charge l'importation de données à l'aide du format d'importation et d'exportation du registre Apicurio, comme dans l'exemple suivant.

ibmcloud es schema-import import.zip

Vous pouvez générer les données à importer à l'aide de l'utilitaire exportConfluent du registre Apicurio, qui exporte les données à partir d'un registre de schéma Confluent. Event Streams a été testé avec la version 2.6.x de cet utilitaire.

Si le registre de schéma Event Streams possède déjà une entrée avec le même ID global qu'une version d'artefact en cours d'importation, l'opération d'importation échoue et vous êtes invité à supprimer la version d'artefact si vous souhaitez continuer.

Noeuds finaux REST du registre de schémas

L'API REST offre quatre fonctions principales :

Création, lecture et suppression de schémas.
Création, lecture et suppression de versions individuelles d'un schéma.
Lecture et mise à jour de la règle de compatibilité globale pour le registre.
Création, lecture, mise à jour et suppression de règles de compatibilité qui s'appliquent à des schémas individuels.

Pour les actions qui modifient la version du schéma, telles que la création, la mise à jour ou la suppression d'artefacts, de versions d'artefact et de règles, un événement de suivi d'activité est généré pour signaler l'action. Pour plus d'informations, voir Evénements Activity Tracker.

Erreurs

Si une condition d'erreur est rencontrée, le registre de schéma renvoie un code d'état d' HTTP s de plage ( non-2XX range status code). Le corps de la réponse contient un objet JSON sous la forme suivante :

{
    "error_code":404,
    "message":"No artifact with id 'my-schema' might be found."
}

Les propriétés de l'objet JSON d'erreur sont les suivantes :

Nom de propriété	Description
code_erreur	Code de statut HTTP de la réponse.
Message	Description de la cause du problème.
Incident	Ce champ n'est inclus que si l'erreur résulte d'un problème lié au registre de schémas. Cette valeur peut être utilisée par le service IBM pour corréler une demande d'informations de diagnostic recueillies par le registre.

Définir un état de schéma

Ce noeud final est utilisé pour définir l'état d'un schéma dans le registre sur ENABLED ou DISABLED. L'état d'un schéma peut être défini en envoyant une demande PUT au noeud final /artifacts/{schema-id}/state (où {schema-id} est l'ID du schéma). Si la requête aboutit, une réponse vide et un code de statut 204 (pas de contenu) sont renvoyés.

Exemple de requête curl :

curl -u token:$APIKEY –X PUT $URL/artifacts/my-schema/state -d '{"state": "DISABLED"}'

La définition d'un état de schéma requiert:

Rôle de gestionnaire d'accès à la ressource de schéma qui correspond au schéma modifié.

Définir un état de version de schéma

Ce noeud final est utilisé pour définir l'état d'une version de schéma dans le registre sur ENABLED ou DISABLED. L'état d'une version de schéma peut être défini en envoyant une demande PUT au noeud final /artifacts/{schema-id}/versions/{version}/state (où {schema-id} est l'ID du schéma et {version} est le numéro de version de la version de schéma). Si la requête aboutit, une réponse vide et un code de statut 204 (pas de contenu) sont renvoyés.

Exemple de requête curl :

curl -u token:$APIKEY –X PUT $URL/artifacts/my-schema/versions/1/state -d '{"state": "DISABLED"}'

La définition d'un état de version de schéma requiert:

Rôle de gestionnaire d'accès à la ressource de schéma qui correspond au schéma en cours de modification.

Création d'un schéma

Ce noeud final est utilisé pour stocker un schéma dans le registre. Les données de schéma sont envoyées en tant que corps de la demande POST. Un identifiant pour le schéma peut être inclus en utilisant l'en-tête de requête ‘X-Registry-ArtifactId'. Si cet en-tête n'est pas présent dans la requête, un identifiant est généré. La valeur "application/json" doit être attribuée à l'en-tête de type de contenu.

Exemple de requête curl :

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

Exemple de réponse :

{"id":"my-schema","type":"AVRO","version":1,"createdBy":"","createdOn":1579267788258,"modifiedBy":"","modifiedOn":1579267788258,"globalId":75}

La création d'un schéma nécessite au moins les deux éléments suivants :

Un accès en tant que Lecteur au type de ressource de cluster Event Streams.
Rôle de l'auteur d'accéder à la ressource de schéma qui correspond au schéma créé.

Un événement de suivi d'activité est généré pour signaler l'action. Pour plus d'informations, voir Evénements Activity Tracker.

Répertoriage des schémas

Vous pouvez générer une liste des identifiants de tous les schémas stockés dans le registre en effectuant une requête GET vers le point de terminaison /artifacts. Vous pouvez formater la réponse à l'aide du paramètre jsonformat (seuls les formats string et object sont pris en charge). Le format de chaîne est le format par défaut et il renvoie un tableau d'ID d'artefact (chaînes). Seuls les artefacts activés sont inclus dans le tableau lorsque cette option est définie. Le format d'objet renvoie un objet JSON qui contient un tableau dans lequel chaque entrée du tableau correspond à un artefact du registre. Les artefacts activés et désactivés sont renvoyés lorsque cette option est définie.

Exemple de requête curl :

curl -u token:$APIKEY $URL/artifacts

curl -u token:$APIKEY $URL/artifacts?jsonformat=string

curl -u token:$APIKEY $URL/artifacts?jsonformat=object

Exemple de réponse lorsque jsonformat est une chaîne ou qu'il n'est pas fourni (par défaut, il s'agit d'une chaîne):

["my-schema-2","my-schema-4"]

Exemple de réponse lorsque jsonformat est un objet:

{"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}

Le répertoriage des schémas nécessite au moins :

Un accès en tant que Lecteur au type de ressource de cluster Event Streams.

Etat et suppression des schémas

La suppression de schéma est un processus en deux étapes. La première étape de la suppression conserve le schéma dans le registre, mais le masque pour certaines opérations. La deuxième étape supprime définitivement le schéma, mais ne peut être appliquée qu'après la première étape. Le processus de suppression en deux étapes s'applique au niveau de l'artefact et au niveau de la version.

Les deux étapes de suppression sont effectuées en ayant un statut activé ou désactivé associé aux artefacts et aux versions (première étape) et en supprimant les API pour les ressources et les versions (deuxième étape).

Un artefact ou une version qui a été désactivée peut être découvert à l'aide d'une propriété'state'qui est renvoyée par des opérations qui répertorient des artefacts ou des versions, ou en obtenant les détails d'un artefact ou d'une version. Les schémas désactivés sont pris en compte dans le quota de schéma de 1000 schémas par instance d'entreprise.

Suppression d'un schéma

Les schémas sont supprimés du registre en envoyant une requête DELETE au point de terminaison /artifacts/{schema-id} (où {schema-id} est l'ID du schéma). En cas de réussite, une réponse vide et un code de statut 204 (aucun contenu) sont renvoyés.

Exemple de requête curl :

curl -u token:$APIKEY -X DELETE $URL/artifacts/my-schema

La suppression d'un schéma nécessite au moins les deux éléments suivants :

Un accès en tant que Lecteur au type de ressource de cluster Event Streams.
Rôle de gestionnaire d'accès à la ressource de schéma qui correspond au schéma supprimé.

Un événement de suivi d'activité est généré pour signaler l'action. Pour plus d'informations, voir Evénements Activity Tracker.

Création d'une version d'un schéma

Pour créer une nouvelle version d'un schéma, effectuez une requête POST vers le point de terminaison /artifacts/{schema-id}/versions, (où {schema-id} est l'ID du schéma). Le corps de la demande doit contenir la nouvelle version du schéma.

Si la requête aboutit, le nouveau schéma est créé en tant que dernière version du schéma, avec un numéro de version approprié, et une réponse avec le code d'état 200 (OK) et une charge utile contenant des métadonnées décrivant la nouvelle version (y compris le numéro de version) est renvoyée.

Exemple de requête curl :

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

Exemple de réponse :

{"id":"my-schema","type":"AVRO","version":2,"createdBy":"","createdOn": 1579267978382,"modifiedBy":"","modifiedOn":1579267978382,"globalId":83}

Pour créer une version d'un schéma, vous devez au moins disposer des deux éléments suivants :

Un accès en tant que Lecteur au type de ressource de cluster Event Streams.
Rôle de l'auteur de l'accès à la ressource de schéma qui correspond au schéma qui obtient une nouvelle version.

Un événement de suivi d'activité est généré pour signaler l'action. Pour plus d'informations, voir Evénements Activity Tracker.

Obtention de la version la plus récente d'un schéma

Pour récupérer la dernière version d'un schéma particulier, faites une requête GET vers le point de terminaison /artifacts/{schema-id} (où {schema-id} est l'ID du schéma). En cas de réussite, la version la plus récente du schéma est renvoyée dans le contenu de la réponse.

Exemple de requête curl :

curl -u token:$APIKEY $URL/artifacts/my-schema

Exemple de réponse :

{"type":"record","name":"Citizen","fields":[{"name": "firstName","type":"string"},{"name":"lastName","type":"string"},{"name":"age","type":"int"},{"name":"phoneNumber","type":"string"}]}

Pour récupérer la version la plus récente d'un schéma, vous devez au moins disposer des deux éléments suivants :

Un accès en tant que Lecteur au type de ressource de cluster Event Streams.
Accès en lecture à la ressource de schéma qui correspond au schéma récupéré.

Obtention d'une version spécifique d'un schéma

Pour récupérer une version spécifique d'un schéma, effectuez une requête GET vers le point de terminaison /artifacts/{schema-id}/versions/{version} (où {schema-id} est l'ID du schéma et {version} est le numéro de version de la version spécifique que vous devez récupérer). En cas de réussite, la version spécifiée du schéma est renvoyée dans le contenu de la réponse.

Exemple de demande curl :

curl -u token:$APIKEY $URL/artifacts/my-schema/versions/3

Exemple de réponse :

{"type":"record","name":"Citizen","fields":[{"name": "firstName","type":"string"},{"name":"lastName","type":"string"},{"name":"age","type":"int"},{"name":"phoneNumber","type":"string"}]}

Pour récupérer la version la plus récente d'un schéma, vous devez au moins disposer des deux éléments suivants :

Un accès en tant que Lecteur au type de ressource de cluster Event Streams.
Accès en lecture à la ressource de schéma qui correspond au schéma récupéré.

Répertoriage de toutes les versions d'un schéma

Pour lister toutes les versions d'un schéma actuellement stockées dans le registre, effectuez une requête GET vers le point de terminaison /artifacts/{schema-id}/versions (où {schema-id} est l'ID du schéma). En cas de réussite, une liste de tous les numéros de version actuels du schéma est renvoyée dans le contenu de la réponse. Vous pouvez formater la réponse à l'aide du paramètre jsonformat (seuls les formats number et object sont pris en charge). Si vous spécifiez'number'(valeur par défaut), la réponse est un tableau de valeurs numériques qui correspondent aux versions activées de l'artefact (les versions désactivées sont omises). Il s'agit du même format que celui actuellement généré par le noeud final. Si vous spécifiez'object', la réponse est un objet JSON qui contient un tableau d'objets JSON représentant les versions de l'artefact. Les versions activées et désactivées sont incluses dans le tableau.

Exemple de requête curl :

curl -u token:$APIKEY $URL/artifacts/my-schema/versions

curl -u token:$APIKEY $URL/artifacts/my-schema/versions?jsonformat=number

curl -u token:$APIKEY $URL/artifacts/my-schema/versions?jsonformat=object

Exemple de réponse lorsque jsonformat est un nombre ou qu'il n'est pas fourni (par défaut, il s'agit d'un nombre):

[1,3,4,6,7]

Exemple de réponse lorsque jsonformat est un objet:

{"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}

Pour obtenir la liste des versions disponibles d'un schéma, vous devez au moins disposer des deux éléments suivants :

Un accès en tant que Lecteur au type de ressource de cluster Event Streams.
Accès en lecture à la ressource de schéma qui correspond au schéma récupéré.

Suppression d'une version d'un schéma

Les versions de schéma sont supprimées du registre en émettant une requête DELETE vers le point de terminaison /artifacts/{schema-id}/versions/{version} (où {schema-id} est l'ID du schéma et {version} est le numéro de version de la version du schéma). En cas de réussite, une réponse vide et un code de statut 204 (aucun contenu) sont renvoyés. La suppression de la seule version restante d'un schéma entraîne également la suppression du schéma.

Exemple de requête curl :

curl -u token:$APIKEY -X DELETE $URL/artifacts/my-schema/versions/3

Pour supprimer une version de schéma, vous devez au moins disposer des deux éléments suivants :

Un accès en tant que Lecteur au type de ressource de cluster Event Streams.
Rôle de gestionnaire d'accès à la ressource de schéma qui correspond au schéma supprimé.

Un événement de suivi d'activité est généré pour signaler l'action. Pour plus d'informations, voir Evénements Activity Tracker.

Obtention de l'ID unique global spécifique d'une version de schéma

Pour récupérer un identifiant global unique spécifique d'une version de schéma, effectuez une requête GET vers le point de terminaison /artifacts/{artifactId}/versions/{version}/meta (où {artifactId} est l'identifiant de l'artefact et {version} est le numéro de version de la version spécifique que vous devez récupérer). Si l'opération aboutit, l'ID unique global spécifique d'une version de schéma est renvoyé dans le contenu de la réponse.

Exemple de requête curl :

curl -u token:$APIKEY $URL/artifacts/9030f450-45fb-4750-bb37-771ad49ee0e8/versions/1/meta

Exemple de réponse :

{"id":"9030f450-45fb-4750-bb37-771ad49ee0e8","type":"AVRO","version":1,"createdOn":1682340169202,"modifiedOn":1682340169202,"globalId":1}

L'obtention de l'ID unique global d'une version de schéma requiert au moins les deux types d'accès suivants:

Un accès en tant que Lecteur au type de ressource de cluster Event Streams.
Accès en lecture à la ressource de schéma qui correspond au schéma récupéré.

Mise à jour d'une règle globale

Les règles de compatibilité globales peuvent être mises à jour en envoyant une requête PUT au point de terminaison /rules/ {rule-type} (où {rule-type} identifie le type de règle globale à mettre à jour - actuellement, le seul type pris en charge est COMPATIBILITY), avec la nouvelle configuration de règle dans le corps de la requête. Si la demande aboutit, la configuration de la règle nouvellement mise à jour est renvoyée dans le contenu de la réponse avec le code de statut 200 (OK).

Le document JSON envoyé dans le corps de la requête doit avoir les propriétés suivantes :

Nom de propriété	Description
Type	Doit toujours être définie sur la valeur COMPATIBILITY.
Config	Doit être définie sur l'une des valeurs suivantes : NONE, BACKWARD, BACKWARD_TRANSITIVE, FORWARD, FORWARD_TRANSITIVE, FULL ou FULL_TRANSITIVE (voir la section relative aux règles de compatibilité pour plus de détails sur chacune de ces valeurs).

Exemple de requête curl :

curl -u token:$APIKEY -X PUT $URL/rules/COMPATIBILITY -d '{"type":"COMPATIBILITY","config":"BACKWARD"}'

Exemple de réponse :

{"type":"COMPATIBILITY","config":"BACKWARD"}

La mise à jour d'une configuration de règle globale nécessite au minimum :

Un accès en tant que Responsable au type de ressource de cluster Event Streams.

Un événement de suivi d'activité est généré pour signaler l'action. Pour plus d'informations, voir Evénements Activity Tracker.

Obtention de la valeur actuelle d'une règle globale

La valeur actuelle d'une règle globale est récupérée en émettant une requête GET vers le point de terminaison /rules/ {rule-type} (où {rule-type} est le type de règle globale à récupérer - actuellement le seul type supporté est COMPATIBILITY). Si la demande aboutit, la configuration de règle actuelle est renvoyée dans le contenu de la réponse avec le code de statut 200 (OK).

Exemple de requête curl :

curl -u token:$APIKEY $URL/rules/COMPATIBILITY

Exemple de réponse :

{"type":"COMPATIBILITY","config":"BACKWARD"}

Pour obtenir une configuration de règle globale, vous devez au moins disposer de ce qui suit :

Un accès en tant que Lecteur au type de ressource de cluster Event Streams.

Création d'une règle par schéma

Les règles peuvent être appliquées à un schéma spécifique, en annulant toute règle globale qui a été définie, en effectuant une requête POST vers le point de terminaison /artifacts/{schema-id}/rules (où {schema-id} est l'ID du schéma), avec le type et la valeur de la nouvelle règle qui est contenue dans le corps de la requête (actuellement, le seul type pris en charge est COMPATIBILITY). En cas de réussite, une réponse vide et un code de statut 204 (aucun contenu) sont renvoyés.

Exemple de requête curl :

curl -u token:$APIKEY $URL/artifacts/my-schema/rules -d '{"type":"COMPATIBILITY","config":"FORWARD"}'

Pour créer des règles par schéma, vous devez au moins disposer de ce qui suit :

Un accès en tant que Lecteur au type de ressource de cluster Event Streams.
Rôle de gestionnaire d'accès à la ressource de schéma à laquelle la règle s'applique.

Un événement de suivi d'activité est généré pour signaler l'action. Pour plus d'informations, voir Evénements Activity Tracker.

Obtention d'une règle pour un schéma spécifique

Pour récupérer la valeur actuelle d'un type de règle appliqué à un schéma spécifique, une requête GET est envoyée au point de terminaison /artifacts/{schema-id}/rules/{rule-type} (où {schema-id} est l'ID du schéma et {rule-type} est le type de règle globale à récupérer - actuellement, le seul type pris en charge est COMPATIBILITY). Si la demande aboutit, la valeur actuelle de la règle est renvoyée dans le contenu de la réponse avec le code de statut 200 (OK).

Exemple de requête curl :

curl -u token:$APIKEY $URL/artifacts/my-schema/rules/COMPATIBILITY

Exemple de réponse :

{"type":"COMPATIBILITY","config":"FORWARD"}

Pour obtenir des règles pour un schéma spécifique, vous devez au moins disposer de ce qui suit :

Un accès en tant que Lecteur au type de ressource de cluster Event Streams.
Accès en tant que Lecteur à la ressource de schéma à laquelle s'applique la règle.

Mise à jour d'une règle pour un schéma spécifique

Les règles appliquées à un schéma spécifique sont modifiées en effectuant une requête PUT vers le point de terminaison /artifacts/{schema-id}/rules/{rule-type} (où {schema-id} est l'ID du schéma et {rule-type} est le type de règle globale à récupérer - actuellement, le seul type pris en charge est COMPATIBILITY). Si la demande aboutit, la configuration de la règle nouvellement mise à jour est renvoyée dans le contenu de la réponse avec le code de statut 200 (OK).

Exemple de requête curl :

curl -u token:$APIKEY -X PUT $URL/artifacts/my-schema/rules/COMPATIBILITY -d '{"type":"COMPATIBILITY","config":"BACKWARD"}'

Exemple de réponse :

{"type":"COMPATIBILITY","config":"BACKWARD"}

Pour mettre à jour une règle d'un schéma spécifique, vous devez au moins disposer de ce qui suit :

Un accès en tant que Lecteur au type de ressource de cluster Event Streams.
Accès en tant que Responsable à la ressource de schéma à laquelle la règle s'applique.

Un événement de suivi d'activité est généré pour signaler l'action. Pour plus d'informations, voir Evénements Activity Tracker.

Suppression d'une règle pour un schéma spécifique

Les règles appliquées à un schéma spécifique sont supprimées en effectuant une requête DELETE vers le point de terminaison /artifacts/{schema-id}/rules/{rule-type} (où {schema-id} est l'ID du schéma et {rule-type} est le type de règle globale à récupérer - actuellement, le seul type pris en charge est COMPATIBILITY). Si la demande aboutit, une réponse vide accompagnée du code de statut 204 (aucun contenu) est renvoyée.

Exemple de requête curl :

curl -u token:$APIKEY -X DELETE $URL/artifacts/my-schema/rules/COMPATIBILITY

Pour supprimer une règle d'un schéma spécifique, vous devez au moins disposer de ce qui suit :

Un accès en tant que Lecteur au type de ressource de cluster Event Streams.
Accès en tant que Responsable à la ressource de schéma à laquelle la règle s'applique.

Un événement de suivi d'activité est généré pour signaler l'action. Pour plus d'informations, voir Evénements Activity Tracker.

Application de règles de compatibilité à de nouvelles versions de schémas

Le registre de schémas permet de faire respecter les règles de compatibilité lorsque vous créez une nouvelle version d'un schéma. Si une demande est émise pour créer une version de schéma qui n'est pas conforme à la règle de compatibilité requise, le registre rejette la demande. Les règles suivantes sont prises en charge :

Règle de compatibilité	Testée par rapport à	Description
NONE	N/A	Aucune vérification de compatibilité n'est effectuée lorsqu'une version de schéma est créée.
BACKWARD	Version la plus récente du schéma	Une nouvelle version du schéma peut omettre des zones présentes dans la version existante du schéma.
BACKWARD_TRANSITIVE	Toutes les versions du schéma	Une nouvelle version du schéma peut ajouter des zones facultatives qui ne sont pas présentes dans la version existante du schéma.
FORWARD	Version la plus récente du schéma	Une nouvelle version du schéma peut ajouter des zones qui ne sont pas présentes dans la version existante du schéma.
FORWARD_TRANSITIVE	Toutes les versions du schéma	Une nouvelle version du schéma peut omettre des zones facultatives présentes dans la version existante du schéma.
FULL	Version la plus récente du schéma	Une nouvelle version du schéma peut ajouter des zones facultatives qui ne sont pas présentes dans la version existante du schéma.
FULL_TRANSITIVE	Toutes les versions du schéma	Une nouvelle version du schéma peut omettre des zones facultatives présentes dans la version existante du schéma.

Ces règles peuvent être appliquées à deux échelles :

A l'échelle globale, qui représente la valeur par défaut utilisée lors de la création d'une nouvelle version de schéma.
A l'échelle de chaque schéma. Si une règle appliquée par schéma est définie, elle remplace la valeur par défaut correspondant à une application à l'échelle globale pour le schéma concerné.

Par défaut, le registre dispose d'un paramètre de règle de compatibilité globale dont la valeur est NONE. Les règles au niveau de chaque schéma doivent être définies, sinon le schéma utilise par défaut le paramètre global.

Description complète de l'API

Pour une description de l'API REST avec des exemples, voir Event Streams schema-registry-rest.

Vous pouvez télécharger la spécification complète de l'API à partir du fichier YAML de l'API REST du registre de schémas d' Event Streams. Pour visualiser le fichier Swagger, utilisez les outils Swagger, par exemple Swagger editor.

Pour plus d'informations sur l'accès au registre de schéma à l'aide d'un logiciel SDK, voir API REST du registre de schémaEvent Streams.

Pour plus d'informations sur les ressources et les sources de données Event Streams sur Terraform, voir Ressources et sources de données.

Utilisation du registre de schémas avec le logiciel tiers SerDes

Schema Registry prend en charge l'utilisation des SerDes:

SerDes Confluent

Pour configurer le SerDes Confluent de sorte qu'il utilise le registre de schémas, vous devez spécifier deux propriétés dans la configuration de votre client Kafka :

Nom de propriété	Valeur
SCHEMA_REGISTRY_URL_CONFIG	Définissez ce paramètre sur l'URL du registre de schémas, y compris vos données d'identification comme authentification de base, et avec le chemin d'accès `/confluent`. Par exemple, si `$APIKEY` est la clé API à utiliser et que `$HOST` est l'hôte du champ `kafka_http_url` dans l'onglet Service Credentials, la valeur a la forme : `https://token:{$APIKEY}@{$HOST}/{confluent}`
BASIC_AUTH_CREDENTIALS_SOURCE	Définit sur `URL`. Elle invite le SerDes à utiliser l'authentification HTTP de base à l'aide des données d'identification fournies dans l'URL du registre de schémas.

Vous pouvez également définir les propriétés suivantes pour contrôler la sélection de schéma (stratégie de dénomination des sujets) :

Nom de propriété Valeur

VALUE_SUBJECT_NAME_STRATEGY TopicNameStrategy(par défaut), RecordNameStrategy et TopicRecordNameStrategy sont pris en charge. Par exemple, pour spécifier que le schéma de la valeur du message est sélectionné à l'aide d'une stratégie de nom de sujet ( TopicRecordNameStrategy), vous pouvez utiliser les propriétés client suivantes : configs.put ( KafkaAvroSerializerConfig.VALUE_SUBJECT_NAME_STRATEGY, TopicRecordNameStrategy.class.getName( ));

KEY_SUBJECT_NAME_STRATEGY TopicNameStrategy (par défaut), RecordNameStrategy et TopicRecordNameStrategy sont pris en charge. Vous trouverez un exemple sous VALUE_OBJET T_NAME_STRATEGY.

Nom de propriété	Valeur
VALUE_SUBJECT_NAME_STRATEGY	`TopicNameStrategy`(par défaut), `RecordNameStrategy` et `TopicRecordNameStrategy` sont pris en charge. Par exemple, pour spécifier que le schéma de la valeur du message est sélectionné à l'aide d'une stratégie de nom de sujet ( `TopicRecordNameStrategy`), vous pouvez utiliser les propriétés client suivantes : configs.put ( KafkaAvroSerializerConfig.VALUE_SUBJECT_NAME_STRATEGY, TopicRecordNameStrategy.class.getName( ));
KEY_SUBJECT_NAME_STRATEGY	`TopicNameStrategy` (par défaut), `RecordNameStrategy` et `TopicRecordNameStrategy` sont pris en charge. Vous trouverez un exemple sous VALUE_OBJET T_NAME_STRATEGY.

Le diagramme suivant montre un exemple des propriétés requises pour créer un producteur d' Kafka s qui utilise l' SerDes Confluent et peut être connecté au service Event Streams:

Si un message est envoyé en utilisant un schéma qui ne figure pas dans le registre, l' SerDes e tente de créer le nouveau schéma, ou la nouvelle version du schéma, dans le registre. Si ce comportement n'est pas nécessaire, il peut être désactivé en supprimant l'autorisation d'écriture pour les ressources de schéma de l'application. Voir Gestion de l'accès au registre de schémas.

L'option Normaliser pour les recherches de schéma et l'enregistrement n'est pas prise en charge.

Utilisation du registre de schéma avec des outils qui utilisent l'API de registre Confluent

Le registre de schéma prend en charge un sous-ensemble de l'API fournie par la version 7.2 du registre de schéma Confluent. Il est destiné à fournir une compatibilité limitée avec les outils conçus pour fonctionner avec le registre de schéma Confluent. Seul le point de terminaison REST d' HTTP, avec les chemins d'accès suivants, est implémenté :

compatibilité
configuration
schémas
subjects

Pour configurer une application afin qu'elle utilise cette API de compatibilité, spécifiez le noeud final Schema Registry au format suivant:

https://token:{$APIKEY}@{$HOST}/{confluent}

où :

$APIKEY est la clé d'API à utiliser dans l'onglet Données d'identification pour le service
$HOST est l'hôte de la zone kafka_http_url de l'onglet Données d'identification pour le service

Utilisation du registre de schémas avec des outils tiers

Le registre de schémas peut être testé avec des outils tiers, tels que l' kafka-avro-console-producer.sh et l' kafka-avro-console-consumer.sh, qui permettent de tester la conformité au schéma à l'aide de l' SerDes e Confluent.

Pour exécuter l'outil producteur ou consommateur, une propriété commune est requise avec les options de connexion pour l'instance d' Event Streams.

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

Outils producteur et consommateur de la console Avro

Vous pouvez utiliser les outils producteur et consommateur de la console Kafka Avro avec Event Streams. Vous devez fournir une propriété client, et en outre, la méthode de connexion et les informations d'identification pour le registre de schémas doivent être fournies en tant qu'arguments d' --property s de ligne de commande. Il existe deux méthodes de connexion en utilisant une source d'informations d'identification USER_INFO ou URL.

Pour exécuter en utilisant la méthode source des informations d'identification d' URL, utilisez le code suivant.

    ./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

Remplacez les variables suivantes dans l'exemple par vos propres valeurs.

BOOTSTRAP_ENDPOINTS avec la valeur de votre console Event Streams Données d'identification de service dans la console IBM Cloud, en tant que liste de vos serveurs d'amorçage.
SCHEMA_REGISTRY_URL avec la valeur kafka_http_url de votre onglet Données d'identification à Event Streams dans la console IBM Cloud, avec le nom d'utilisateur token et la clé d'API, ainsi que le chemin /confluent (par exemple, https://{token}:{apikey}@{kafka_http_url}/{confluent}).
CONFIG_FILE par le chemin d'accès au fichier de configuration.

Pour exécuter en utilisant la méthode source des informations d'identification de USER_INFO, utilisez le code suivant.

    ./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

Remplacez les variables suivantes dans l'exemple par vos propres valeurs.

BOOTSTRAP_ENDPOINTS avec la valeur de votre console Event Streams Données d'identification de service dans la console IBM Cloud, en tant que liste de vos serveurs d'amorçage.
SCHEMA_REGISTRY_URL avec la valeur kafka_http_url de votre onglet Event Streams données d'identification dans la console IBM Cloud, avec le chemin /confluent (par exemple, https://{kafka_http_url}/{confluent}).
CONFIG_FILE par le chemin d'accès au fichier de configuration.