.. role:: raw-html-m2r(raw) :format: html Azure Schema Registry client library for Python =============================================== Azure Schema Registry is a schema repository service hosted by Azure Event Hubs, providing schema storage, versioning, and management. The registry is leveraged by serializers to reduce payload size while describing payload structure with schema identifiers rather than full schemas. `Source code `_ | `Package (PyPi) `_ | `API reference documentation `_ | `Samples `_ | `Changelog `_ *Disclaimer* ---------------- *Azure SDK Python packages support for Python 2.7 has ended on 01 January 2022. For more information and questions, please refer to https://github.com/Azure/azure-sdk-for-python/issues/20691* Getting started --------------- Install the package ^^^^^^^^^^^^^^^^^^^ Install the Azure Schema Registry client library for Python with `pip `_\ : .. code-block:: Bash pip install azure-schemaregistry Prerequisites: ^^^^^^^^^^^^^^ To use this package, you must have: * Azure subscription - `Create a free account `_ * `Azure Schema Registry `_ - `Here is the quickstart guide `_ to create a Schema Registry group using the Azure portal. * Python 3.7 or later - `Install Python `_ Authenticate the client ^^^^^^^^^^^^^^^^^^^^^^^ Interaction with Schema Registry starts with an instance of SchemaRegistryClient class. The client constructor takes the fully qualified namespace and an Azure Active Directory credential: * The fully qualified namespace of the Schema Registry instance should follow the format: ``.servicebus.windows.net``. * An AAD credential that implements the `TokenCredential `_ protocol should be passed to the constructor. There are implementations of the ``TokenCredential`` protocol available in the `azure-identity package `_. To use the credential types provided by ``azure-identity``\ , please install the Azure Identity client library for Python with `pip `_\ : .. code-block:: Bash pip install azure-identity * Additionally, to use the async API, you must first install an async transport, such as `aiohttp `_\ : .. code-block:: Bash pip install aiohttp **Create client using the azure-identity library:** .. code-block:: python from azure.schemaregistry import SchemaRegistryClient from azure.identity import DefaultAzureCredential credential = DefaultAzureCredential() # Namespace should be similar to: '.servicebus.windows.net/' fully_qualified_namespace = '<< FULLY QUALIFIED NAMESPACE OF THE SCHEMA REGISTRY >>' schema_registry_client = SchemaRegistryClient(fully_qualified_namespace, credential) Key concepts ------------ * Schema: Schema is the organization or structure for data. More detailed information can be found `here `_. * Schema Group: A logical group of similar schemas based on business criteria, which can hold multiple versions of a schema. More detailed information can be found `here `_. * SchemaRegistryClient: ``SchemaRegistryClient`` provides the API for storing and retrieving schemas in schema registry. Examples -------- The following sections provide several code snippets covering some of the most common Schema Registry tasks, including: * `Register a schema <#register-a-schema>`_ * `Get the schema by id <#get-the-schema-by-id>`_ * `Get the schema by version <#get-the-schema-by-version>`_ * `Get the id of a schema <#get-the-id-of-a-schema>`_ Register a schema ^^^^^^^^^^^^^^^^^ Use ``SchemaRegistryClient.register_schema`` method to register a schema. .. code-block:: python 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 Get the schema by id ^^^^^^^^^^^^^^^^^^^^ Get the schema definition and its properties by schema id. .. code-block:: python 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 Get the schema by version ^^^^^^^^^^^^^^^^^^^^^^^^^ Get the schema definition and its properties by schema version. .. code-block:: python 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("") 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 Get the id of a schema ^^^^^^^^^^^^^^^^^^^^^^ Get the schema id of a schema by schema definition and its properties. .. code-block:: python 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 Troubleshooting --------------- General ^^^^^^^ Schema Registry clients raise exceptions defined in `Azure Core `_. Logging ^^^^^^^ This library uses the standard `logging `_ library for logging. Basic information about HTTP sessions (URLs, headers, etc.) is logged at INFO level. Detailed DEBUG level logging, including request/response bodies and unredacted headers, can be enabled on a client with the ``logging_enable`` argument: .. code-block:: python 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) Similarly, ``logging_enable`` can enable detailed logging for a single operation, even when it isn't enabled for the client: .. code-block:: py schema_registry_client.get_schema(schema_id, logging_enable=True) Next steps ---------- More sample code ^^^^^^^^^^^^^^^^ Please take a look at the `samples `_ directory for detailed examples of how to use this library to register and retrieve schema to/from Schema Registry. Contributing ------------ This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com. When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA. This project has adopted the `Microsoft Open Source Code of Conduct `_. For more information see the `Code of Conduct FAQ `_ or contact `opencode@microsoft.com `_ with any additional questions or comments. :raw-html-m2r:`` Indices and tables ------------------ * :ref:`genindex` * :ref:`modindex` * :ref:`search` .. toctree:: :maxdepth: 5 :glob: :caption: Developer Documentation azure.schemaregistry.rst