Share via

Azure Event Grid System Events for Java

This package contains strongly typed model classes for Azure Event Grid System Events and utilities for deserializing system event data.

Overview

This library provides:

  • System Event Data Models: Strongly typed classes for all Azure Event Grid system events (e.g., StorageBlobCreatedEventData, AppConfigurationKeyValueDeletedEventData)
  • Event Type Constants: Pre-defined constants for all system event types via SystemEventNames
  • Event Mappings: Automatic mapping between event type strings and their corresponding data model classes

System events are published by Azure services when resources change state. For example, when a blob is created in Azure Storage, a Microsoft.Storage.BlobCreated event is published with StorageBlobCreatedEventData as the event data.

Sources | API Reference Documentation | Product Documentation | Samples

Getting started

Prerequisites

Adding the package to your product

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-messaging-eventgrid-systemevents</artifactId>
    <version>1.0.0</version>
</dependency>

Note: This package contains only the system event models and utilities. To send events, you'll also need the main Event Grid SDK:

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-messaging-eventgrid</artifactId>
    <version>4.30.0</version>
</dependency>

For Event Grid namespaces: If you're working with Event Grid namespaces, consider using the EventGrid namespaces package for namespace-specific functionality:

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-messaging-eventgrid-namespaces</artifactId>
    <version>1.1.3</version>
</dependency>

Key concepts

System Events: Events automatically published by Azure services when resource state changes occur.

Event Data Models: Strongly typed classes in the com.azure.messaging.eventgrid.systemevents.models package that represent the data payload of system events.

SystemEventNames: Utility class containing constants for all system event types and mappings to their corresponding data model classes.

Examples

Available System Events

This package provides models for system events from many Azure services, including:

  • Azure App Configuration: AppConfigurationKeyValueDeletedEventData, AppConfigurationKeyValueModifiedEventData
  • Azure Blob Storage: StorageBlobCreatedEventData, StorageBlobDeletedEventData
  • Azure Communication Services: AcsCallStartedEventData, AcsChatMessageReceivedEventData
  • Azure Container Registry: ContainerRegistryImagePushedEventData, ContainerRegistryImageDeletedEventData
  • Azure Event Hubs: EventHubCaptureFileCreatedEventData
  • Azure IoT Hub: IotHubDeviceCreatedEventData, IotHubDeviceTelemetryEventData
  • Azure Service Bus: ServiceBusActiveMessagesAvailableWithNoListenersEventData
  • See the Azure services that support system events for additional supported services. For a complete list, see the com.azure.messaging.eventgrid.systemevents.models package.

Working with System Events

1. Get System Event Type Constants

// Access predefined event type constants
String blobCreatedEventType = SystemEventNames.STORAGE_BLOB_CREATED;
String keyVaultSecretExpiredEventType = SystemEventNames.KEY_VAULT_SECRET_NEAR_EXPIRY;

2. Look up Event Data Model Class

// Find the appropriate model class for an event type
Class<?> eventDataClass = SystemEventNames.getSystemEventMappings().get(eventType);
if (eventDataClass != null) {
    System.out.println("Event data should be deserialized to: " + eventDataClass.getSimpleName());
}

3. Deserialize System Event Data

// Assuming you have an EventGridEvent from the main EventGrid SDK and the event is Storage Blob Created event
StorageBlobCreatedEventData storageBlobCreatedEventData
    = StorageBlobCreatedEventData.fromJson(JsonProviders.createReader("payload"));
BinaryData data = storageBlobCreatedEventData.getStorageDiagnostics().get("batchId");

System.out.println("Blob URL: " + storageBlobCreatedEventData.getUrl());
System.out.println("Blob size: " + storageBlobCreatedEventData.getContentLength());
System.out.println("Content type: " + storageBlobCreatedEventData.getContentType());

Troubleshooting

Common Issues

  • Missing Event Type: If SystemEventNames.getSystemEventMappings().get(eventType) returns null, the event type might be:

    • A custom event (not a system event)
    • A new system event is not yet supported in this version
    • Misspelled event type string

  • Deserialization Errors: Ensure you're using the correct model class for the event type. Use SystemEventNames mappings to get the right class.

Enable client logging

Azure SDKs for Java offer a consistent logging story to help aid in troubleshooting application errors and expedite their resolution. The logs produced will capture the flow of an application before reaching the terminal state to help locate the root issue. View the logging wiki for guidance about enabling logging.

Next steps

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a [Contributor License Agreement (CLA)][cla] declaring that you have the right to, and actually do, grant us the rights to use your contribution.

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). 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][coc]. For more information, see the [Code of Conduct FAQ][coc_faq] or contact [opencode@microsoft.com][coc_contact] with any additional questions or comments.