From ae0a90255db67c27c083784c71ae9e34e9ec058c Mon Sep 17 00:00:00 2001 From: KieranBrantnerMagee Date: Wed, 2 Sep 2020 15:12:16 -0700 Subject: [PATCH] Make doc-owner recommended revisions to eventhub readme and samples. (#13518) Move auth samples into samples and link from readme rather than line. Add snippets to the top of samples lacking any verbiage. Whitespace improvements in client auth sample Explicit samples for connstr auth to link from new terse readme auth section. --- sdk/eventhub/azure-eventhub/README.md | 43 +++++++------------ sdk/eventhub/azure-eventhub/samples/README.md | 5 ++- .../connection_string_authentication_async.py | 24 +++++++++++ .../client_identity_authentication.py | 1 + .../connection_string_authentication.py | 24 +++++++++++ 5 files changed, 69 insertions(+), 28 deletions(-) create mode 100644 sdk/eventhub/azure-eventhub/samples/async_samples/connection_string_authentication_async.py create mode 100644 sdk/eventhub/azure-eventhub/samples/sync_samples/connection_string_authentication.py 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