.. 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 `_
Getting started
---------------
Install the package
^^^^^^^^^^^^^^^^^^^
Install the Azure Schema Registry client library and Azure Identity client library for Python with `pip `_\ :
.. code-block:: Bash
pip install azure-schemaregistry azure-identity
Prerequisites:
^^^^^^^^^^^^^^
To use this package, you must have:
* Azure subscription - `Create a free account `_
* `Azure Schema Registry `_
* Python 2.7, 3.6 or later - `Install Python `_
Authenticate the client
^^^^^^^^^^^^^^^^^^^^^^^
Interaction with Schema Registry starts with an instance of SchemaRegistryClient class. You need the endpoint and AAD credential to instantiate the client object.
**Create client using the azure-identity library:**
.. code-block:: python
from azure.schemaregistry import SchemaRegistryClient
from azure.identity import DefaultAzureCredential
credential = DefaultAzureCredential()
endpoint = '<< ENDPOINT OF THE SCHEMA REGISTRY >>'
schema_registry_client = SchemaRegistryClient(endpoint, credential)
Key concepts
------------
*
Schema: Schema is the organization or structure for data.
*
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 id of a schema <#get-the-id-of-a-schema>`_
Register a schema
^^^^^^^^^^^^^^^^^
Use ``SchemaRegistryClient.register_schema`` method to register a schema.
When registering a schema, the ``Schema`` and ``SchemaProperties`` will be cached in the ``SchemaRegistryClient`` instance, so that any subsequent calls to ``get_schema_id`` and ``get_schema`` corresponding to the same schema can use the cached value rather than going to the service.
.. code-block:: python
import os
from azure.identity import DefaultAzureCredential
from azure.schemaregistry import SchemaRegistryClient
token_credential = DefaultAzureCredential()
endpoint = os.environ['SCHEMA_REGISTRY_ENDPOINT']
schema_group = ""
schema_name = ""
serialization_type = "Avro"
schema_content = """
{"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(endpoint=endpoint, credential=token_credential)
with schema_registry_client:
schema_properties = schema_registry_client.register_schema(schema_group, schema_name, serialization_type, schema_content)
schema_id = schema_properties.schema_id
Get the schema by id
^^^^^^^^^^^^^^^^^^^^
Get the schema content and its properties by schema id.
When looking up the schema content by schema id, the ``Schema`` will be cached in the ``SchemaRegistryClient`` instance so that subsequent requests for this schema id do not need to go the service.
.. code-block:: python
import os
from azure.identity import DefaultAzureCredential
from azure.schemaregistry import SchemaRegistryClient
token_credential = DefaultAzureCredential()
endpoint = os.environ['SCHEMA_REGISTRY_ENDPOINT']
schema_id = ''
schema_registry_client = SchemaRegistryClient(endpoint=endpoint, credential=token_credential)
with schema_registry_client:
schema = schema_registry_client.get_schema(schema_id)
schema_content = schema.schema_content
Get the id of a schema
^^^^^^^^^^^^^^^^^^^^^^
Get the schema id of a schema by schema content and its properties.
When looking up the schema id, the ``Schema`` and ``SchemaProperties`` will be cached in the ``SchemaRegistryClient`` instance, so that subsequent requests for this schema do not need to go the service.
.. code-block:: python
import os
from azure.identity import DefaultAzureCredential
from azure.schemaregistry import SchemaRegistryClient
token_credential = DefaultAzureCredential()
endpoint = os.environ['SCHEMA_REGISTRY_ENDPOINT']
schema_group = ""
schema_name = ""
serialization_type = "Avro"
schema_content = """
{"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(endpoint=endpoint, credential=token_credential)
with schema_registry_client:
schema_properties = schema_registry_client.get_schema_id(schema_group, schema_name, serialization_type, schema_content)
schema_id = schema_properties.schema_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("you_end_point", 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.
Event Hubs and Avro Serializer
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
We provide `azure-schemaregistry-avroserializer `_ library as serializer
implementation to serialize/deserialize avro data integrated with ``azure-schemaregistry`` for automatic schema registration and retrieval.
It integrates nicely with the `EventHubs SDK `_.
For more information and sample codes, please refer to the `Azure Schema Registry Avro Serializer SDK `_.
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