Registra una nueva versión del esquema

Versión preliminar

Este producto o función está con sujeción a las "Condiciones de las Ofertas de la Fase Previa a la DG" de la sección de Términos Generales del Servicio de los Términos Específicos del Servicio. Los productos y las funciones de la fase previa a la DG están disponibles sin modificaciones y pueden estar sujetos a asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

Después de crear un tema, puedes agregarle versiones nuevas. Este proceso se conoce como registro de una nueva versión del esquema. Cada versión nueva representa una evolución del esquema asociado a ese tema.

Un tema puede tener varias versiones. Las versiones dentro de un tema siguen reglas de compatibilidad configurables para garantizar una evolución segura del esquema. Por ejemplo, un tema puede requerir que todos los cambios sean retrocompatibles. Un ejemplo de cambio retrocompatible es agregar un campo opcional. Agregar un campo obligatorio se consideraría un cambio incompatible con versiones anteriores. Si tu tema está configurado para ser compatible con versiones anteriores, este cambio no se permite. Sin embargo, si tu tema está configurado para ser compatible con versiones futuras, se aceptaría agregar un campo obligatorio.

Las verificaciones de compatibilidad no son retroactivas. Si se cambian las reglas de compatibilidad para un registro de esquemas o un tema, las versiones que ya existen en el tema no se vuelven a validar según las reglas nuevas. Para obtener más información sobre la compatibilidad, consulta Acerca del tipo de compatibilidad.

Roles y permisos requeridos

Para obtener los permisos que necesitas para registrar una versión de esquema para un tema, pídele a tu administrador que te otorgue el rol de IAM de Editor del registro de esquemas de Kafka administrado (roles/managedkafka.schemaRegistryEditor) en tu proyecto o en el registro de esquemas y el tema específicos. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Este rol predefinido contiene los permisos necesarios para registrar una versión de esquema para un tema. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:

Permisos necesarios

Se requieren los siguientes permisos para registrar una versión de esquema para un tema:

• Otorga este permiso en el contexto principal o en el contexto predeterminado: managedkafka.versions.create

También puedes obtener estos permisos con roles personalizados o con otros roles predefinidos.

El rol de nivel superior Administrador del registro de esquemas de Kafka administrado (roles/managedkafka.schemaRegistryAdmin) también incluye estos permisos.

Para obtener más información sobre los roles predefinidos disponibles para Managed Service for Apache Kafka, consulta la documentación de control de acceso.

Registra una nueva versión del esquema

Para registrar una nueva versión del esquema, sigue estos pasos.

Console

1. En la consola Google Cloud , ve a la página Registros de esquemas.

   Ir a Registros de esquemas

2. Haz clic en el nombre del registro de esquemas en el que deseas registrar una nueva versión del esquema.

3. En Sujetos en este registro de esquemas, haz clic en el nombre del sujeto.

4. En la página Detalles del asunto, haz clic en Crear versión.

5. En el campo Definición del esquema, se muestra la definición de la versión más reciente. Actualiza la definición en este campo para la versión nueva. No incluyas información sensible, como información de identificación personal (PII) ni datos de seguridad, en los nombres de los campos del esquema.

6. Si tu esquema usa o depende de estructuras de datos definidas en otros esquemas del registro de esquemas, sigue estos pasos:

   1. Haz clic en Agregar referencia de esquema.
   2. En el campo Nombre de referencia, ingresa el nombre de referencia del esquema al que se hace referencia.
   3. En la lista Asunto, selecciona el asunto que contiene el esquema al que se hace referencia.
   4. En la lista Versión, selecciona el número de versión del esquema al que se hace referencia.
   5. Haz clic en Aceptar.

   Repite estos pasos para cada esquema al que se haga referencia.

7. Opcional: Para verificar si el esquema nuevo es compatible con la versión anterior, haz clic en Verificar compatibilidad.

   Si el esquema es compatible, se mostrará una marca de verificación . De lo contrario, aparecerá un mensaje de error. En ese caso, corrige el error y vuelve a hacer clic en Verificar compatibilidad.

   La verificación de compatibilidad que se realiza depende del tipo de compatibilidad del sujeto.

