|
| 1 | +--- |
| 2 | +title: |
| 3 | +keywords: Azure, java, SDK, API, azure-messaging-eventgrid-systemevents, eventgrid |
| 4 | +ms.date: 06/28/2025 |
| 5 | +ms.topic: reference |
| 6 | +ms.devlang: java |
| 7 | +ms.service: eventgrid |
| 8 | +--- |
| 9 | +# Azure Event Grid System Events for Java |
| 10 | + |
| 11 | +This package contains strongly typed model classes for Azure Event Grid System Events and utilities for deserializing system event data. |
| 12 | + |
| 13 | +## Overview |
| 14 | + |
| 15 | +This library provides: |
| 16 | +- **System Event Data Models**: Strongly typed classes for all Azure Event Grid system events (e.g., |
| 17 | + `StorageBlobCreatedEventData`, `AppConfigurationKeyValueDeletedEventData`) |
| 18 | +- **Event Type Constants**: Pre-defined constants for all system event types via `SystemEventNames` |
| 19 | +- **Event Mappings**: Automatic mapping between event type strings and their corresponding data model classes |
| 20 | + |
| 21 | +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. |
| 22 | + |
| 23 | +[Sources][sources] | |
| 24 | +[API Reference Documentation][javadocs] | |
| 25 | +[Product Documentation][service_docs] | |
| 26 | +[Samples][samples] |
| 27 | + |
| 28 | +## Getting started |
| 29 | + |
| 30 | +### Prerequisites |
| 31 | + |
| 32 | +- [Java Development Kit (JDK)][jdk] with version 8 or above |
| 33 | + |
| 34 | +### Adding the package to your product |
| 35 | + |
| 36 | +[//]: # ({x-version-update-start;com.azure:azure-messaging-eventgrid-systemevents;current}) |
| 37 | +```xml |
| 38 | +<dependency> |
| 39 | + <groupId>com.azure</groupId> |
| 40 | + <artifactId>azure-messaging-eventgrid-systemevents</artifactId> |
| 41 | + <version>1.0.0</version> |
| 42 | +</dependency> |
| 43 | +``` |
| 44 | +[//]: # ({x-version-update-end}) |
| 45 | + |
| 46 | +**Note**: This package contains only the system event models and utilities. To send events, you'll also need the |
| 47 | +main [Event Grid SDK][azure-messaging-eventgrid]: |
| 48 | + |
| 49 | +[//]: # ({x-version-update-start;com.azure:azure-messaging-eventgrid;dependency}) |
| 50 | +```xml |
| 51 | +<dependency> |
| 52 | + <groupId>com.azure</groupId> |
| 53 | + <artifactId>azure-messaging-eventgrid</artifactId> |
| 54 | + <version>4.30.0</version> |
| 55 | +</dependency> |
| 56 | +``` |
| 57 | +[//]: # ({x-version-update-end}) |
| 58 | + |
| 59 | +**For Event Grid namespaces**: If you're working with Event Grid namespaces, consider using the [EventGrid namespaces |
| 60 | +package](https://github.com/Azure/azure-sdk-for-java/tree/azure-messaging-eventgrid-systemevents_1.0.0/sdk/eventgrid/azure-messaging-eventgrid-namespaces) for |
| 61 | +namespace-specific functionality: |
| 62 | + |
| 63 | +[//]: # ({x-version-update-start;com.azure:azure-messaging-eventgrid-namespaces;dependency}) |
| 64 | + |
| 65 | +```xml |
| 66 | +<dependency> |
| 67 | + <groupId>com.azure</groupId> |
| 68 | + <artifactId>azure-messaging-eventgrid-namespaces</artifactId> |
| 69 | + <version>1.1.3</version> |
| 70 | +</dependency> |
| 71 | +``` |
| 72 | +[//]: # ({x-version-update-end}) |
| 73 | + |
| 74 | +## Key concepts |
| 75 | + |
| 76 | +**System Events**: Events automatically published by Azure services when resource state changes occur. |
| 77 | + |
| 78 | +**Event Data Models**: Strongly typed classes in the `com.azure.messaging.eventgrid.systemevents.models` package |
| 79 | +that represent the `data` payload of system events. |
| 80 | + |
| 81 | +**SystemEventNames**: Utility class containing constants for all system event types and mappings to their corresponding data model classes. |
| 82 | + |
| 83 | +## Examples |
| 84 | + |
| 85 | +### Available System Events |
| 86 | + |
| 87 | +This package provides models for system events from many Azure services, including: |
| 88 | + |
| 89 | +- **Azure App Configuration**: `AppConfigurationKeyValueDeletedEventData`, `AppConfigurationKeyValueModifiedEventData` |
| 90 | +- **Azure Blob Storage**: `StorageBlobCreatedEventData`, `StorageBlobDeletedEventData` |
| 91 | +- **Azure Communication Services**: `AcsCallStartedEventData`, `AcsChatMessageReceivedEventData` |
| 92 | +- **Azure Container Registry**: `ContainerRegistryImagePushedEventData`, `ContainerRegistryImageDeletedEventData` |
| 93 | +- **Azure Event Hubs**: `EventHubCaptureFileCreatedEventData` |
| 94 | +- **Azure IoT Hub**: `IotHubDeviceCreatedEventData`, `IotHubDeviceTelemetryEventData` |
| 95 | +- **Azure Service Bus**: `ServiceBusActiveMessagesAvailableWithNoListenersEventData` |
| 96 | +- See the [Azure services that support system events](https://learn.microsoft.com/azure/event-grid/system-topics#azure-services-that-support-system-topics) for additional supported services. |
| 97 | +For a complete list, see the `com.azure.messaging.eventgrid.systemevents.models` package. |
| 98 | + |
| 99 | +### Working with System Events |
| 100 | + |
| 101 | +#### 1. Get System Event Type Constants |
| 102 | + |
| 103 | +```java readme-sample-getSystemEventTypeConstants |
| 104 | +// Access predefined event type constants |
| 105 | +String blobCreatedEventType = SystemEventNames.STORAGE_BLOB_CREATED; |
| 106 | +String keyVaultSecretExpiredEventType = SystemEventNames.KEY_VAULT_SECRET_NEAR_EXPIRY; |
| 107 | +``` |
| 108 | + |
| 109 | +#### 2. Look up Event Data Model Class |
| 110 | + |
| 111 | +```java readme-sample-lookupSystemEventClass |
| 112 | +// Find the appropriate model class for an event type |
| 113 | +Class<?> eventDataClass = SystemEventNames.getSystemEventMappings().get(eventType); |
| 114 | +if (eventDataClass != null) { |
| 115 | + System.out.println("Event data should be deserialized to: " + eventDataClass.getSimpleName()); |
| 116 | +} |
| 117 | +``` |
| 118 | + |
| 119 | +#### 3. Deserialize System Event Data |
| 120 | + |
| 121 | +```java readme-sample-deserializeSystemEventData |
| 122 | +// Assuming you have an EventGridEvent from the main EventGrid SDK and the event is Storage Blob Created event |
| 123 | +StorageBlobCreatedEventData storageBlobCreatedEventData |
| 124 | + = StorageBlobCreatedEventData.fromJson(JsonProviders.createReader("payload")); |
| 125 | +BinaryData data = storageBlobCreatedEventData.getStorageDiagnostics().get("batchId"); |
| 126 | + |
| 127 | +System.out.println("Blob URL: " + storageBlobCreatedEventData.getUrl()); |
| 128 | +System.out.println("Blob size: " + storageBlobCreatedEventData.getContentLength()); |
| 129 | +System.out.println("Content type: " + storageBlobCreatedEventData.getContentType()); |
| 130 | + |
| 131 | +``` |
| 132 | + |
| 133 | +## Troubleshooting |
| 134 | + |
| 135 | +### Common Issues |
| 136 | + |
| 137 | +- **Missing Event Type**: If `SystemEventNames.getSystemEventMappings().get(eventType)` returns null, the event type might be: |
| 138 | + - A custom event (not a system event) |
| 139 | + - A new system event is not yet supported in this version |
| 140 | + - Misspelled event type string |
| 141 | + |
| 142 | +- **Deserialization Errors**: Ensure you're using the correct model class for the event type. Use `SystemEventNames` mappings to get the right class. |
| 143 | + |
| 144 | +### Enable client logging |
| 145 | +Azure SDKs for Java offer a consistent logging story to help aid in troubleshooting application errors and expedite |
| 146 | +their resolution. The logs produced will capture the flow of an application before reaching the terminal state to help |
| 147 | +locate the root issue. View the [logging][logging] wiki for guidance about enabling logging. |
| 148 | + |
| 149 | +## Next steps |
| 150 | + |
| 151 | +- Explore the [`azure-messaging-eventgrid-systemevents`][sources] package for available event data models |
| 152 | +- Explore the [`azure-messaging-eventgrid`][azure-messaging-eventgrid] package for sending events |
| 153 | +- Learn about [Azure Event Grid System Topics](https://learn.microsoft.com/azure/event-grid/system-topics) |
| 154 | +- Review [Event Grid event schemas](https://learn.microsoft.com/azure/event-grid/event-schema) for different Azure services |
| 155 | +- Check out [Event Grid samples][samples] for complete examples |
| 156 | +- Additional Event Grid tutorials can be found [here][service_docs] |
| 157 | + |
| 158 | +## Contributing |
| 159 | + |
| 160 | +This project welcomes contributions and suggestions. Most contributions require you to agree to a |
| 161 | +[Contributor License Agreement (CLA)][cla] declaring that you have the right to, and actually do, grant us the rights |
| 162 | +to use your contribution. |
| 163 | + |
| 164 | +When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate |
| 165 | +the PR appropriately (e.g., label, comment). Follow the instructions provided by the bot. You will only need to |
| 166 | +do this once across all repos using our CLA. |
| 167 | + |
| 168 | +This project has adopted the [Microsoft Open Source Code of Conduct][coc]. For more information, see the |
| 169 | +[Code of Conduct FAQ ][coc_faq] or contact [[email protected]][coc_contact] with any additional questions or comments. |
| 170 | + |
| 171 | +<!-- LINKS --> |
| 172 | +[product_documentation]: https://learn.microsoft.com/azure/event-grid/ |
| 173 | +[docs]: https://azure.github.io/azure-sdk-for-java/ |
| 174 | +[jdk]: https://learn.microsoft.com/azure/developer/java/fundamentals/ |
| 175 | +[logging]: https://github.com/Azure/azure-sdk-for-java/wiki/Logging-in-Azure-SDK |
| 176 | +[azure-messaging-eventgrid]: https://github.com/Azure/azure-sdk-for-java/tree/azure-messaging-eventgrid-systemevents_1.0.0/sdk/eventgrid/azure-messaging-eventgrid |
| 177 | +[service_docs]: https://learn.microsoft.com/azure/event-grid/ |
| 178 | +[samples]: https://github.com/Azure/azure-sdk-for-java/blob/azure-messaging-eventgrid-systemevents_1.0.0/sdk/eventgrid/azure-messaging-eventgrid/src/samples/java/com/azure/messaging/eventgrid |
| 179 | +[sources]: https://github.com/Azure/azure-sdk-for-java/tree/azure-messaging-eventgrid-systemevents_1.0.0/sdk/eventgrid/azure-messaging-eventgrid-systemevents/src |
| 180 | +[javadocs]: https://github.com/Azure/azure-sdk-for-java/tree/azure-messaging-eventgrid-systemevents_1.0.0/sdk/eventgrid/azure-messaging-eventgrid-systemevents/src |
| 181 | + |
0 commit comments