Esquema 1

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

Esquema 2

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

Esquema 3

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

El esquema 1 y el esquema 2 son esquemas distintos y el registro los almacena como esquemas separados. No se pueden utilizar indistintamente porque listan los campos author y title en un orden diferente. Los datos codificados con el Esquema 1 no se descodificarán correctamente si el proceso de descodificación utiliza el Esquema 2.

Cuando se utiliza SerDes para crear el nuevo esquema en el orden Esquema 1, Esquema 2 y Esquema 3, el resultado sería dos nuevos esquemas. El esquema 1 y el esquema 2 son diferentes, pero el esquema 3 es el equivalente al esquema 2.

Cuando se crean esquemas utilizando la API REST, los esquemas se consideran coincidentes sólo si son textualmente iguales, incluidos todos los campos descriptivos y de ordenación de atributos. Esto es para permitir que el caso en el que desea que el esquema 3 sea un esquema diferente.

Autenticación

Para acceder al registro de esquema, también necesita un conjunto de credenciales que se pueden utilizar para autenticarse con el registro. Hay dos opciones, la autenticación básica con una clave de API o la autenticación de señal portadora.

Los ejemplos de este documento muestran el uso de la clave de API, pero se puede utilizar cualquiera de las opciones.

curl -u token:$APIKEY ...

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

Errores

non-2XX Si se encuentra una condición de error, el Registro de Esquemas devuelve un código de estado HTTP range. El cuerpo de la respuesta contiene un objeto JSON en el siguiente formato:

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

Las propiedades del objeto JSON del error son las siguientes:

Establecer un estado de esquema

Este punto final se utiliza para establecer el estado de un esquema en el registro en ENABLED o DISABLED. El estado de un esquema se puede establecer emitiendo una solicitud PUT al punto final /artifacts/{schema-id}/state (donde {schema-id} es el ID del esquema). Si la solicitud se realiza correctamente, se devuelve una respuesta vacía y un código de estado 204 (sin contenido).

Ejemplo de solicitud de curl:

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

El establecimiento de un estado de esquema requiere:

• Acceso de rol de administrador al recurso de esquema que coincide con el esquema que se modifica.

Establecer un estado de versión de esquema

Este punto final se utiliza para establecer el estado de una versión de esquema en el registro en ENABLED o DISABLED. El estado de una versión de esquema se puede establecer emitiendo una solicitud PUT al punto final /artifacts/{schema-id}/versions/{version}/state (donde {schema-id} es el ID del esquema y {version} es el número de versión de la versión del esquema). Si la solicitud se realiza correctamente, se devuelve una respuesta vacía y un código de estado 204 (sin contenido).

Ejemplo de solicitud de curl:

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

El establecimiento de un estado de versión de esquema requiere:

• Acceso de rol de administrador al recurso de esquema que coincide con el esquema que se está modificando.

Crear un esquema

Este punto final se utiliza para almacenar un esquema en el registro. Los datos de esquema se envían como el cuerpo de la solicitud POST. Se puede incluir un ID para el esquema utilizando el encabezado de solicitud ‘X-Registry-ArtifactId'. Si este encabezado no está presente en la solicitud, se genera un ID. La cabecera del tipo de contenido debe establecerse en "application/json".

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

Respuesta de ejemplo:

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

La creación de un esquema requiere al menos ambos:

• Acceso de rol de lector al tipo de recurso de clúster de Event Streams.
• Acceso de rol de escritor al recurso de esquema que coincide con el esquema creado.

Se genera un suceso de Activity Tracker para informar de la acción. Para obtener más información, consulte Sucesos de Activity Tracker.

Generación de listas de esquemas

Puede generar una lista de los ID de todos los esquemas almacenados en el registro realizando una solicitud GET al punto de conexión /artifacts. Puede formatear la respuesta utilizando el parámetro jsonformat (solo se soportan los formatos string y object ). El formato de serie es el predeterminado y devuelve una matriz de ID de artefacto (series). Sólo los artefactos habilitados se incluyen en la matriz cuando se establecen estas opciones. El formato de objeto devuelve un objeto JSON que contiene una matriz donde cada entrada de la matriz corresponde a un artefacto del registro. Tanto los artefactos habilitados como los inhabilitados se devuelven cuando se establece esta opción.