8. Haz clic en Crear. Si la definición del esquema es válida y pasa las verificaciones de compatibilidad del tema, la nueva versión aparecerá en Todas las versiones.

REST

La solicitud debe autenticarse con un token de acceso en el encabezado Authorization. Para obtener un token de acceso para las credenciales predeterminadas actuales de la aplicación, usa el siguiente comando: gcloud auth application-default print-access-token.

Para registrar una nueva versión de esquema para un tema dentro del contexto predeterminado, realiza una solicitud POST al URI específico con el método projects.locations.schemaRegistries.subjects.versions.create:

POST https://managedkafka.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/schemaRegistries/REGISTRY_ID/subjects/SUBJECT_ID/versions
Authorization: Bearer $(gcloud auth application-default print-access-token)
Content-Type: application/json

Como alternativa, si usas un contexto específico, incluye el contexto en el URI de la colección de versiones y usa el método projects.locations.schemaRegistries.contexts.subjects.versions.create.

POST https://managedkafka.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/schemaRegistries/REGISTRY_ID/contexts/CONTEXT_ID/subjects/SUBJECT_ID/versions
Authorization: Bearer $(gcloud auth application-default print-access-token)
Content-Type: application/json

Reemplaza lo siguiente:

• PROJECT_ID (obligatorio): ID del proyecto de Google Cloud.
• LOCATION (obligatorio): Es la Google Cloud región en la que existe el registro de esquemas.
• REGISTRY_ID (obligatorio): Es el ID del registro de esquema de destino.
• CONTEXT_ID (opcional): Es el ID del contexto que contiene el asunto. Usa . (un solo punto) para el contexto predeterminado si deseas ser explícito. De lo contrario, omite /contexts/CONTEXT_ID para usar el contexto predeterminado de forma implícita.
• SUBJECT_ID (obligatorio): Es el ID del tema sobre el que se creará la versión nueva.

Cuerpo de la solicitud:

Incluye un objeto JSON en el cuerpo de la solicitud que especifique los detalles del esquema:

{
  "schema": "YOUR_SCHEMA_DEFINITION_STRING",
  "schema_type": "AVRO" | "PROTOBUF" | "JSON", // Optional, defaults to AVRO
  "references": [ // Optional
    {
      "name": "REFERENCE_NAME",
      "subject": "REFERENCED_SUBJECT_ID",
      "version": REFERENCED_VERSION_NUMBER
    }
    // ... more references
  ]
  // "version": VERSION_NUMBER, // Optional: Usually omitted, let service assign next
  // "id": SCHEMA_ID, // Optional: Usually omitted, let service assign or reuse
}

Reemplaza lo siguiente:

• YOUR_SCHEMA_DEFINITION_STRING (obligatorio): Es una cadena que contiene la carga útil de la definición del esquema real.

• schemaType (opcional, dentro del objeto schema): Es el tipo de esquema. Puede ser AVRO o PROTOBUF. Si se omite, el valor predeterminado es AVRO.

• references (opcional, dentro del objeto schema): Es un array de objetos que definen los esquemas a los que hace referencia este esquema.

  • REFERENCE_NAME: Es el nombre que se usa para hacer referencia al otro esquema dentro de la definición de este esquema.

  • REFERENCED_SUBJECT_ID: Es el nombre del asunto completamente calificado del esquema al que se hace referencia. Ejemplo: projects/test-project/locations/us-central1/schemaRegistries/test-registry/subjects/test-referenced-subject.

  • REFERENCED_VERSION_NUMBER: Es el número de versión específico (número entero) del esquema del tema al que se hace referencia.

• versionId y schemaId: Son campos opcionales que suele controlar el servicio. Cuando se registra la versión del esquema, el servicio asigna el siguiente número de versión disponible.

Si la solicitud se realiza correctamente, la API devuelve un código de estado 200 OK y un cuerpo de respuesta que contiene el ID del esquema.

Para obtener más información, consulta la documentación de la API de REST.

¿Qué sigue?

• Más información sobre el registro de esquemas
• Enumera las versiones del asunto
• Cómo borrar una versión de un tema del esquema

Apache Kafka® es una marca registrada de The Apache Software Foundation o sus afiliados en Estados Unidos y otros países.