Ús de Schemas a EventHub (Schema Registry)

Navegació

Ús de Schemas a EventHub (Schema Registry)

Canigó – Guia per a aplicacions

Aquesta pàgina explica què ha de fer una aplicació per crear o modificar un schema a EventHub mitjançant Schema Registry.

1. Quan necessites un schema?

Necessites un schema si:

• Publiques o consumeixes esdeveniments amb estructura definida.
• Vols garantir la compatibilitat entre productors i consumidors.
• El topic està governat a EventHub.

❌ No utilitzis schemas si:

• El topic és purament tècnic i sense contracte estable.
• No existeix intenció de reutilització ni d’evolució controlada.

2. Alta o modificació d’un schema: què has de fer

Pas 1. Tenir el topic governat

• Tot schema ha d’estar associat a un topic existent.

Pas 2. Omplir la plantilla de sol·licitud (obligatori)

• Plantilla oficial: Plantillas_Solicitud_EventHub
• Pestanya Solicitud_Schema, una fila per schema.

Camps que ha d’omplir l’aplicació:

Camps automàtics: Codigo_Aplicacion, Nombre_Aplicacion, JIRA_ID, Owners (heredats de Datos_Proyecto). Nombre_Schema_Generado: {topic}-value.

Pas 3-5. Sol·licitud, validació i registre

Idèntic al flux estàndard: tiquet JIRA → validació Oficina → registre a Schema Registry. Cada canvi genera una nova versió automàtica.

3. Configuració del client Schema Registry

Per connectar la teva aplicació al Schema Registry d’EventHub, configura les següents propietats:

# URL del Schema Registry (ajustar segons entorn)
schema.registry.url=<url_schema_registry>

# Classe del convertidor utilitzat per serialitzar/desseralitzar key i el value del missatge
key.serializer=<converter_class>
value.serializer=<converter_class>

# Propietat per a indiqués que el client no té permisos per a registrar o actualitzar esquemes
auto.register.schemas=false

URLs del Schema Registry per entorn:

Les credencials d’accés al Schema Registry es proporcionen durant el procés d’onboarding. Sol·liciteu-les a l’Oficina EventHub si no les teniu.

4. Format de l’esquema

Quan proporcioneu l’esquema a la fitxa de sol·licitud, assegureu-vos que:

• El JSON sigui vàlid i estigui correctament formatat.
• No inclogui metadades de Schema Registry (com subject, version, id). Proporcioneu només la definició del schema.
• Si utilitzeu AVRO, seguiu l’especificació Avro.

5. Compatibilitat de schemas (resum pràctic)

Política per defecte: BACKWARD.

Excepcions:

• Compatibilitat diferent de BACKWARD requereix justificació i validació.
• NONE només en casos molt concrets (ex: connectors externs).
• FORWARD o FULL requereixen aprovació expressa.

6. Canvis, eliminació i errors habituals

Canvis

Actualitzar fitxa → tiquet JIRA → coordinar si hi ha impacte → CRQ en PRO.

Eliminació

Només quan no existeixin missatges pendents i el topic associat es retiri.

Errors habituals

• Canvis incompatibles sense coordinació.
• Registrar schemas sense topic governat.
• No avaluar l’impacte en consumidors.
• Proporcionar l’esquema amb metadades de SR incloses.

7. Documentació de referència

• Plantillas_Solicitud_EventHub
• Estàndard de Schemas
• Estàndard de Compatibilitat
• Documentació Schema Registry Confluent

I ara què?

• -> Estàndards i validació
• -> Autoservei governat
• -> Canvi i desplegament