Compartir a través de

Biblioteca cliente de Azure Schema Registry para Python: versión 1.2.0

  • Artículo

Azure Schema Registry es un servicio de repositorio de esquemas hospedado por Azure Event Hubs, lo que proporciona almacenamiento de esquemas, control de versiones y administración. Los serializadores aprovechan el registro para reducir el tamaño de la carga mientras se describe la estructura de carga con identificadores de esquema en lugar de esquemas completos.

Código | fuente Paquete (PyPi) | Documentación | de referencia de APIMuestras | Changelog

Declinación de responsabilidades

El 1 de enero de 2022 finalizó la compatibilidad de paquetes de Python del SDK de Azure para Python 2.7. Para más información y preguntas, consulte https://github.com/Azure/azure-sdk-for-python/issues/20691.

Introducción

Instalar el paquete

Instale la biblioteca cliente de Azure Schema Registry para Python con pip:

pip install azure-schemaregistry

Requisitos previos:

Para usar este paquete, debe tener:

Autenticar el cliente

La interacción con el Registro de esquema comienza con una instancia de la clase SchemaRegistryClient. El constructor de cliente toma el espacio de nombres completo y una credencial de Azure Active Directory:

  • El espacio de nombres completo de la instancia del Registro de esquema debe seguir el formato : <yournamespace>.servicebus.windows.net.

  • Una credencial de AAD que implemente el protocolo TokenCredential debe pasarse al constructor. Hay implementaciones del TokenCredential protocolo disponibles en el paquete azure-identity. Para usar los tipos de credenciales proporcionados por azure-identity, instale la biblioteca cliente de Azure Identity para Python con pip:

pip install azure-identity
  • Además, para usar la API asincrónica, primero debe instalar un transporte asincrónico, como aiohttp:
pip install aiohttp

Cree un cliente mediante la biblioteca azure-identity:

from azure.schemaregistry import SchemaRegistryClient
from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()
# Namespace should be similar to: '<your-eventhub-namespace>.servicebus.windows.net/'
fully_qualified_namespace = '<< FULLY QUALIFIED NAMESPACE OF THE SCHEMA REGISTRY >>'
schema_registry_client = SchemaRegistryClient(fully_qualified_namespace, credential)

Conceptos clave

  • Esquema: el esquema es la organización o estructura de los datos. Puede encontrar información más detallada aquí.

  • Grupo de esquemas: un grupo lógico de esquemas similares basados en criterios empresariales, que pueden contener varias versiones de un esquema. Puede encontrar información más detallada aquí.

  • SchemaRegistryClient: SchemaRegistryClient proporciona la API para almacenar y recuperar esquemas en el registro de esquemas.

Ejemplos

En las secciones siguientes se proporcionan varios fragmentos de código que abarcan algunas de las tareas más comunes del Registro de esquemas, entre las que se incluyen:

Registro de un esquema

Use SchemaRegistryClient.register_schema el método para registrar un esquema.

import os

from azure.identity import DefaultAzureCredential
from azure.schemaregistry import SchemaRegistryClient

token_credential = DefaultAzureCredential()
fully_qualified_namespace = os.environ['SCHEMA_REGISTRY_FULLY_QUALIFIED_NAMESPACE']
group_name = os.environ['SCHEMA_REGISTRY_GROUP']
name = "your-schema-name"
format = "Avro"
definition = """
{"namespace": "example.avro",
 "type": "record",
 "name": "User",
 "fields": [
     {"name": "name", "type": "string"},
     {"name": "favorite_number",  "type": ["int", "null"]},
     {"name": "favorite_color", "type": ["string", "null"]}
 ]
}
"""

schema_registry_client = SchemaRegistryClient(fully_qualified_namespace=fully_qualified_namespace, credential=token_credential)
with schema_registry_client:
    schema_properties = schema_registry_client.register_schema(group_name, name, definition, format)
    id = schema_properties.id

Obtención del esquema por identificador

Obtenga la definición del esquema y sus propiedades por identificador de esquema.

import os

from azure.identity import DefaultAzureCredential
from azure.schemaregistry import SchemaRegistryClient

token_credential = DefaultAzureCredential()
fully_qualified_namespace = os.environ['SCHEMA_REGISTRY_FULLY_QUALIFIED_NAMESPACE']
schema_id = 'your-schema-id'

