Package: azure-eventgrid
Azure Event Grid client library for PythonAzure Event Grid is a fully-managed intelligent event routing service that allows for uniform event consumption using a publish-subscribe model.Source code|Package (PyPI)|Package (Conda)|API reference documentation|Product documentation|Samples|ChangelogGetting startedPrerequisitesPython 3.7 or later is required to use this package.You must have anAzure subscriptionand an Event Grid Topic resource to use this package. Follow thisstep-by-step tutorialto register the Event Grid resource provider and create Event Grid topics using theAzure portal. There is asimilar tutorialusingAzure CLI.Install the packageInstall the Azure Event Grid client library for Python withpip:pipinstallazure-eventgridAn existing Event Grid topic or domain is required. You can create the resource usingAzure PortalorAzure CLIIf you use Azure CLI, replace<resource-group-name>and<resource-name>with your own unique names.Create an Event Grid Topicaz eventgrid topic --create --location <location> --resource-group <resource-group-name> --name <resource-name>Create an Event Grid Domainaz eventgrid domain --create --location <location> --resource-group <resource-group-name> --name <resource-name>Authenticate the clientIn order to interact with the Event Grid service, you will need to create an instance of a client.
Anendpointandcredentialare necessary to instantiate the client object.Using Azure Active Directory (AAD)Azure Event Grid provides integration with Azure Active Directory (Azure AD) for identity-based authentication of requests. With Azure AD, you can use role-based access control (RBAC) to grant access to your Azure Event Grid resources to users, groups, or applications.To send events to a topic or domain with aTokenCredential, the authenticated identity should have the "EventGrid Data Sender" role assigned.With theazure-identitypackage, you can seamlessly authorize requests in both development and production environments. To learn more about Azure Active Directory, see theazure-identityREADME.For example, you can useDefaultAzureCredentialto construct a client which will authenticate using Azure Active Directory:fromazure.identityimportDefaultAzureCredentialfromazure.eventgridimportEventGridPublisherClient,EventGridEventdefault_az_credential=DefaultAzureCredential()endpoint=os.environ["EVENTGRID_TOPIC_ENDPOINT"]client=EventGridPublisherClient(endpoint,default_az_credential)Looking up the endpointYou can find the topic endpoint within the Event Grid Topic resource on the Azure portal. This will look like:"https://<event-grid-topic-name>.<topic-location>.eventgrid.azure.net/api/events"Create the client with AzureKeyCredentialTo use an Access key as thecredentialparameter,
pass the key as a string into an instance ofAzureKeyCredential.Note:The Access Key may be found in the azure portal in the "Access Keys" menu of the Event Grid Topic resource.  They may also be obtained via the azure CLI, or theazure-mgmt-eventgridlibrary. A guide for getting access keys can be foundhere.importosfromazure.eventgridimportEventGridPublisherClientfromazure.core.credentialsimportAzureKeyCredentialtopic_key=os.environ["EVENTGRID_TOPIC_KEY"]endpoint=os.environ["EVENTGRID_TOPIC_ENDPOINT"]credential_key=AzureKeyCredential(topic_key)client=EventGridPublisherClient(endpoint,credential_key)Note:A client may also be authenticated via SAS signature, using theAzureSasCredential. A sample demonstrating this, is availablehere(async_version).Note:Thegenerate_sasmethod can be used to generate a shared access signature. A sample demonstrating this can be seenhere.Key conceptsTopicAtopicis a channel within the EventGrid service to send events. The event schema that a topic accepts is decided at topic creation time. If events of a schema type are sent to a topic that requires a different schema type, errors will be raised.DomainAn eventdomainis a management tool for large numbers of Event Grid topics related to the same application. They allow you to publish events to thousands of topics. Domains also give you authorization and authentication control over each topic. For more information, visitEvent domain overview.When you create an event domain, a publishing endpoint for this domain is made available to you. This process is similar to creating an Event Grid Topic. The only difference is that, when publishing to a domain, you must specify the topic within the domain that you'd like the event to be delivered to.Event schemasAneventis the smallest amount of information that fully describes something that happened in the system. When a custom topic or domain is created, you must specify the schema that will be used when publishing events.Event Grid supports multiple schemas for encoding events.Event Grid schemaWhile you may configure your topic to use acustom schema, it is more common to use the already-defined Event Grid schema. See the specifications and requirementshere.CloudEvents v1.0 schemaAnother option is to use the CloudEvents v1.0 schema.CloudEventsis a Cloud Native Computing Foundation project which produces a specification for describing event data in a common way. The service summary of CloudEvents can be foundhere.EventGridPublisherClientEventGridPublisherClientprovides operations to send event data to a topic hostname specified during client initialization.Regardless of the schema that your topic or domain is configured to use,EventGridPublisherClientwill be used to publish events to it. Use thesendmethod publishing events.The following formats of events are allowed to be sent:A list or a single instance of strongly typed EventGridEvents.A dict representation of a serialized EventGridEvent object.A list or a single instance of strongly typed CloudEvents.A dict representation of a serialized CloudEvent object.A dict representation of any Custom Schema.Please have a look at thesamplesfor detailed examples.Note:It is important to know if your topic supports CloudEvents or EventGridEvents before publishing. If you send to a topic that does not support the schema of the event you are sending, send() will throw an exception.System TopicsAsystem topicin Event Grid represents one or more events published by Azure services such as Azure Storage or Azure Event Hubs. For example, a system topic may represent all blob events or only blob creation and blob deletion events published for a specific storage account.The names of the various event types for the system events published to Azure Event Grid are available inazure.eventgrid.SystemEventNames.
For complete list of recognizable system topics, visitSystem Topics.For more information about the key concepts on Event Grid, seeConcepts in Azure Event Grid.Event Grid on Kubernetes with Azure ArcEvent Grid on Kubernetes with Azure Arc is an offering that allows you to run Event Grid on your own Kubernetes cluster. This capability is enabled by the use of Azure Arc enabled Kubernetes. Through Azure Arc enabled Kubernetes, a supported Kubernetes cluster connects to Azure. Once connected, you are able to install Event Grid on it. Learn more about ithere.Support for CNCF Cloud EventsStarting with v4.7.0, this package also supports publishing a CNCF cloud event fromhttps://pypi.org/project/cloudevents/. You would be able to pass a CloudEvent object from this library to thesendAPI.fromcloudevents.httpimportCloudEventevent=CloudEvent(...)client.send(event)ExamplesThe following sections provide several code snippets covering some of the most common Event Grid tasks, including:Send an Event Grid EventSend a Cloud EventSend Multiple EventsSend events as DictionariesConsume a payload from storage queueConsume from ServiceBusSend an Event Grid EventThis example publishes an Event Grid event.importosfromazure.core.credentialsimportAzureKeyCredentialfromazure.eventgridimportEventGridPublisherClient,EventGridEventkey=os.environ["EG_ACCESS_KEY"]endpoint=os.environ["EG_TOPIC_HOSTNAME"]event=EventGridEvent(data={"team":"azure-sdk"},subject="Door1",event_type="Azure.Sdk.Demo",data_version="2.0")credential=AzureKeyCredential(key)client=EventGridPublisherClient(endpoint,credential)client.send(event)Send a Cloud EventThis example publishes a Cloud event.importosfromazure.core.credentialsimportAzureKeyCredentialfromazure.core.messagingimportCloudEventfromazure.eventgridimportEventGridPublisherClientkey=os.environ["CLOUD_ACCESS_KEY"]endpoint=os.environ["CLOUD_TOPIC_HOSTNAME"]event=CloudEvent(type="Azure.Sdk.Sample",source="https://egsample.dev/sampleevent",data={"team":"azure-sdk"})credential=AzureKeyCredential(key)client=EventGridPublisherClient(endpoint,credential)client.send(event)Send Multiple eventsIt is possible to send events as a batch when sending multiple events to a topic or a domain. This example sends a list of CloudEvents using the send method.WARNING:When sending a list of multiple events at one time, iterating over and sending each event will not result in optimal performance. For best performance, it is highly recommended to send a list of events.importosfromazure.core.credentialsimportAzureKeyCredentialfromazure.core.messagingimportCloudEventfromazure.eventgridimportEventGridPublisherClientkey=os.environ["CLOUD_ACCESS_KEY"]endpoint=os.environ["CLOUD_TOPIC_HOSTNAME"]event0=CloudEvent(type="Azure.Sdk.Sample",source="https://egsample.dev/sampleevent",data={"team":"azure-sdk"})event1=CloudEvent(type="Azure.Sdk.Sample",source="https://egsample.dev/sampleevent",data={"team2":"azure-eventgrid"})events=[event0,event1]credential=AzureKeyCredential(key)client=EventGridPublisherClient(endpoint,credential)client.send(events)Send events as dictionariesA dict representation of respective serialized models can also be used to publish CloudEvent(s) or EventGridEvent(s) apart from the strongly typed objects.Use a dict-like representation to send to a topic with custom schema as shown below.importosimportuuidimportdatetimeasdtfrommsrest.serializationimportUTCfromazure.core.credentialsimportAzureKeyCredentialfromazure.eventgridimportEventGridPublisherClientkey=os.environ["CUSTOM_SCHEMA_ACCESS_KEY"]endpoint=os.environ["CUSTOM_SCHEMA_TOPIC_HOSTNAME"]event=custom_schema_event={"customSubject":"sample","customEventType":"sample.event","customDataVersion":"2.0","customId":uuid.uuid4(),"customEventTime":dt.datetime.now(UTC()).isoformat(),"customData":"sample data"}credential=AzureKeyCredential(key)client=EventGridPublisherClient(endpoint,credential)client.send(event)Consume from storage queueThis example consumes a message received from storage queue and deserializes it to a CloudEvent object.fromazure.core.messagingimportCloudEventfromazure.storage.queueimportQueueServiceClient,BinaryBase64DecodePolicyimportosimportjson# all types of CloudEvents below produce same DeserializedEventconnection_str=os.environ['STORAGE_QUEUE_CONN_STR']queue_name=os.environ['STORAGE_QUEUE_NAME']withQueueServiceClient.from_connection_string(connection_str)asqsc:payload=qsc.get_queue_client(queue=queue_name,message_decode_policy=BinaryBase64DecodePolicy()).peek_messages()## deserialize payload into a list of typed Eventsevents=[CloudEvent.from_dict(json.loads(msg.content))formsginpayload]Consume from servicebusThis example consumes a payload message received from ServiceBus and deserializes it to an EventGridEvent object.fromazure.eventgridimportEventGridEventfromazure.servicebusimportServiceBusClientimportosimportjson# all types of EventGridEvents below produce same DeserializedEventconnection_str=os.environ['SERVICE_BUS_CONN_STR']queue_name=os.environ['SERVICE_BUS_QUEUE_NAME']withServiceBusClient.from_connection_string(connection_str)assb_client:payload=sb_client.get_queue_receiver(queue_name).receive_messages()## deserialize payload into a list of typed Eventsevents=[EventGridEvent.from_dict(json.loads(next(msg.body).decode('utf-8')))formsginpayload]Distributed Tracing with EventGridYou can use OpenTelemetry for Python as usual with EventGrid since it's compatible with azure-core tracing integration.Here is an example of using OpenTelemetry to trace sending a CloudEvent.First, set OpenTelemetry as enabled tracing plugin for EventGrid.fromazure.core.settingsimportsettingsfromazure.core.tracing.ext.opentelemetry_spanimportOpenTelemetrySpansettings.tracing_implementation=OpenTelemetrySpanRegular open telemetry usage from here. SeeOpenTelemetryfor details.
This example uses a simple console exporter to export the traces. Any exporter can be used here includingazure-monitor-opentelemetry-exporter,jaeger,zipkinetc.fromopentelemetryimporttracefromopentelemetry.sdk.traceimportTracerProviderfromopentelemetry.sdk.trace.exportimportConsoleSpanExporterfromopentelemetry.sdk.trace.exportimportSimpleSpanProcessor# this requires opentelemetry >= 1.0.0# Simple console exporterexporter=ConsoleSpanExporter()trace.set_tracer_provider(TracerProvider())tracer=trace.get_tracer(__name__)trace.get_tracer_provider().add_span_processor(SimpleSpanProcessor(exporter))Once thetracerandexporterare set, please follow the example below to start collecting traces while using thesendmethod from theEventGridPublisherClientto send a CloudEvent object.importosfromazure.eventgridimportEventGridPublisherClientfromazure.core.messagingimportCloudEventfromazure.core.credentialsimportAzureKeyCredentialhostname=os.environ['CLOUD_TOPIC_HOSTNAME']key=AzureKeyCredential(os.environ['CLOUD_ACCESS_KEY'])cloud_event=CloudEvent(source='demo',type='sdk.demo',data={'test':'hello'},)withtracer.start_as_current_span(name="MyApplication"):client=EventGridPublisherClient(hostname,key)client.send(cloud_event)TroubleshootingEnableazure.eventgridlogger to collect traces from the library.GeneralEvent Grid client library will raise exceptions defined inAzure Core.LoggingThis library uses the standardlogginglibrary for logging.
Basic information about HTTP sessions (URLs, headers, etc.) is logged at INFO
level.Optional ConfigurationOptional keyword arguments can be passed in at the client and per-operation level.
The azure-corereference documentationdescribes available configurations for retries, logging, transport protocols, and more.Next stepsThe following section provides several code snippets illustrating common patterns used in the Event Grid Python API.More sample codeThese code samples show common champion scenario operations with the Azure Event Grid client library.Generate Shared Access Signature:sample_generate_sas.pyAuthenticate the client:sample_authentication.py(async_version)Publish events to a topic using SAS:sample_publish_events_to_a_topic_using_sas_credential_async.py(async_version)Publish Event Grid Events to a topic:sample_publish_eg_events_to_a_topic.py(async_version)Publish EventGrid Events to a domain topic:sample_publish_eg_events_to_a_domain_topic.py(async_version)Publish a Cloud Event:sample_publish_events_using_cloud_events_1.0_schema.py(async_version)Publish a Custom Schema:sample_publish_custom_schema_to_a_topic.py(async_version)The following samples cover publishing and consumingdictrepresentations of EventGridEvents and CloudEvents.Publish EventGridEvent as dict like representation:sample_publish_eg_event_using_dict.py(async_version)Publish CloudEvent as dict like representation:sample_publish_cloud_event_using_dict.py(async_version)Consume a Custom Payload of raw cloudevent data:sample_consume_custom_payload.pyMore samples can be foundhere.More samples related to the send scenario can be seenhere.To see more samples related to consuming a payload from different messaging services as a typed object, please visitConsume SamplesAdditional documentationFor more extensive documentation on Azure Event Grid, see theEvent Grid documentationon docs.microsoft.com.ContributingThis 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, visitcla.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 theMicrosoft Open Source Code of Conduct. For more information see theCode of Conduct FAQor contactopencode@microsoft.comwith any additional questions or comments.Release History4.17.0 (2024-02-08)This version and all future versions will require Python 3.8+.Features AddedAdded new enums values toSystemEventNamesrelated to Azure Storage and Azure VMware Solution.4.16.0 (2023-11-08)Features AddedAdded new enum values toSystemEventnamesrelated to Azure Resource Notifications.4.15.0 (2023-10-12)Features AddedAdded new enum values toSystemEventNamesrelated to Azure Communication Services and Azure Resource Notifications.4.14.0 (2023-09-13)Features AddedAdded new enum values toSystemEventNamesrelated to Azure App Configuration and Azure EventGrid.4.13.0 (2023-06-08)Features AddedAdded new enum values toSystemEventNamesrelated to Azure Container Services.4.12.0b1 (2023-05-22)Features AddedAdded a new EventGridClient that supportspublish_cloud_events,receive_cloud_events,acknowledge_cloud_events,release_cloud_events, andreject_cloud_eventsoperations.Added new models to support these new operations on EventGridClient.4.11.0 (2023-05-09)Features AddedAdded new enum values toSystemEventNamesrelated to Storage Tasks, Azure Communication Services and Azure HealthcareApis.4.10.0 (2023-04-11)Features AddedAdded new enum values toSystemEventNamesrelated to Azure Communication Services, DataBox and ApiManagementGateway APIs.Bugs FixedSystemEventNamesenums for APIManagement were incorrectly capitalized, changedApitoAPI.Other ChangesRemovedmsrestdependency andsixdependencyAddedisodatedependency4.9.1 (2022-11-08)This version and all future versions will require Python 3.7+.Features AddedAdded new enum values toSystemEventNamesrelated to health care APIs.4.9.0 (2022-07-05)Features AddedAdded support for publishing events to a channel.4.9.0b1 (2022-04-07)Features AddedAdded support for publishing events to a channel.4.8.0 (2022-04-06)This version and all future versions will require Python 3.6+. Python 2.7 is no longer supported.Features AddedAdded new enum values toSystemEventNamesrelated to health care APIs.4.7.1 (2021-11-18)Bugs FixedThesendAPI will raise on exceptions.4.7.0 (2021-11-09)Features AddedAdded support for publishing native CNCF cloudevents (https://pypi.org/project/cloudevents/).4.6.0 (2021-10-05)Features AddedAdded new enum values toSystemEvents.4.5.0 (2021-08-10)Features AddedAdded a new enum valueMicrosoft.ContainerService.NewKubernetesVersionAvailabletoSystemEvents.Added afrom_jsonmethod which now accepts storage QueueMessage, eventhub's EventData or ServiceBusMessage or simply json bytes to return anEventGridEvent4.4.0 (2021-07-19)Bumpedmsrestdependency to0.6.21to align with mgmt package.Features AddedEventGridPublisherClientnow supports Azure Active Directory (AAD) for authentication.4.3.0 (2021-06-09)New FeaturesAdded new event names related to blob inventory to theSystemEventNamesenum.Bug FixesReplaced theServiceBusDeadletterMessagesAvailableWithNoListenerEventNamewith the right value.4.2.0 (2021-05-12)New FeaturesAdded new event names to theSystemEventNamesenum.4.1.1 (2021-04-07)Bug FixesImproved therepronEventGridEventto show more meaningful text.4.1.0 (2021-03-23)New FeaturesAdded new SystemEventNamesAcsChatThreadParticipantRemovedEventName,AcsChatThreadParticipantAddedEventNameandAcsRecordingFileStatusUpdatedEventName.4.0.0 (2021-03-09)Note:This is the first stable release of our efforts to create a user-friendly and Pythonic client library for Azure EventGrid. Users migrating fromv1.xare advised to view themigration guide.New Featuresazure-eventgridpackage now supportsazure.core.messaging.CloudEventwhich honors the CNCF CloudEvent spec.azure.eventgrid.SystemEventNamescan be used to get the event model type mapping for system events.Implements theEventGridPublisherClientfor the publish flow for EventGrid Events, CloudEvents and Custom schema events.Breaking Changesazure.eventgrid.modelsnamespace along with all the models in it are now removed.:JSON documentation on the events is available here:https://docs.microsoft.com/azure/event-grid/system-topicsazure.eventgrid.SystemEventNamesprovides the list of available events name for easy switching.azure.eventgrid.event_grid_client.EventGridClientis now removed in favor ofazure.eventgrid.EventGridPublisherClient.azure.eventgrid.event_grid_client.EventGridClientConfigurationis now removed.2.0.0 (2021-03-09)Disclaimer:v2.0.0 is functionally equivalent to v4.0.0. Users are advised to use v4.0.0 instead of this.Breaking Changes~azure.eventgrid.CloudEventis now removed in favor of~azure.core.messaging.CloudEvent.All theSystemEventNamesrelated to Azure Communication Service starting withACS****are renamed toAcs***to honor pascal case.FeaturesAdded support for two newSystemEvents-ServiceBusDeadletterMessagesAvailablePeriodicNotificationsEventDataandServiceBusActiveMessagesAvailablePeriodicNotificationsEventData2.0.0b5 (2021-02-10)Breaking ChangesEventGridSharedAccessSignatureCredentialis deprecated in favor ofAzureSasCredential.azure.eventgrid.modelsnamespace along with all the models in it are now removed.azure.eventgrid.SystemEventNamescan be used to get the event model type mapping.topic_hostnameis renamed toendpointin theEventGridPublisherClient.azure.eventgrid.generate_shared_access_signaturemethod is now renamed togenerate_sas.EventGridConsumeris now removed. Please see the samples to see how events can be deserialized.CustomEventmodel is removed. Dictionaries must be used to send a custom schema.Bug FixesEventGridEventhas two additional required positional parameters namely,dataanddata_version.EventGridPublisherClientnow appropriately throws aValueErrorif an invalid credential is passed during initialization.2.0.0b4 (2020-11-11)Bug FixesTypeErroris raised when bytes are passed to anEventGridEvent.2.0.0b3 (2020-10-05)FeatureAdded support for Keyvault Event TypesAdded distributed tracing support for CloudEvents2.0.0b2 (2020-09-24)FeaturesAdded support for Azure Communication Services event types.2.0.0b1 (2020-09-08)FeaturesVersion (2.0.0b1) is the first preview of our efforts to create a user-friendly and Pythonic client library for Azure EventGrid.
For more information about this, and preview releases of other Azure SDK libraries, please visithttps://azure.github.io/azure-sdk/releases/latest/python.html.Added Support forCloudEvents.Implements theEventGridPublisherClientfor the publish flow for EventGrid Events, CloudEvents and CustomEvents.Implements theEventGridConsumerfor the consume flow of the events.1.3.0 (2019-05-20)Event Schemas for new event types from IotHub, Media Services,
Container Registry, Maps, and AppConfiguration services.1.2.0 (2018-08-28)Event Schemas for new events (IotHub DeviceConnected and
DeviceDisconnected events, Resource events related to actions), and
breaking changes to the schema for IotHub DeviceCreated event and
IotHub DeviceDeleted event.1.1.0 (2018-05-24)Event Schemas for EventGrid subscription validation event, Azure
Media events, and ServiceBus events.1.0.0 (2018-04-26)General Breaking changesThis version uses a next-generation code generator thatmightintroduce breaking changes.Model signatures now use only keyword-argument syntax. All
positional arguments must be re-written as keyword-arguments. To
keep auto-completion in most cases, models are now generated for
Python 2 and Python 3. Python 3 uses the "*" syntax for
keyword-only arguments.Enum types now use the "str" mixin (class AzureEnum(str, Enum)) to
improve the behavior when unrecognized enum values are encountered.
While this is not a breaking change, the distinctions are important,
and are documented here:https://docs.python.org/3/library/enum.html#othersAt a glance:"is" should not be used at all."format" will return the string value, where "%s" string
formatting will returnNameOfEnum.stringvalue. Format syntax
should be preferred.New Long Running Operation:Return type changes frommsrestazure.azure_operation.AzureOperationPollertomsrest.polling.LROPoller. External API is the same.Return type is nowalwaysamsrest.polling.LROPoller,
regardless of the optional parameters used.The behavior has changed when usingraw=True. Instead of
returning the initial call result asClientRawResponse,
without polling, now this returns an LROPoller. After polling,
the final resource will be returned as aClientRawResponse.Newpollingparameter. The default behavior isPolling=Truewhich will poll using ARM algorithm. WhenPolling=False, the response of the initial call will be
returned without polling.pollingparameter accepts instances of subclasses ofmsrest.polling.PollingMethod.add_done_callbackwill no longer raise if called after
polling is finished, but will instead execute the callback right
away.FeaturesClient class can be used as a context manager to keep the underlying
HTTP session open for performanceSupport for consuming Azure Container Registry events and Azure IoT
Hub events published to Event Grid.0.1.0 (2018-01-30)Initial Release