Ejemplo de solicitud de curl:

curl -u token:$APIKEY $URL/artifacts

o

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

o

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

Respuesta de ejemplo cuando jsonformat es serie, o no se proporciona (toma el valor predeterminado de serie):

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

Respuesta de ejemplo cuando jsonformat es objeto:

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

Generar listas de esquemas requiere al menos:

• Acceso de rol de lector al tipo de recurso de clúster de Event Streams.

Estado y supresión de esquemas

La supresión de esquema es un proceso de dos etapas. La primera etapa de supresión conserva el esquema en el registro, pero lo oculta de algunas operaciones. La segunda etapa elimina permanentemente el esquema, pero sólo se puede aplicar después de la primera etapa. El proceso de supresión de dos etapas se aplica a nivel de artefacto y también a nivel de versión.

Las dos etapas de supresión se realizan teniendo un estado habilitado o inhabilitado asociado a artefactos y versiones (primera etapa) y suprimiendo API para recursos y versiones (segunda etapa).

Un artefacto o versión que se ha inhabilitado se puede descubrir utilizando una propiedad 'state' que devuelven las operaciones que listan artefactos o versiones, u obteniendo los detalles de un artefacto o versión. Los esquemas inhabilitados cuentan para la cuota de esquema de 1000 esquemas por instancia de empresa.

Supresión de un esquema

Los esquemas se eliminan del registro mediante la emisión de una solicitud DELETE al punto final /artifacts/{schema-id} (donde {schema-id} es el ID del esquema). Si se ejecuta correctamente, se devuelve una respuesta vacía y un código de estado 204 (sin contenido).

Ejemplo de solicitud de curl:

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

La supresión de un esquema requiere al menos ambos:

• Acceso de rol de lector al tipo de recurso de clúster de Event Streams.
• Acceso de rol de administrador al recurso de esquema que coincide con el esquema que se elimina.

Se genera un suceso de Activity Tracker para informar de la acción. Para obtener más información, consulte Sucesos de Activity Tracker.

Creación de una nueva versión de un esquema

Para crear una nueva versión de un esquema, realice una solicitud POST al punto final /artifacts/{schema-id}/versions, (donde {schema-id} es el ID del esquema). El cuerpo de la solicitud debe contener la nueva versión del esquema.

Si la solicitud se realiza correctamente, el nuevo esquema se crea como la última versión del esquema, con un número de versión apropiado, y se devuelve una respuesta con el código de estado 200 (OK), y una carga útil que contiene metadatos que describen la nueva versión (incluido el número de versión).

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

Respuesta de ejemplo:

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

La creación de una nueva versión de un esquema requiere al menos ambos:

• Acceso de rol de lector al tipo de recurso de clúster de Event Streams.
• Acceso de rol de escritor al recurso de esquema que coincide con el esquema que obtiene una nueva versión.

Se genera un suceso de Activity Tracker para informar de la acción. Para obtener más información, consulte Sucesos de Activity Tracker.

Obtención de la versión más reciente de un esquema

Para recuperar la última versión de un esquema concreto, realice una solicitud GET al punto final /artifacts/{schema-id} (donde {schema-id} es el ID del esquema). Si se ejecuta correctamente, se devuelve la versión más reciente del esquema en la carga útil de la respuesta.

Ejemplo de solicitud de curl:

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

Respuesta de ejemplo:

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

La obtención de la versión más reciente de un esquema requiere al menos ambos:

• Acceso de rol de lector al tipo de recurso de clúster de Event Streams.
• Acceso de rol de lector al recurso de esquema que coincide con el esquema recuperado.

Obtención de una versión específica de un esquema

Para recuperar una versión específica de un esquema, realice una solicitud GET al punto final /artifacts/{schema-id}/versions/{version} (donde {schema-id} es el ID del esquema y {version} es el número de versión de la versión específica que necesita recuperar). Si se ejecuta correctamente, se devuelve la versión especificada del esquema en la carga útil de la respuesta.

Ejemplo de solicitud curl

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

Respuesta de ejemplo:

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

