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][python-eg-src] | [Package (PyPI)][python-eg-pypi] | Package (Conda) | [API reference documentation][python-eg-ref-docs] | [Product documentation][python-eg-product-docs] | [Samples][python-eg-samples] | [Changelog][python-eg-changelog]

Disclaimer

This is a GA release of Azure Event Grid's EventGridPublisherClient and EventGridConsumerClient. EventGridPublisherClient supports send for Event Grid Basic and Event Grid Namespaces. EventGridConsumerClient supports receive, acknowledge , release, reject, and renew_locks operations for Event Grid Namespaces. Please refer to the samples for further information.

Getting started

Prerequisites

• Python 3.8 or later is required to use this package.
• You must have an [Azure subscription][azure_subscription] and at least one of the following:
  • an Event Grid Namespace resource. To create an Event Grid Namespace resource follow this tutorial.
  • an Event Grid Basic resource. To create an Event Grid Basic resource via the Azure portal follow this step-by-step tutorial. To create an Event Grid Basic resource via the Azure CLI follow this tutorial

Event Grid Resources

Azure Event Grid Namespaces supports both pull and push delivery. Azure Event Grid Basic supports only push delivery. More information on the two resource tiers can be found here.

Note: Azure Event Grid Namespaces only supports the Cloud Event v1.0 Schema.

Install the package

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

pip install azure-eventgrid

• An existing Event Grid Basic topic or domain, or Event Grid Namespace topic is required. You can create the resource using [Azure Portal][azure_portal_create_EG_resource] or [Azure CLI][azure_cli_link]

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

Create an Event Grid Namespace

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

Create an Event Grid Namespace Topic

az eventgrid namespace create topic --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. An endpoint and credential are necessary to instantiate the client object.

The default EventGridPublisherClient created is compatible with an Event Grid Basic Resource. To create an Event Grid Namespace compatible client, specify namespace_topic="YOUR_TOPIC_NAME" when instantiating the client.

# Event Grid Namespace client
client = EventGridPublisherClient(endpoint, credential, namespace_topic=YOUR_TOPIC_NAME)

# Event Grid Basic Client
client = EventGridPublisherClient(endpoint, credential)

EventGridConsumerClient only supports Event Grid Namespaces.

# Event Grid Namespace Client
client = EventGridConsumerClient(endpoint, credential, namespace_topic=YOUR_TOPIC_NAME, subscription=YOUR_SUBSCRIPTION_NAME)

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 a TokenCredential, the authenticated identity should have the "Event Grid Data Sender" role assigned. To receive events from a topic event subscription with a TokenCredential, the authenticated identity should have the "Event Grid Data Receiver" role assigned. To send and receive events to/from a topic with a TokenCredential, the authenticated identity should have the "Event Grid Data Contributor" role assigned.

More about RBAC setup can be found here.

With the azure-identity package, you can seamlessly authorize requests in both development and production environments. To learn more about Azure Active Directory, see the azure-identity README.

For example, you can use DefaultAzureCredential to construct a client which will authenticate using Azure Active Directory:

<!-- SNIPPET:sample_authentication.client_auth_with_token_cred -->

from azure.identity import DefaultAzureCredential
from azure.eventgrid import EventGridPublisherClient, EventGridEvent

default_az_credential = DefaultAzureCredential()
endpoint = os.environ["EVENTGRID_TOPIC_ENDPOINT"]
client = EventGridPublisherClient(endpoint, default_az_credential)

<!-- END SNIPPET -->

Looking up the endpoint

Event Grid Namespace

You can find the Namespace endpoint within the Event Grid Namespace resource on the Azure portal. This will look like: "<event-grid-namespace-name>.<namespace-location>.eventgrid.azure.net"

Event Grid Basic

You 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 AzureKeyCredential

To use an Access key as the credential parameter, pass the key as a string into an instance of [AzureKeyCredential][azure-key-credential].

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 the azure-mgmt-eventgrid library. A guide for getting access keys can be found here.

<!-- SNIPPET:sample_authentication.client_auth_with_key_cred -->

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

topic_key = os.environ["EVENTGRID_TOPIC_KEY"]
endpoint = os.environ["EVENTGRID_TOPIC_ENDPOINT"]

credential_key = AzureKeyCredential(topic_key)
client = EventGridPublisherClient(endpoint, credential_key)

<!-- END SNIPPET -->

Note: A Basic client may also be authenticated via SAS signature, using the AzureSasCredential. A sample demonstrating this, is available [here][python-eg-sample-send-using-sas] ([async_version][python-eg-sample-send-using-sas-async]).

Note: The generate_sas method can be used to generate a shared access signature. A sample demonstrating this can be seen [here][python-eg-generate-sas].

Key concepts

Event Grid Namespace

A namespace is a management container for other resources. It allows for grouping of related resources in order to manage them under one subscription.

Namespace Topic

A namespace topic is a topic that is created within an Event Grid namespace. The client publishes events to an HTTP namespace endpoint specifying a namespace topic where published events are logically contained. A namespace topic only supports the CloudEvent v1.0 schema.

Event Subscription

An event subscription is a configuration resource associated with a single topic.

Event Grid Basic

Topic

A topic is a channel within the Event Grid 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.

Domain

An event domain is 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, visit Event domain overview.

Event schemas

An event is 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.

System Topics

A system topic in 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 in azure.eventgrid.SystemEventNames. For complete list of recognizable system topics, visit System Topics.