schema_registry_client = SchemaRegistryClient(fully_qualified_namespace=fully_qualified_namespace, credential=token_credential)
with schema_registry_client:
    schema = schema_registry_client.get_schema(schema_id)
    definition = schema.definition
    properties = schema.properties

Obtención del esquema por versión

Obtenga la definición del esquema y sus propiedades por versión del esquema.

import os

from azure.identity import DefaultAzureCredential
from azure.schemaregistry import SchemaRegistryClient

token_credential = DefaultAzureCredential()
fully_qualified_namespace = os.environ['SCHEMA_REGISTRY_FULLY_QUALIFIED_NAMESPACE']
group_name = os.environ["SCHEMAREGISTRY_GROUP"]
name = "your-schema-name"
version = int("<your schema version>")

schema_registry_client = SchemaRegistryClient(fully_qualified_namespace=fully_qualified_namespace, credential=token_credential)
with schema_registry_client:
    schema = schema_registry_client.get_schema(group_name=group_name, name=name, version=version)
    definition = schema.definition
    properties = schema.properties

Obtención del identificador de un esquema

Obtenga el identificador de esquema de un esquema por definición de esquema y sus propiedades.

import os

from azure.identity import DefaultAzureCredential
from azure.schemaregistry import SchemaRegistryClient

token_credential = DefaultAzureCredential()
fully_qualified_namespace = os.environ['SCHEMA_REGISTRY_FULLY_QUALIFIED_NAMESPACE']
group_name = os.environ['SCHEMA_REGISTRY_GROUP']
name = "your-schema-name"
format = "Avro"
definition = """
{"namespace": "example.avro",
 "type": "record",
 "name": "User",
 "fields": [
     {"name": "name", "type": "string"},
     {"name": "favorite_number",  "type": ["int", "null"]},
     {"name": "favorite_color", "type": ["string", "null"]}
 ]
}
"""

schema_registry_client = SchemaRegistryClient(fully_qualified_namespace=fully_qualified_namespace, credential=token_credential)
with schema_registry_client:
    schema_properties = schema_registry_client.register_schema(group_name, name, definition, format)
    id = schema_properties.id

Solución de problemas

General

Los clientes del Registro de esquema generan excepciones definidas en Azure Core.

Registro

Esta biblioteca usa la biblioteca de registro estándar para el registro. La información básica sobre las sesiones HTTP (direcciones URL, encabezados, etc.) se registra en el nivel INFO.

El registro detallado de nivel de DEPURACIÓN, incluidos los cuerpos de solicitud/respuesta y los encabezados no aprobados, se puede habilitar en un cliente con el logging_enable argumento :

import sys
import logging
from azure.schemaregistry import SchemaRegistryClient
from azure.identity import DefaultAzureCredential

# Create a logger for the SDK
logger = logging.getLogger('azure.schemaregistry')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

credential = DefaultAzureCredential()
# This client will log detailed information about its HTTP sessions, at DEBUG level
schema_registry_client = SchemaRegistryClient("your_fully_qualified_namespace", credential, logging_enable=True)

Igualmente, logging_enable puede habilitar el registro detallado de una sola operación, aunque no esté habilitado para el cliente:

schema_registry_client.get_schema(schema_id, logging_enable=True)

Pasos siguientes

Más código de ejemplo

Eche un vistazo al directorio de ejemplos para obtener ejemplos detallados de cómo usar esta biblioteca para registrar y recuperar el esquema hacia o desde el Registro de esquemas.

Contribuciones

Este proyecto agradece las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia para el colaborador (CLA) que declara que tiene el derecho a concedernos y nos concede los derechos para usar su contribución. Para más detalles, visite https://cla.microsoft.com.

Cuando se envía una solicitud de incorporación de cambios, un bot de CLA determinará de forma automática si tiene que aportar un CLA y completar la PR adecuadamente (por ejemplo, la etiqueta, el comentario). Solo siga las instrucciones que le dará el bot. Solo será necesario que lo haga una vez en todos los repositorios con nuestro CLA.

Este proyecto ha adoptado el Código de conducta de Microsoft Open Source. Para más información, consulte las preguntas más frecuentes del código de conducta o póngase en contacto con opencode@microsoft.com si tiene cualquier otra pregunta o comentario.