La obtención de la versión más reciente de un esquema requiere al menos ambos:

• Acceso de rol de lector al tipo de recurso de clúster de Event Streams.
• Acceso de rol de lector al recurso de esquema que coincide con el esquema recuperado.

Listado de todas las versiones de un esquema

Para enumerar todas las versiones de un esquema que están almacenadas actualmente en el registro, haga una solicitud GET al punto final /artifacts/{schema-id}/versions (donde {schema-id} es el ID del esquema). Si se ejecuta correctamente, se devuelve una lista de todos los números de versión actuales para el esquema en la carga útil de la respuesta. Puede dar formato a la respuesta utilizando el parámetro jsonformat (solo se da soporte a los formatos number y object ). Si especifica 'número' (el valor predeterminado), la respuesta es una matriz de valores numéricos que corresponden a versiones habilitadas del artefacto (se omiten las versiones inhabilitadas). Tiene el mismo formato que el que genera actualmente el punto final. Si especifica 'object', la respuesta es un objeto JSON que contiene una matriz de objetos JSON que representan versiones del artefacto. Tanto las versiones habilitadas como las inhabilitadas se incluyen en la matriz.

Ejemplo de solicitud de curl:

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

o

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

o

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

Respuesta de ejemplo cuando jsonformat es número, o no se proporciona (el valor predeterminado es número):

[1,3,4,6,7]

Respuesta de ejemplo cuando jsonformat es objeto:

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

La obtención de la lista de versiones disponibles de un esquema requiere al menos ambos:

• Acceso de rol de lector al tipo de recurso de clúster de Event Streams.
• Acceso de rol de lector al recurso de esquema que coincide con el esquema recuperado.

Supresión de una versión de un esquema

Las versiones de esquema se eliminan del registro mediante una solicitud DELETE al punto de conexión /artifacts/{schema-id}/versions/{version} (donde {schema-id} es el ID del esquema y {version} es el número de versión del esquema). Si se ejecuta correctamente, se devuelve una respuesta vacía y un código de estado 204 (sin contenido). Al eliminar la única versión restante de un esquema, también se elimina el esquema.

Ejemplo de solicitud de curl:

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

La supresión de una versión de esquema requiere al menos ambos:

• Acceso de rol de lector al tipo de recurso de clúster de Event Streams.
• Acceso de rol de administrador al recurso de esquema que coincide con el esquema que se elimina.

Se genera un suceso de Activity Tracker para informar de la acción. Para obtener más información, consulte Sucesos de Activity Tracker.

Obtención del ID exclusivo global específico de una versión de esquema

Para recuperar un ID único global específico de una versión de esquema, realice una solicitud GET al punto final /artifacts/{artifactId}/versions/{version}/meta (donde {artifactId} es el ID del artefacto y {version} es el número de versión de la versión específica que necesita recuperar). Si es satisfactorio, el ID exclusivo global específico de una versión de esquema se devuelve en la carga útil de la respuesta.

Ejemplo de solicitud de curl:

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

Respuesta de ejemplo:

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

La obtención del ID exclusivo global de una versión de esquema requiere al menos los dos tipos de acceso siguientes:

• Acceso de rol de lector al tipo de recurso de clúster de Event Streams.
• Acceso de rol de lector al recurso de esquema que coincide con el esquema recuperado.

Actualización de una regla global

Las reglas de compatibilidad global pueden actualizarse enviando una solicitud PUT al punto final /rules/ {rule-type} (donde {rule-type} identifica el tipo de regla global que se va a actualizar; actualmente el único tipo admitido es COMPATIBILITY), con la nueva configuración de la regla en el cuerpo de la solicitud. Si la solicitud es correcta, la configuración de regla recién actualizada se devuelve en la carga útil de la respuesta, junto con un código de estado 200 (OK).

El documento JSON que se envía en el cuerpo de la solicitud debe tener las siguientes propiedades:

Ejemplo de solicitud de curl:

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

Respuesta de ejemplo:

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

Actualizar una configuración de regla global requiere como mínimo:

• Acceso de rol de gestor al tipo de recurso de clúster de Event Streams.

