Announcing the new Azure Event Grid Client Libraries

Josh Love

March 19th, 20210 0

We are pleased to announce that the new Azure Event Grid libraries have reached general availability (GA). Version 4 of the Azure Event Grid packages have now been released (.NET, Java, Python and JavaScript/TypeScript), following the new Azure SDK guidelines. These guidelines provide consistency across all Azure SDK client libraries while also allowing each language to follow the idioms for their respective languages.

This library is the result of months of development, design discussions, feedback, and observing developers in user studies as they worked with Azure Event Grid. In this release, we’ve simplified the API surface, added distributed tracing, and added support for publishing using the CloudEvent schema and custom event schemas.

Cross Service SDK improvements

The new Event Grid client libraries allow Event Grid developers to take advantage of the cross-service improvements made to the Azure development experience, such as:

  • Core credential types to share a single authentication approach between clients
  • A unified logging and diagnostics pipeline offering a common view of the activities across each of the client libraries

In particular, the new Event Grid libraries use the core AzureKeyCredential type for authenticating the service client.

C#

EventGridPublisherClient client = new EventGridPublisherClient(
    new Uri("<endpoint>"),
    new AzureKeyCredential("<access-key>"));

Java

EventGridPublisherClient<EventGridEvent> eventGridEventClient = new EventGridPublisherClientBuilder()
    .endpoint("<endpoint>")
    .credential(new AzureKeyCredential("<access-key>"))
    .buildEventGridEventPublisherClient();

JavaScript

const { EventGridPublisherClient, AzureKeyCredential } = require("@azure/eventgrid");
const client = new EventGridPublisherClient("<endpoint>", "EventGrid", new AzureKeyCredential("<access-key>"));

Python

from azure.core.credentials import AzureKeyCredential
from azure.eventgrid import EventGridPublisherClient
credential = AzureKeyCredential("<access-key>")
client = EventGridPublisherClient("<endpoint>", credential)

New features

In addition to the cross-service improvements, Version 4 of the library includes several new features specific to Event Grid: – Support for publishing events using the CloudEvent schema to topics which are configured to use the CloudEvent V1 schema.

C#

var cloudEvent = new CloudEvent(
    source: "/cloudevents/example/source",
    type: "Example.EventType",
    data: new MyDataModel() { A = 5, B = true });

await client.SendEventAsync(cloudEvent);

Java

// Initialize the client for use with the cloud event schema
EventGridPublisherClient<CloudEvent> publisherClient = new EventGridPublisherClientBuilder()
    .endpoint("<endpoint>")
    .credential(new AzureKeyCredential("<access-key>"))
    .buildCloudEventPublisherClient();

User newUser = new User("John2", "James");
CloudEvent cloudEventModel = new CloudEvent("https://com.example.myapp", "User.Created.Object",
BinaryData.fromObject(newUser), CloudEventDataFormat.JSON, "application/json");
publisherClient.sendEvents(cloudEventModel);

JavaScript

// Initialize the client for use with the cloud event schema
const client = new EventGridPublisherClient(
  "<endpoint>",
  "CloudEvent",
  new AzureKeyCredential("<access-key>")
);

// Send an event to the Event Grid Service, using the Cloud Event schema.
// A random ID will be generated for this event, since one is not provided.
await client.send([
  {
    type: "com.example.cloudevent",
    source: "/azure/sdk/eventgrid/samples/sendEventSample",
    data: {
      message: "this is a sample event"
    }
  }
]);

Python

client.send([
    CloudEvent(
        type="Contoso.Items.ItemReceived",
        source="/contoso/items",
        data={
            "itemSku": "Contoso Item SKU #1"
        },
        subject="Door1"
    )
])
  • Support for publishing events using a custom schema to topics which are configured to use a custom schema. Custom schema events are useful in situations where you are dealing with events that do not match either the CloudEvent or the Event Grid schema, but you would still like to use Azure Event Grid. In both Java and .NET, custom events are represented with the BinaryData type. This is a common type used across several messaging libraries in Java and .NET, including Service Bus, Event Hubs, and Storage Queues.

C#

var customModel = new CustomModel
{
    DataVersion = "1.0",
    EventTime = Recording.Now,
    EventType = "Microsoft.MockPublisher.TestEvent",
    Id = Recording.Random.NewGuid().ToString(),
    Subject = "Subject",
    Topic = "Topic",
    Data = new MyDataModel() { A = 5, B = true }
};
var customEvent = new BinaryData(customModel);
await client.SendEventAsync(cloudEvent);

Java

