Crea un asunto

En este documento, se describe cómo crear un tema en un registro de esquema. Un tema es un contenedor lógico para diferentes versiones de un esquema. Cuando creas un tema por primera vez, también creas la primera versión del esquema para ese tema.

Puedes crear un asunto de una de las siguientes maneras:

Implícito (predeterminado): El comportamiento predeterminado para muchos clientes productores y consumidores es crear automáticamente un esquema que no existe cuando se conecta el cliente. También se crean automáticamente el asunto y la versión que hacen referencia al esquema. Esto es conveniente, pero puede generar posibles incoherencias en los datos si varios clientes crean versiones de forma simultánea.
Explícito (recomendado): En este método, cada esquema debe crearse en el registro antes de que un cliente productor o consumidor pueda usarlo. Puedes usar la consola de Google Cloud o la API de Managed Kafka para hacerlo.

Este comportamiento se debe configurar en la configuración del cliente. Consulta la documentación de la biblioteca cliente del serializador o deserializador para obtener más detalles.

Antes de comenzar

Obtén más información sobre el resumen del esquema.
Crea un registro de esquema si aún no tienes uno.
Comprende las referencias de esquema.

Roles y permisos requeridos

Para obtener los permisos que necesitas para crear un tema, pídele a tu administrador que te otorgue el rol de IAM Editor del registro de esquemas de Kafka administrado (roles/managedkafka.schemaRegistryEditor) en tu proyecto o registro de esquemas. 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 crear un asunto. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:

Permisos necesarios

Se requieren los siguientes permisos para crear un asunto:

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 los permisos para crear y administrar versiones de temas.

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

Cómo crear un tema o la primera versión de un esquema

Cuando creas un tema, también creas su primera versión. Esta primera versión crea un esquema nuevo o es una referencia a un esquema existente.

Console

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

Ir a Registros de esquemas
Haz clic en el nombre del registro de esquemas en el que deseas crear un tema.
Haz clic en Crear asunto.
En Nombre del asunto, ingresa un nombre único para el asunto.

El nombre debe comenzar con una letra y solo puede contener letras, números y los siguientes caracteres especiales: guion (-), punto (.), guion bajo (_), virgulilla (~), porcentaje (%) o signo más (+). El nombre de un tema es inmutable.

Para obtener más información sobre cómo elegir un nombre de asunto, consulta Estrategias para nombrar asuntos.
En Context, elige un contexto o crea uno nuevo. Los contextos actúan como espacios de nombres para organizar tus temas y esquemas, y proporcionan aislamiento entre diferentes grupos.
- Para usar un contexto existente, selecciónalo en la lista Context. El contexto predeterminado se muestra como (default context).
- Para crear un contexto nuevo, sigue estos pasos:
  1. Selecciona Crear contexto en la lista Contexto.
  2. En el campo Nombre del contexto, ingresa un nombre para el contexto.
    
    El nombre debe comenzar con una letra y solo puede contener letras, números y los siguientes caracteres especiales: guion (-), punto (.), guion bajo (_), virgulilla (~), porcentaje (%) o signo más (+). El nombre de un contexto es inmutable.
  3. Haz clic en Guardar.
En Tipo de esquema, selecciona Avro o Búfer de protocolo.
En el campo Definición del esquema, ingresa la definición del esquema. El formato del esquema debe coincidir con el tipo de esquema. 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.
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.
Haz clic en Crear.

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.

En los siguientes ejemplos de la API de REST, se crea la primera versión de un tema.

Para crear un asunto dentro del contexto predeterminado, realiza una solicitud POST al URI especificado con el método projects.locations.schemaRegistries.subjects.versions.create:

POST https://managedkafka.googleapis.com/v1main/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 temas con el método projects.locations.schemaRegistries.contexts.subjects.versions.create:

POST https://managedkafka.googleapis.com/v1main/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 . 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.

El nombre debe comenzar con una letra y solo puede contener letras, números y los siguientes caracteres especiales: guiones -, puntos ., guiones bajos _, virgulillas ~, porcentajes % o signos de suma +. El nombre de un contexto es inmutable.
SUBJECT_ID (obligatorio): Es el ID del tema nuevo en el que se creará la primera versión.

El nombre debe comenzar con una letra y solo puede contener letras, números y los siguientes caracteres especiales: guiones -, puntos ., guiones bajos _, virgulillas ~, porcentajes % o signos de suma +. El nombre de un asunto es inmutable.

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

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.
schemaType (opcional): Es el tipo de esquema. Puede ser AVRO o PROTOBUF. Si se omite, el valor predeterminado es AVRO.
references (opcional): 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 ID del tema del esquema al que se hace referencia.
- REFERENCED_VERSION_NUMBER: Es el número de versión específico del esquema del sujeto al que se hace referencia.
versionId y schemaId: Son campos opcionales que suele controlar el servicio. Para la primera versión de un tema, versionId será "1".

Si la solicitud se realiza correctamente y el esquema es válido y pasa las verificaciones de compatibilidad (si se configuraron), la API devuelve un código de estado 200 OK. El cuerpo de la respuesta contiene el ID del esquema que usa la versión creada, que es diferente del ID de la versión.

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

¿Qué sigue?

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