{"id":2033,"date":"2022-05-19T12:33:15","date_gmt":"2022-05-19T19:33:15","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/azure-sdk\/?p=2033"},"modified":"2022-05-20T10:17:51","modified_gmt":"2022-05-20T17:17:51","slug":"nnouncing-the-stable-release-of-the-azure-schema-registry-client-libraries","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/azure-sdk\/nnouncing-the-stable-release-of-the-azure-schema-registry-client-libraries\/","title":{"rendered":"Announcing the stable release of the Azure Schema Registry client libraries"},"content":{"rendered":"

Azure Schema Registry is a feature of Azure Event Hubs. It provides a central repository for schemas for event-driven and messaging-centric applications, which often work with structured data payload in events or messages. Producers use a schema to serialize payload before publishing it to a broker like Azure Event Hubs; consumers get the payload from the broker and deserialize it using the same schema. For example, a commonly used schema format is Apache Avro<\/a>. Schema Registry allows producers and consumers to exchange data without having to manage and share the schema. Read more about this feature at Azure Schema Registry in Azure Event Hubs<\/a>.<\/p>\n

Azure Schema Registry client<\/h2>\n

The Azure SDK team previously released a stable version of the .NET<\/a>, Java<\/a>, JavaScript\/TypeScript<\/a>, and Python<\/a> library for the Schema Registry client. This client allows you to interact with Schema Registry and perform operations like registering and retrieving a schema. Check out the code samples below.<\/p>\n

.NET<\/h3>\n

Registering<\/h4>\n
string name = \"employeeSample\";\r\nSchemaFormat format = SchemaFormat.Avro;\r\n\/\/ Example schema's definition\r\nstring definition = @\"\r\n{\r\n   \"\"type\"\" : \"\"record\"\",\r\n    \"\"namespace\"\" : \"\"TestSchema\"\",\r\n    \"\"name\"\" : \"\"Employee\"\",\r\n    \"\"fields\"\" : [\r\n        { \"\"name\"\" : \"\"Name\"\" , \"\"type\"\" : \"\"string\"\" },\r\n        { \"\"name\"\" : \"\"Age\"\", \"\"type\"\" : \"\"int\"\" }\r\n    ]\r\n}\";\r\n\r\nResponse<SchemaProperties> schemaProperties = client.RegisterSchema(groupName, name, definition, format);<\/code><\/pre>\n
Retrieving<\/h4>\n
SchemaRegistrySchema schema = client.GetSchema(schemaId);\r\nstring definition = schema.Definition;<\/code><\/pre>\n
Java<\/h3>\n
Registering<\/h4>\n
String schemaContent = \"{n\"\r\n    + \"    \"type\" : \"record\",  n\"\r\n    + \"    \"namespace\" : \"SampleSchemaNameSpace\", n\"\r\n    + \"    \"name\" : \"Person\", n\"\r\n    + \"    \"fields\" : [n\"\r\n    + \"        { n\"\r\n    + \"            \"name\" : \"FirstName\" , \"type\" : \"string\" n\"\r\n    + \"        }, n\"\r\n    + \"        { n\"\r\n    + \"            \"name\" : \"LastName\", \"type\" : \"string\" n\"\r\n    + \"        }n\"\r\n    + \"    ]n\"\r\n    + \"}\";\r\nSchemaProperties schemaProperties = schemaRegistryClient.registerSchema(\"{schema-group}\", \"{schema-name}\",\r\n    schemaContent, SchemaFormat.AVRO);\r\n\r\nSystem.out.println(\"Registered schema: \" + schemaProperties.getId());<\/code><\/pre>\n
Retrieving<\/h4>\n
String schemaContent = \"{n\"\r\n    + \"    \"type\" : \"record\",  n\"\r\n    + \"    \"namespace\" : \"SampleSchemaNameSpace\", n\"\r\n    + \"    \"name\" : \"Person\", n\"\r\n    + \"    \"fields\" : [n\"\r\n    + \"        { n\"\r\n    + \"            \"name\" : \"FirstName\" , \"type\" : \"string\" n\"\r\n    + \"        }, n\"\r\n    + \"        { n\"\r\n    + \"            \"name\" : \"LastName\", \"type\" : \"string\" n\"\r\n    + \"        }n\"\r\n    + \"    ]n\"\r\n    + \"}\";\r\nSchemaProperties properties = schemaRegistryClient.getSchemaProperties(\"{schema-group}\", \"{schema-name}\",\r\n    schemaContent, SchemaFormat.AVRO);\r\n\r\nSystem.out.println(\"Retrieved schema id: \" + properties.getId());<\/code><\/pre>\n
JavaScript\/TypeScript<\/h3>\n
Registering<\/h4>\n
import { DefaultAzureCredential } from \"@azure\/identity\";\r\nimport { SchemaRegistryClient } from \"@azure\/schema-registry\";\r\n\r\nconst client = new SchemaRegistryClient(\"<fullyQualifiedNamespace>\", new DefaultAzureCredential());\r\n\r\nconst description = {\r\n  name: \"<name>\",\r\n  groupName: \"<group name>\",\r\n  format: \"<schema format>\",\r\n  definition: \"<schema definition>\"\r\n}\r\n\r\nconst registered = await client.registerSchema(description);\r\nconsole.log(registered.id);<\/code><\/pre>\n
Retrieving<\/h4>\n
import { DefaultAzureCredential } from \"@azure\/identity\";\r\nimport { SchemaRegistryClient } from \"@azure\/schema-registry\";\r\n\r\nconst client = new SchemaRegistryClient(\"<fullyQualifiedNamespace>\", new DefaultAzureCredential());\r\nconst foundSchema = await client.getSchema(\"<id>\");\r\nif (foundSchema) {\r\n  console.log(`Got schema definition=${foundSchema.definition}`);\r\n}<\/code><\/pre>\n
Python<\/h3>\n
Registering<\/h4>\n
import os\r\n\r\nfrom azure.identity import DefaultAzureCredential\r\nfrom azure.schemaregistry import SchemaRegistryClient\r\n\r\ntoken_credential = DefaultAzureCredential()\r\nfully_qualified_namespace = os.environ['SCHEMA_REGISTRY_FULLY_QUALIFIED_NAMESPACE']\r\ngroup_name = os.environ['SCHEMA_REGISTRY_GROUP']\r\nname = \"your-schema-name\"\r\nformat = \"Avro\"\r\ndefinition = \"\"\"\r\n{\"namespace\": \"example.avro\",\r\n \"type\": \"record\",\r\n \"name\": \"User\",\r\n \"fields\": [\r\n     {\"name\": \"name\", \"type\": \"string\"},\r\n     {\"name\": \"favorite_number\",  \"type\": [\"int\", \"null\"]},\r\n     {\"name\": \"favorite_color\", \"type\": [\"string\", \"null\"]}\r\n ]\r\n}\r\n\"\"\"\r\n\r\nschema_registry_client = SchemaRegistryClient(fully_qualified_namespace=fully_qualified_namespace, credential=token_credential)\r\nwith schema_registry_client:\r\n    schema_properties = schema_registry_client.register_schema(group_name, name, definition, format)\r\n    id = schema_properties.id<\/code><\/pre>\n
Retrieving<\/h4>\n
import os\r\n\r\nfrom azure.identity import DefaultAzureCredential\r\nfrom azure.schemaregistry import SchemaRegistryClient\r\n\r\ntoken_credential = DefaultAzureCredential()\r\nfully_qualified_namespace = os.environ['SCHEMA_REGISTRY_FULLY_QUALIFIED_NAMESPACE']\r\nschema_id = 'your-schema-id'\r\n\r\nschema_registry_client = SchemaRegistryClient(fully_qualified_namespace=fully_qualified_namespace, credential=token_credential)\r\nwith schema_registry_client:\r\n    schema = schema_registry_client.get_schema(schema_id)\r\n    definition = schema.definition\r\n    properties = schema.properties<\/code><\/pre>\n
Azure Schema Registry Avro serializer<\/h2>\n
Recently, a stable version of the Schema Registry Avro serializer library has also been released, available in these four languages: .NET<\/a>, Java<\/a>, JavaScript\/TypeScript<\/a>, and Python<\/a>. Combining the serializer and the client allows you to serialize and deserialize data into the Avro format. See the following code samples. The samples demonstrate how to use the serializer with event data from Azure Event Hubs and<\/em> with other data types of your choice.<\/p>\n
.NET<\/h3>\n
Serialize<\/h4>\n
var serializer = new SchemaRegistryAvroSerializer(client, groupName, new SchemaRegistryAvroSerializerOptions { AutoRegisterSchemas = true });\r\n\r\nvar employee = new Employee { Age = 42, Name = \"Caketown\" };\r\nEventData eventData = await serializer.SerializeAsync<EventData, Employee>(employee);\r\n\r\n\/\/ the schema Id will be included as a parameter of the content type\r\nConsole.WriteLine(eventData.ContentType);\r\n\r\n\/\/ the serialized Avro data will be stored in the EventBody\r\nConsole.WriteLine(eventData.EventBody);<\/code><\/pre>\n
Deserialize<\/h4>\n
\/\/ construct a consumer and consume the event from our event hub\r\nawait using var consumer = new EventHubConsumerClient(EventHubConsumerClient.DefaultConsumerGroupName, fullyQualifiedNamespace, eventHubName, credential);\r\nawait foreach (PartitionEvent receivedEvent in consumer.ReadEventsAsync())\r\n{\r\n    Employee deserialized = await serializer.DeserializeAsync<Employee>(eventData);\r\n    Console.WriteLine(deserialized.Age);\r\n    Console.WriteLine(deserialized.Name);\r\n    break;\r\n}<\/code><\/pre>\n
Java<\/h3>\n
Serialize<\/h4>\n
PlayingCard playingCard = new PlayingCard();\r\nplayingCard.setPlayingCardSuit(PlayingCardSuit.SPADES);\r\nplayingCard.setIsFaceCard(false);\r\nplayingCard.setCardValue(5);\r\n\r\nMessageContent message = serializer.serializeMessageData(playingCard,\r\n    TypeReference.createInstance(MessageContent.class));<\/code><\/pre>\n
Deserialize<\/h4>\n
SchemaRegistryApacheAvroSerializer serializer = createAvroSchemaRegistrySerializer();\r\nMessageContent message = getSchemaRegistryAvroMessage();\r\nPlayingCard playingCard = serializer.deserializeMessageData(message, TypeReference.createInstance(PlayingCard.class));<\/code><\/pre>\n
JavaScript\/TypeScript<\/h3>\n
Serialize<\/h4>\n
import { DefaultAzureCredential } from \"@azure\/identity\";\r\nimport { createEventDataAdapter } from \"@azure\/event-hubs\";\r\nimport { SchemaRegistryClient } from \"@azure\/schema-registry\";\r\nimport { AvroSerializer } from \"@azure\/schema-registry-avro\";\r\n\r\nconst client = new SchemaRegistryClient(\r\n  \"<fully qualified namespace>\",\r\n  new DefaultAzureCredential()\r\n);\r\nconst serializer = new AvroSerializer(client, {\r\n  groupName: \"<group>\",\r\n  messageAdapter: createEventDataAdapter(),\r\n});\r\n\r\n\/\/ Example Avro schema\r\nconst schema = JSON.stringify({\r\n  type: \"record\",\r\n  name: \"Rating\",\r\n  namespace: \"my.example\",\r\n  fields: [{ name: \"score\", type: \"int\" }],\r\n});\r\n\r\n\/\/ Example value that matches the Avro schema above\r\nconst value = { score: 42 };\r\n\r\n\/\/ Serialize value to a message\r\nconst message = await serializer.serialize(value, schema);<\/code><\/pre>\n
Deserialize<\/h4>\n
\/\/ Deserialize a message to value\r\nconst deserializedValue = await serializer.deserialize(message);<\/code><\/pre>\n
Python<\/h3>\n
Serialize<\/h4>\n
import os\r\nfrom azure.schemaregistry import SchemaRegistryClient\r\nfrom azure.schemaregistry.encoder.avroencoder import AvroEncoder\r\nfrom azure.identity import DefaultAzureCredential\r\nfrom azure.eventhub import EventData\r\n\r\ntoken_credential = DefaultAzureCredential()\r\nfully_qualified_namespace = os.environ['SCHEMAREGISTRY_FULLY_QUALIFIED_NAMESPACE']\r\ngroup_name = os.environ['SCHEMAREGISTRY_GROUP']\r\nname = \"example.avro.User\"\r\nformat = \"Avro\"\r\n\r\ndefinition = \"\"\"\r\n{\"namespace\": \"example.avro\",\r\n \"type\": \"record\",\r\n \"name\": \"User\",\r\n \"fields\": [\r\n     {\"name\": \"name\", \"type\": \"string\"},\r\n     {\"name\": \"favorite_number\",  \"type\": [\"int\", \"null\"]},\r\n     {\"name\": \"favorite_color\", \"type\": [\"string\", \"null\"]}\r\n ]\r\n}\"\"\"\r\n\r\nschema_registry_client = SchemaRegistryClient(fully_qualified_namespace, token_credential)\r\nschema_registry_client.register_schema(group_name, name, definition, format)\r\nencoder = AvroEncoder(client=schema_registry_client, group_name=group_name)\r\n\r\nwith encoder:\r\n    dict_content = {\"name\": \"Ben\", \"favorite_number\": 7, \"favorite_color\": \"red\"}\r\n    event_data = encoder.encode(dict_content, schema=definition, message_type=EventData)\r\n\r\n    # OR\r\n\r\n    message_content_dict = encoder.encode(dict_content, schema=definition)\r\n    event_data = EventData.from_message_content(message_content_dict[\"content\"], message_content_dict[\"content_type\"])<\/code><\/pre>\n
Deserialize<\/h4>\n
import os\r\nfrom azure.schemaregistry import SchemaRegistryClient\r\nfrom azure.schemaregistry.encoder.avroencoder import AvroEncoder\r\nfrom azure.identity import DefaultAzureCredential\r\n\r\ntoken_credential = DefaultAzureCredential()\r\nfully_qualified_namespace = os.environ['SCHEMAREGISTRY_FULLY_QUALIFIED_NAMESPACE']\r\ngroup_name = \"<your-group-name>\"\r\n\r\nschema_registry_client = SchemaRegistryClient(fully_qualified_namespace, token_credential)\r\nencoder = AvroEncoder(client=schema_registry_client)\r\n\r\nwith encoder:\r\n    # event_data is an EventData object with Avro encoded body\r\n    dict_content = {\"name\": \"Ben\", \"favorite_number\": 7, \"favorite_color\": \"red\"}\r\n    event_data = encoder.encode(dict_content, schema=definition, message_type=EventData)\r\n    decoded_content = encoder.decode(event_data)\r\n\r\n    # OR \r\n\r\n    encoded_bytes = b'<content_encoded_by_azure_schema_registry_avro_encoder>'\r\n    content_type = 'avro\/binary+<schema_id_of_corresponding_schema>'\r\n    content_dict = {\"content\": encoded_bytes, \"content_type\": content_type}\r\n    decoded_content = encoder.decode(content_dict)<\/code><\/pre>\n
The serializer also allows you to cache schemas to optimize performance.<\/p>\n
More samples<\/h3>\n
The following samples demonstrate how to use the Avro Serializer to create events with Avro-serialized payload then sending them to Azure Event Hubs. To prevent this blog post from getting too long, links to samples are given here instead of code:<\/p>\n