Azure Event Grid client library for Python

Azure 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) | API reference documentation| Product documentation | Samples| Changelog

Getting started

Prerequisites

• Python 2.7, or 3.5 or later is required to use this package.
• You must have an Azure subscription and an Event Grid Topic resource to use this package.

Install the package

Install the Azure Event Grid client library for Python with pip:

pip install azure-eventgrid

• An existing Event Grid topic or domain is required. You can create the resource using Azure Portal or Azure CLI

If you use Azure CLI, replace <resource-group-name> and <resource-name> with your own unique names.

Create an Event Grid Topic

az eventgrid topic --create --location <location> --resource-group <resource-group-name> --name <resource-name>

Create an Event Grid Domain

az eventgrid domain --create --location <location> --resource-group <resource-group-name> --name <resource-name>

Authenticate the client

In order to interact with the Event Grid service, you will need to create an instance of a client. A topic_hostname and credential are necessary to instantiate the client object.

Looking up the endpoint

You can find the endpoint and the hostname on the Azure portal.

Create the client with AzureKeyCredential

To use an API key as the credential parameter, pass the key as a string into an instance of AzureKeyCredential.

from azure.core.credentials import AzureKeyCredential
from azure.eventgrid import EventGridPublisherClient

topic_hostname = "https://<name>.<region>.eventgrid.azure.net"
credential = AzureKeyCredential("<api_key>")
eg_publisher_client = EventGridPublisherClient(topic_hostname, credential)

Key concepts

Information about the key concepts on Event Grid, see Concepts in Azure Event Grid

EventGridPublisherClient

EventGridPublisherClient provides operations to send event data to topic hostname specified during client initialization. Either a list or a single instance of CloudEvent/EventGridEvent/CustomEvent can be sent.

EventGridConsumer

EventGridConsumer is used to desrialize an event received.

Examples

The following sections provide several code snippets covering some of the most common Event Grid tasks, including:

• Send an Event Grid Event
• Send a Cloud Event
• Consume an eventgrid Event
• Consume a cloud Event

Send an Event Grid Event

This example publishes an Event Grid event.

import os
from azure.core.credentials import AzureKeyCredential
from azure.eventgrid import EventGridPublisherClient, EventGridEvent

key = os.environ["EG_ACCESS_KEY"]
topic_hostname = os.environ["EG_TOPIC_HOSTNAME"]

event = EventGridEvent(
    subject="Door1",
    data={"team": "azure-sdk"},
    event_type="Azure.Sdk.Demo",
    data_version="2.0"
)

credential = AzureKeyCredential(key)
client = EventGridPublisherClient(topic_hostname, credential)

client.send(event)

Send a Cloud Event

This example publishes a Cloud event.

import os
from azure.core.credentials import AzureKeyCredential
from azure.eventgrid import EventGridPublisherClient, CloudEvent

key = os.environ["CLOUD_ACCESS_KEY"]
topic_hostname = 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(topic_hostname, credential)

client.send(event)

Consume an Event Grid Event

This example demonstrates consuming and deserializing an eventgrid event.

import os
from azure.eventgrid import EventGridConsumer

consumer = EventGridConsumer()

eg_storage_dict = {
    "id":"bbab625-dc56-4b22-abeb-afcc72e5290c",
    "subject":"/blobServices/default/containers/oc2d2817345i200097container/blobs/oc2d2817345i20002296blob",
    "data":{
        "api":"PutBlockList",
    },
    "eventType":"Microsoft.Storage.BlobCreated",
    "dataVersion":"2.0",
    "metadataVersion":"1",
    "eventTime":"2020-08-07T02:28:23.867525Z",
    "topic":"/subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.EventGrid/topics/eventgridegsub"
}

deserialized_event = consumer.decode_eventgrid_event(eg_storage_dict)

# both allow access to raw properties as strings
time_string = deserialized_event.event_time

Consume a Cloud Event

This example demonstrates consuming and deserializing a cloud event.

import os
from azure.eventgrid import EventGridConsumer

consumer = EventGridConsumer()

cloud_storage_dict = {
    "id":"a0517898-9fa4-4e70-b4a3-afda1dd68672",
    "source":"/subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.Storage/storageAccounts/{storage-account}",
    "data":{
        "api":"PutBlockList",
    },
    "type":"Microsoft.Storage.BlobCreated",
    "time":"2020-08-07T01:11:49.765846Z",
    "specversion":"1.0"
}

deserialized_event = consumer.decode_cloud_event(cloud_storage_dict)

# both allow access to raw properties as strings
time_string = deserialized_event.time

Troubleshooting

• Enable azure.eventgrid logger to collect traces from the library.

General

Event Grid client library will raise exceptions defined in Azure Core.

Logging

This library uses the standard logging library for logging. Basic information about HTTP sessions (URLs, headers, etc.) is logged at INFO level.

Optional Configuration

Optional keyword arguments can be passed in at the client and per-operation level. The azure-core reference documentation describes available configurations for retries, logging, transport protocols, and more.

Next steps

The following section provides several code snippets illustrating common patterns used in the Event Grid Python API.

More sample code

These code samples show common champion scenario operations with the Azure Event Grid client library.

• Publish Custom Events to a topic: cs1_publish_custom_events_to_a_topic.py
• Publish Custom events to a domain topic: cs2_publish_custom_events_to_a_domain_topic.py
• Deserialize a System Event: cs3_consume_system_events.py
• Deserialize a Custom Event: cs4_consume_custom_events.py
• Deserialize a Cloud Event: cs5_consume_events_using_cloud_events_1.0_schema.py
• Publish a Cloud Event: cs6_publish_events_using_cloud_events_1.0_schema.py

More samples can be found here.

Additional documentation

For more extensive documentation on Azure Event Grid, see the Event Grid documentation on docs.microsoft.com.

Contributing

This 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, visit cla.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 the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Release History

2.0.0b3 (2020-10-05)

Feature

• Added support for Keyvault Event Types
• Added distributed tracing support for CloudEvents

2.0.0b2 (2020-09-24)

Features

• Added support for Azure Communication Services event types.

2.0.0b1 (2020-09-08)

Features

• Version (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 visit https://azure.github.io/azure-sdk/releases/latest/python.html.
• Added Support for CloudEvents.
• Implements the EventGridPublisherClient for the publish flow for EventGrid Events, CloudEvents and CustomEvents.
• Implements the EventGridConsumer for 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 changes

This version uses a next-generation code generator that might introduce 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#others At a glance:
  • "is" should not be used at all.
  • "format" will return the string value, where "%s" string formatting will return NameOfEnum.stringvalue. Format syntax should be prefered.
• New Long Running Operation:
  • Return type changes from msrestazure.azure_operation.AzureOperationPoller to msrest.polling.LROPoller. External API is the same.
  • Return type is now always a msrest.polling.LROPoller, regardless of the optional parameters used.
  • The behavior has changed when using raw=True. Instead of returning the initial call result as ClientRawResponse, without polling, now this returns an LROPoller. After polling, the final resource will be returned as a ClientRawResponse.
  • New polling parameter. The default behavior is Polling=True which will poll using ARM algorithm. When Polling=False, the response of the initial call will be returned without polling.
  • polling parameter accepts instances of subclasses of msrest.polling.PollingMethod.
  • add_done_callback will no longer raise if called after polling is finished, but will instead execute the callback right away.

Features

• Client class can be used as a context manager to keep the underlying HTTP session open for performance
• Support for consuming Azure Container Registry events and Azure IoT Hub events published to Event Grid.

0.1.0 (2018-01-30)

• Initial Release