Se genera un suceso de Activity Tracker para informar de la acción. Para obtener más información, consulte Sucesos de Activity Tracker.

Obtención del valor actual de una regla global

El valor actual de una regla global se recupera emitiendo una solicitud GET al punto final /rules/ {rule-type} (donde {rule-type} es el tipo de regla global que se va a recuperar; actualmente el único tipo admitido es COMPATIBILITY). Si la solicitud es correcta, la configuración de la regla actual se devuelve en la carga útil de la respuesta, junto con un código de estado 200 (OK).

Ejemplo de solicitud de curl:

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

Respuesta de ejemplo:

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

Obtener una configuración de regla global requiere como mínimo:

• Acceso de rol de lector al tipo de recurso de clúster de Event Streams.

Creación de una regla por esquema

Las reglas se pueden aplicar a un esquema específico, anulando cualquier regla global que se haya establecido, realizando una solicitud POST al punto final /artifacts/{schema-id}/rules (donde {schema-id} es el ID del esquema), con el tipo y el valor de la nueva regla que está contenida en el cuerpo de la solicitud (actualmente el único tipo admitido es COMPATIBILITY). Si se ejecuta correctamente, se devuelve una respuesta vacía y un código de estado 204 (sin contenido).

Ejemplo de solicitud de curl:

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

Crear reglas por esquema requiere al menos:

• Acceso de rol de lector al tipo de recurso de clúster de Event Streams.
• Acceso de rol de administrador al recurso de esquema al que se aplica la regla.

Se genera un suceso de Activity Tracker para informar de la acción. Para obtener más información, consulte Sucesos de Activity Tracker.

Obtención de una regla por esquema

Para recuperar el valor actual de un tipo de regla que se aplica a un esquema específico, se realiza una solicitud GET al punto final /artifacts/{schema-id}/rules/{rule-type} (donde {schema-id} es el ID del esquema y {rule-type} es el tipo de regla global que se va a recuperar; actualmente el único tipo admitido es COMPATIBILITY). Si la solicitud es correcta, el valor de la regla actual se devuelve en la carga útil de la respuesta, junto con un código de estado 200 (OK).

Ejemplo de solicitud de curl:

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

Respuesta de ejemplo:

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

Obtener reglas por esquema requiere al menos:

• Acceso de rol de lector al tipo de recurso de clúster de Event Streams.
• Acceso de rol de lector al recurso de esquema al que se aplica la regla.

Actualización de una regla por esquema

Las reglas aplicadas a un esquema específico se modifican realizando una solicitud PUT al punto final /artifacts/{schema-id}/rules/{rule-type} (donde {schema-id} es el ID del esquema y {rule-type} es el tipo de regla global que se va a recuperar; actualmente, el único tipo admitido es COMPATIBILITY). Si la solicitud es correcta, la configuración de regla recién actualizada se devuelve en la carga útil de la respuesta, junto con un código de estado 200 (OK).

Ejemplo de solicitud de curl:

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

Respuesta de ejemplo:

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

Actualizar una regla por esquema requiere como mínimo:

• Acceso de rol de lector al tipo de recurso de clúster de Event Streams.
• Acceso de rol de gestor al recurso de esquema al que se aplica la regla.

Se genera un suceso de Activity Tracker para informar de la acción. Para obtener más información, consulte Sucesos de Activity Tracker.

Supresión de una regla por esquema

Las reglas aplicadas a un esquema específico se eliminan realizando una solicitud DELETE al punto final /artifacts/{schema-id}/rules/{rule-type} (donde {schema-id} es el ID del esquema y {rule-type} es el tipo de regla global que se va a recuperar; actualmente el único tipo admitido es COMPATIBILITY). Si la solicitud es correcta, se devuelve una respuesta vacía, con un código de estado de 204 (sin contenido).

Ejemplo de solicitud de curl:

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

Suprimir una regla por esquema requiere como mínimo:

• Acceso de rol de lector al tipo de recurso de clúster de Event Streams.
• Acceso de rol de gestor al recurso de esquema al que se aplica la regla.

Se genera un suceso de Activity Tracker para informar de la acción. Para obtener más información, consulte Sucesos de Activity Tracker.