// Initialize the client for use with a custom event schema
EventGridPublisherClient<BinaryData> customEventClient = new EventGridPublisherClientBuilder()
    .endpoint("<endpoint>")
    .credential(new AzureKeyCredential("<access-key>"))
    .buildCustomEventPublisherClient();

List<BinaryData> events = new ArrayList<>();
events.add(BinaryData.fromObject(new HashMap<String, String>() {
    {
        put("id", UUID.randomUUID().toString());
        put("time", OffsetDateTime.now().toString());
        put("subject", "Test");
        put("foo", "bar");
        put("type", "Microsoft.MockPublisher.TestEvent");
        put("data", "example data");
        put("dataVersion", "0.1");
    }
}));
customEventClient.sendEvents(events);

JavaScript

// Initialize the client for use with a custom event schema
const client = new EventGridPublisherClient(
  "<endpoint>",
  "Custom",
  new AzureKeyCredential("<access-key>")
);

await client.send([
  {
    eventType: "Azure.Sdk.SampleEvent",
    subject: "Event Subject",
    dataVersion: "1.0",
    data: {
      hello: "world"
    }
  }
]);

Python

custom_schema_event = {
    "customSubject": "sample",
    "customEventType": "sample.event",
    "customDataVersion": "2.0",
    "customId": uuid.uuid4(),
    "customEventTime": dt.datetime.now(UTC()).isoformat(),
    "customData": "sample data"
}

client.send(custom_schema_event)
  • Helpers to construct SAS (shared access signature) tokens which can be used to provide time-based access for publishing to an Event Grid topic. Generally, the workflow would be that one application would generate the shared string and hand off the string to another application that would consume the string.

C#

Generate the SAS:

var builder = new EventGridSasBuilder(new Uri(topicEndpoint), DateTimeOffset.Now.AddHours(1));
var keyCredential = new AzureKeyCredential(topicAccessKey);
string sasToken = builder.GenerateSas(keyCredential);

Here is how it would be used from the consumer’s perspective using the core AzureSasCredential type:

var sasCredential = new AzureSasCredential(sasToken);
EventGridPublisherClient client = new EventGridPublisherClient(
    new Uri(topicEndpoint),
    sasCredential);

Java

Generate the SAS:

String sasToken = EventGridPublisherClient.generateSas(
    topicEndpoint,
    new AzureKeyCredential(topicAccessKey),
    OffsetDateTime.now().plusMinutes(20));

Here is how it would be used from the consumer’s perspective using the core AzureSasCredential type:

EventGridPublisherClient<CloudEvent> publisherClient = new EventGridPublisherClientBuilder()
    .endpoint(topicEndpoint)
    .credential(new AzureSasCredential(sasToken))
    .buildCloudEventPublisherClient();

JavaScript

Generate the SAS:

// Create a SAS Token which expires on 2020-01-01 at Midnight.
const token = generateSharedAccessSignature(
  "<endpoint>",
  new AzureKeyCredential("<API key>"),
  new Date("2020-01-01T00:00:00")
);

Here is how it would be used from the consumer’s perspective using the core AzureSasCredential type:

const client = new EventGridPublisherClient(
  "<endpoint>",
  "<endpoint schema>",
  new AzureSASCredential("<SAS Token>")
);

Python

Generate the SAS:

signature = generate_sas(endpoint, topic_key, expiration_date_utc)

Here is how it would be used from the consumer’s perspective using the core AzureSasCredential type:

credential = AzureSasCredential(signature)
client = EventGridPublisherClient(endpoint, credential)
  • Bridge library providing integration with the CNCF CloudEvents package for .NET The CloudNative.CloudEvents package is the official Cloud Native Computing Foundation SDK for CloudEvents. We have introduced a bridge library that contains extension methods for the EventGridPublisherClient that can be used to send CloudNative CloudEvents:
var cloudEvent =
    new CloudEvent(
        type: "record",
        source: new Uri("http://www.contoso.com"))
        {
            Data = new MyDataModel() { A = 5, B = true }
        };

await client.SendCloudEventAsync(cloudEvent);

Conclusion

Azure Event Grid is one of Azure’s core messaging offerings, that can greatly simplify your application. The latest set of packages are our effort to make integrating Event Grid quick and painless, allowing you to quickly jumpstart your applications and get running.

For more information about each language from this article please see the following:

Azure SDK Blog Contributions

Thank you for reading this Azure SDK blog post! We hope that you learned something new and welcome you to share this post. We are open to Azure SDK blog contributions. Please contact us at azsdkblog@microsoft.com with your topic and we’ll get you set up as a guest blogger.

Josh Love Senior Software Engineer, Azure SDK

Read next

0 comments

Discussion is closed.

Feedback usabilla icon