diff --git a/sdk/eventhub/azure-eventhub/README.md b/sdk/eventhub/azure-eventhub/README.md index 024bd581cc3a..7b5e59df699d 100644 --- a/sdk/eventhub/azure-eventhub/README.md +++ b/sdk/eventhub/azure-eventhub/README.md @@ -39,43 +39,20 @@ $ pip install azure-eventhub Interaction with Event Hubs starts with an instance of EventHubConsumerClient or EventHubProducerClient class. You need either the host name, SAS/AAD credential and event hub name or a connection string to instantiate the client object. -**Create client from connection string:** +**[Create client from connection string:](https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/eventhub/azure-eventhub/samples/sync_samples/connection_string_authentication.py)** For the Event Hubs client library to interact with an Event Hub, the easiest means is to use a connection string, which is created automatically when creating an Event Hubs namespace. If you aren't familiar with shared access policies in Azure, you may wish to follow the step-by-step guide to [get an Event Hubs connection string](https://docs.microsoft.com/azure/event-hubs/event-hubs-get-connection-string). - -```python -from azure.eventhub import EventHubConsumerClient, EventHubProducerClient - -connection_str = '<< CONNECTION STRING FOR THE EVENT HUBS NAMESPACE >>' -consumer_group = '<< CONSUMER GROUP >>' -eventhub_name = '<< NAME OF THE EVENT HUB >>' -producer_client = EventHubProducerClient.from_connection_string(connection_str, eventhub_name=eventhub_name) -consumer_client = EventHubConsumerClient.from_connection_string(connection_str, consumer_group, eventhub_name=eventhub_name) - -``` - - The `from_connection_string` method takes the connection string of the form `Endpoint=sb://.servicebus.windows.net/;SharedAccessKeyName=;SharedAccessKey=` and entity name to your Event Hub instance. You can get the connection string from the [Azure portal](https://docs.microsoft.com/azure/event-hubs/event-hubs-get-connection-string#get-connection-string-from-the-portal). -**Create client using the azure-identity library:** +**[Create client using the azure-identity library:](https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/eventhub/azure-eventhub/samples/sync_samples/client_identity_authentication.py)** -```python -from azure.eventhub import EventHubConsumerClient -from azure.identity import DefaultAzureCredential +Alternately, one can use a Credential object to authenticate via AAD with the azure-identity package. -credential = DefaultAzureCredential() - -fully_qualified_namespace = '<< HOSTNAME OF THE EVENT HUB >>' -eventhub_name = '<< NAME OF THE EVENT HUB >>' -consumer_group = '<< CONSUMER GROUP >>' -consumer_client = EventHubConsumerClient(fully_qualified_namespace, eventhub_name, consumer_group, credential) - -``` - -- This constructor takes the host name and entity name of your Event Hub instance and credential that implements the +- This constructor demonstrated in the sample linked above takes the host name and entity name of your Event Hub instance and credential that implements the [TokenCredential](../../core/azure-core/azure/core/credentials.py) protocol. There are implementations of the `TokenCredential` protocol available in the [azure-identity package](https://pypi.org/project/azure-identity/). The host name is of the format ``. @@ -160,6 +137,9 @@ with client: ### Consume events from an Event Hub +There are multiple ways to consume events from an EventHub. To simply trigger a callback when an event is received, +the `EventHubConsumerClient.receive` method will be of use as follows: + ```python import logging from azure.eventhub import EventHubConsumerClient @@ -187,6 +167,9 @@ with client: ### Consume events from an Event Hub in batches +Whereas the above sample triggers the callback for each message as it is received, the following sample +triggers the callback on a batch of events, attempting to receive a number at a time. + ```python import logging from azure.eventhub import EventHubConsumerClient @@ -248,6 +231,9 @@ if __name__ == '__main__': ### Consume events from an Event Hub asynchronously +This SDK supports both synchronous and asyncio based code. To receive as demonstrated in the samples above, but within +aio, one would need the following: + ```python import logging import asyncio @@ -281,6 +267,9 @@ if __name__ == '__main__': ### Consume events from an Event Hub in batches asynchronously +All synchronous functions are supported in aio as well. As demonstrated above for synchronous batch receipt, one can accomplish +the same within asyncio as follows: + ```python import logging import asyncio diff --git a/sdk/eventhub/azure-eventhub/samples/README.md b/sdk/eventhub/azure-eventhub/samples/README.md index 3ba733f4add8..ac68f9b0ac71 100644 --- a/sdk/eventhub/azure-eventhub/samples/README.md +++ b/sdk/eventhub/azure-eventhub/samples/README.md @@ -55,13 +55,16 @@ Both [sync version](https://github.com/Azure/azure-sdk-for-python/tree/master/sd - [client_identity_authentication.py](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/eventhub/azure-eventhub/samples/sync_samples/client_identity_authentication.py) ([async version](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/eventhub/azure-eventhub/samples/async_samples/client_identity_authentication_async.py)) - Examples for authentication by Azure Active Directory: - Authenticating and creating the client utilizing the `azure.identity` library +- [connection_string_authentication.py](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/eventhub/azure-eventhub/samples/sync_samples/connection_string_authentication.py) ([async version](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/eventhub/azure-eventhub/samples/async_samples/connection_string_authentication_async.py)) - Examples for authentication by connection string: + - Authenticating and creating the client utilizing a connection string. + - [proxy.py](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/eventhub/azure-eventhub/samples/sync_samples/proxy.py) ([async version](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/eventhub/azure-eventhub/samples/async_samples/proxy_async.py)) - Examples to send and receive events behind a proxy: - Send and receive events behind a proxy - [iot_hub_connection_string_receive_async.py](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/eventhub/azure-eventhub/samples/async_samples/iot_hub_connection_string_receive_async.py) - Examples to receive events from an IoT Hub: - Convert an IoT Hub connection string to the built-in Event Hub endpoint and receive events from it -- [authenticate_with_sas_token.py] +- [authenticate_with_sas_token.py](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/eventhub/azure-eventhub/samples/sync_samples/authenticate_with_sas_token.py) - Utilize a SAS token to authenticate when creating an Event Hub client. ## Prerequisites diff --git a/sdk/eventhub/azure-eventhub/samples/async_samples/connection_string_authentication_async.py b/sdk/eventhub/azure-eventhub/samples/async_samples/connection_string_authentication_async.py new file mode 100644 index 000000000000..19dff480e74e --- /dev/null +++ b/sdk/eventhub/azure-eventhub/samples/async_samples/connection_string_authentication_async.py @@ -0,0 +1,24 @@ +#!/usr/bin/env python + +# -------------------------------------------------------------------------------------------- +# Copyright (c) Microsoft Corporation. All rights reserved. +# Licensed under the MIT License. See License.txt in the project root for license information. +# -------------------------------------------------------------------------------------------- +""" +An example to show authentication using a connection string obtained via the Azure Portal, or the Azure CLI toolkit. +""" + +import os +from azure.eventhub.aio import EventHubConsumerClient + +CONNECTION_STR = os.environ["EVENT_HUB_CONN_STR"] +EVENTHUB_NAME = os.environ['EVENT_HUB_NAME'] + +consumer_client = EventHubConsumerClient.from_connection_string( + conn_str=CONNECTION_STR, + consumer_group='$Default', + eventhub_name=EVENTHUB_NAME, +) + +async with consumer_client: + pass # consumer_client is now ready to be used. \ No newline at end of file diff --git a/sdk/eventhub/azure-eventhub/samples/sync_samples/client_identity_authentication.py b/sdk/eventhub/azure-eventhub/samples/sync_samples/client_identity_authentication.py index 01f4988ebd11..09e725637ed8 100644 --- a/sdk/eventhub/azure-eventhub/samples/sync_samples/client_identity_authentication.py +++ b/sdk/eventhub/azure-eventhub/samples/sync_samples/client_identity_authentication.py @@ -50,6 +50,7 @@ # For example user to be logged in can be specified by the environment variable AZURE_USERNAME, consumed via the ManagedIdentityCredential # Alternately, one can specify the AZURE_TENANT_ID, AZURE_CLIENT_ID, and AZURE_CLIENT_SECRET to use the EnvironmentCredentialClass. # The docs above specify all mechanisms which the defaultCredential internally support. +# # credential = DefaultAzureCredential() producer = EventHubProducerClient(fully_qualified_namespace=fully_qualified_namespace, diff --git a/sdk/eventhub/azure-eventhub/samples/sync_samples/connection_string_authentication.py b/sdk/eventhub/azure-eventhub/samples/sync_samples/connection_string_authentication.py new file mode 100644 index 000000000000..5fd8fd8a6dd9 --- /dev/null +++ b/sdk/eventhub/azure-eventhub/samples/sync_samples/connection_string_authentication.py @@ -0,0 +1,24 @@ +#!/usr/bin/env python + +# -------------------------------------------------------------------------------------------- +# Copyright (c) Microsoft Corporation. All rights reserved. +# Licensed under the MIT License. See License.txt in the project root for license information. +# -------------------------------------------------------------------------------------------- +""" +An example to show authentication using a connection string obtained via the Azure Portal, or the Azure CLI toolkit. +""" + +import os +from azure.eventhub import EventHubConsumerClient + +CONNECTION_STR = os.environ["EVENT_HUB_CONN_STR"] +EVENTHUB_NAME = os.environ['EVENT_HUB_NAME'] + +consumer_client = EventHubConsumerClient.from_connection_string( + conn_str=CONNECTION_STR, + consumer_group='$Default', + eventhub_name=EVENTHUB_NAME, +) + +with consumer_client: + pass # consumer_client is now ready to be used. \ No newline at end of file