From b27939483a91d5171e08b2998ed779b1f4f7dcb0 Mon Sep 17 00:00:00 2001 From: "Adam Ling (MSFT)" <47871814+yunhaoling@users.noreply.github.com> Date: Fri, 24 Apr 2020 14:49:15 -0700 Subject: [PATCH] [ServiceBus] Update for readme and sample (#11047) * tweak sample code * update according to comment * add aad sample in readme * Update sdk/servicebus/azure-servicebus/README.md Co-Authored-By: KieranBrantnerMagee Co-authored-by: KieranBrantnerMagee --- sdk/servicebus/azure-servicebus/README.md | 55 ++++++++++++++----- .../sample_code_servicebus_async.py | 6 +- .../sync_samples/sample_code_servicebus.py | 6 +- 3 files changed, 46 insertions(+), 21 deletions(-) diff --git a/sdk/servicebus/azure-servicebus/README.md b/sdk/servicebus/azure-servicebus/README.md index 9f155ee1967a..f0b0938ec8e3 100644 --- a/sdk/servicebus/azure-servicebus/README.md +++ b/sdk/servicebus/azure-servicebus/README.md @@ -7,7 +7,7 @@ publish/subscribe capabilities, and the ability to easily scale as your needs gr Use the Service Bus client library for Python to communicate between applications and services and implement asynchronous messaging patterns. -* Create Service Bus namespaces, queues, topics, and subscriptions, and modify their settings +* Create Service Bus namespaces, queues, topics, and subscriptions, and modify their settings. * Send and receive messages within your Service Bus channels. * Utilize message locks, sessions, and dead letter functionality to implement complex messaging patterns. @@ -29,7 +29,7 @@ pip install azure-servicebus --pre To use this package, you must have: * Azure subscription - [Create a free account][azure_sub] * Azure Service Bus - [Namespace and management credentials][service_bus_namespace] -* Python 2.7, 3.5, 3.6, 3.7 or 3.8 - [Install Python][python] +* Python 2.7, 3.5 or later - [Install Python][python] If you need an Azure service bus namespace, you can create it via the [Azure Portal][azure_namespace_creation]. @@ -43,19 +43,17 @@ az servicebus namespace create --resource-group --name NAMESPACE_NAME= -export SERVICE_BUS_CONN_STR=$(az servicebus namespace authorization-rule keys list --resource-group $RES_GROUP --namespace-name $NAMESPACE_NAME --query RootManageSharedAccessKey --output tsv) +export SERVICE_BUS_CONN_STR=$(az servicebus namespace authorization-rule keys list --resource-group $RES_GROUP --namespace-name $NAMESPACE_NAME --name RootManageSharedAccessKey --query primaryConnectionString --output tsv) ``` -#### Create client - Once you've populated the `SERVICE_BUS_CONN_STR` environment variable, you can create the `ServiceBusClient`. ```Python @@ -68,6 +66,28 @@ with ServiceBusClient.from_connection_string(connstr) as client: ... ``` +#### Create client using the azure-identity library: + +```python +import os +from azure.servicebus import ServiceBusClient +from azure.identity import DefaultAzureCredential + +credential = DefaultAzureCredential() + +FULLY_QUALIFIED_NAMESPACE = os.environ['SERVICE_BUS_FULLY_QUALIFIED_NAMESPACE'] +with ServiceBusClient(FULLY_QUALIFIED_NAMESPACE, credential): + ... +``` + +- This constructor takes the fully qualified namespace of your Service Bus instance and a credential that implements the +[TokenCredential][token_credential_interface] +protocol. There are implementations of the `TokenCredential` protocol available in the +[azure-identity package][pypi_azure_identity]. The fully qualified namespace is of the format ``. +- When using Azure Active Directory, your principal must be assigned a role which allows access to Service Bus, such as the +Azure Service Bus Data Owner role. For more information about using Azure Active Directory authorization with Service Bus, +please refer to [the associated documentation][servicebus_aad_authentication]. + Note: client can be initialized without a context manager, but must be manually closed via client.close() to not leak resources. ## Key concepts @@ -88,7 +108,7 @@ To interact with these resources, one should be familiar with the following SDK * [Sender](./azure/servicebus/_servicebus_sender.py): To send messages to a Queue or Topic, one would use the corresponding `get_queue_sender` or `get_topic_sender` method off of a `ServiceBusClient` instance as seen [here](./samples/sync_samples/send_queue.py). -* [Receiver](./azure/servicebus/_servicebus_receiver.py): To receive messages from a Queue or Subscription, one would use the corrosponding `get_queue_receiver` or `get_subscription_receiver` method off of a `ServiceBusClient` instance as seen [here](./samples/sync_samples/receive_queue.py). +* [Receiver](./azure/servicebus/_servicebus_receiver.py): To receive messages from a Queue or Subscription, one would use the corresponding `get_queue_receiver` or `get_subscription_receiver` method off of a `ServiceBusClient` instance as seen [here](./samples/sync_samples/receive_queue.py). * [Message](./azure/servicebus/_common/message.py): When sending, this is the type you will construct to contain your payload. When receiving, this is where you will access the payload and control how the message is "settled" (completed, dead-lettered, etc); these functions are only available on a received message. @@ -96,14 +116,14 @@ To interact with these resources, one should be familiar with the following SDK The following sections provide several code snippets covering some of the most common Service Bus tasks, including: -* [Send a message to a queue](#send-to-a-queue) -* [Receive a message from a queue](#receive-from-a-queue) -* [Defer a message on receipt](#defer-a-message) +* [Send a message to a queue](#send-a-message-to-a-queue) +* [Receive a message from a queue](#receive-a-message-from-a-queue) +* [Defer a message on receipt](#defer-a-message-on-receipt) To perform management tasks such as creating and deleting queues/topics/subscriptions, please utilize the azure-mgmt-servicebus library, available [here][servicebus_management_repository]. -### Send to a queue +### Send a message to a queue This example sends a message to a queue that is assumed to already exist, created via the Azure portal or az commands. @@ -121,7 +141,7 @@ with ServiceBusClient.from_connection_string(connstr) as client: sender.send(message) ``` -### Receive from a queue +### Receive a message from a queue To receive from a queue, you can either perform a one-off receive via "receiver.receive()" or receive persistently as follows: @@ -139,7 +159,7 @@ with ServiceBusClient.from_connection_string(connstr) as client: msg.complete() ``` -### Defer a message +### Defer a message on receipt When receiving from a queue, you have multiple actions you can take on the messages you receive. Where the prior example completes a message, permanently removing it from the queue and marking as complete, this example demonstrates how to defer the message, sending it back to the queue @@ -150,6 +170,7 @@ from azure.servicebus import ServiceBusClient import os connstr = os.environ['SERVICE_BUS_CONN_STR'] +queue_name = os.environ['SERVICE_BUS_QUEUE_NAME'] with ServiceBusClient.from_connection_string(connstr) as client: with client.get_queue_receiver(queue_name) as receiver: @@ -225,4 +246,8 @@ contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additio [topic_concept]: https://docs.microsoft.com/en-us/azure/service-bus-messaging/service-bus-messaging-overview#topics [subscription_concept]: https://docs.microsoft.com/en-us/azure/service-bus-messaging/service-bus-queues-topics-subscriptions#topics-and-subscriptions [azure_namespace_creation]: https://docs.microsoft.com/en-us/azure/service-bus-messaging/service-bus-create-namespace-portal -[servicebus_management_repository]: https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/servicebus/azure-mgmt-servicebus \ No newline at end of file +[servicebus_management_repository]: https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/servicebus/azure-mgmt-servicebus +[get_servicebus_conn_str]: https://docs.microsoft.com/en-us/azure/service-bus-messaging/service-bus-create-namespace-portal#get-the-connection-string +[servicebus_aad_authentication]: https://docs.microsoft.com/en-us/azure/service-bus-messaging/service-bus-authentication-and-authorization +[token_credential_interface]: ../../core/azure-core/azure/core/credentials.py +[pypi_azure_identity]: https://pypi.org/project/azure-identity/ diff --git a/sdk/servicebus/azure-servicebus/samples/async_samples/sample_code_servicebus_async.py b/sdk/servicebus/azure-servicebus/samples/async_samples/sample_code_servicebus_async.py index 30caeab27de8..90657b76e374 100644 --- a/sdk/servicebus/azure-servicebus/samples/async_samples/sample_code_servicebus_async.py +++ b/sdk/servicebus/azure-servicebus/samples/async_samples/sample_code_servicebus_async.py @@ -35,7 +35,7 @@ def example_create_servicebus_client_async(): # [START create_sb_client_async] import os from azure.servicebus.aio import ServiceBusClient, ServiceBusSharedKeyCredential - fully_qualified_namespace = os.environ['SERVICE_BUS_CONNECTION_STR'] + fully_qualified_namespace = os.environ['SERVICE_BUS_FULLY_QUALIFIED_NAMESPACE'] shared_access_policy = os.environ['SERVICE_BUS_SAS_POLICY'] shared_access_key = os.environ['SERVICE_BUS_SAS_KEY'] servicebus_client = ServiceBusClient( @@ -65,7 +65,7 @@ async def example_create_servicebus_sender_async(): # [START create_servicebus_sender_async] import os from azure.servicebus.aio import ServiceBusSender, ServiceBusSharedKeyCredential - fully_qualified_namespace = os.environ['SERVICE_BUS_CONNECTION_STR'] + fully_qualified_namespace = os.environ['SERVICE_BUS_FULLY_QUALIFIED_NAMESPACE'] shared_access_policy = os.environ['SERVICE_BUS_SAS_POLICY'] shared_access_key = os.environ['SERVICE_BUS_SAS_KEY'] queue_name = os.environ['SERVICE_BUS_QUEUE_NAME'] @@ -119,7 +119,7 @@ async def example_create_servicebus_receiver_async(): # [START create_servicebus_receiver_async] import os from azure.servicebus.aio import ServiceBusReceiver, ServiceBusSharedKeyCredential - fully_qualified_namespace = os.environ['SERVICE_BUS_CONNECTION_STR'] + fully_qualified_namespace = os.environ['SERVICE_BUS_FULLY_QUALIFIED_NAMESPACE'] shared_access_policy = os.environ['SERVICE_BUS_SAS_POLICY'] shared_access_key = os.environ['SERVICE_BUS_SAS_KEY'] queue_name = os.environ['SERVICE_BUS_QUEUE_NAME'] diff --git a/sdk/servicebus/azure-servicebus/samples/sync_samples/sample_code_servicebus.py b/sdk/servicebus/azure-servicebus/samples/sync_samples/sample_code_servicebus.py index adb73303ddad..55d689e4bf5a 100644 --- a/sdk/servicebus/azure-servicebus/samples/sync_samples/sample_code_servicebus.py +++ b/sdk/servicebus/azure-servicebus/samples/sync_samples/sample_code_servicebus.py @@ -32,7 +32,7 @@ def example_create_servicebus_client_sync(): # [START create_sb_client_sync] import os from azure.servicebus import ServiceBusClient, ServiceBusSharedKeyCredential - fully_qualified_namespace = os.environ['SERVICE_BUS_CONNECTION_STR'] + fully_qualified_namespace = os.environ['SERVICE_BUS_FULLY_QUALIFIED_NAMESPACE'] shared_access_policy = os.environ['SERVICE_BUS_SAS_POLICY'] shared_access_key = os.environ['SERVICE_BUS_SAS_KEY'] servicebus_client = ServiceBusClient( @@ -62,7 +62,7 @@ def example_create_servicebus_sender_sync(): # [START create_servicebus_sender_sync] import os from azure.servicebus import ServiceBusSender, ServiceBusSharedKeyCredential - fully_qualified_namespace = os.environ['SERVICE_BUS_CONNECTION_STR'] + fully_qualified_namespace = os.environ['SERVICE_BUS_FULLY_QUALIFIED_NAMESPACE'] shared_access_policy = os.environ['SERVICE_BUS_SAS_POLICY'] shared_access_key = os.environ['SERVICE_BUS_SAS_KEY'] queue_name = os.environ['SERVICE_BUS_QUEUE_NAME'] @@ -116,7 +116,7 @@ def example_create_servicebus_receiver_sync(): # [START create_servicebus_receiver_sync] import os from azure.servicebus import ServiceBusReceiver, ServiceBusSharedKeyCredential - fully_qualified_namespace = os.environ['SERVICE_BUS_CONNECTION_STR'] + fully_qualified_namespace = os.environ['SERVICE_BUS_FULLY_QUALIFIED_NAMESPACE'] shared_access_policy = os.environ['SERVICE_BUS_SAS_POLICY'] shared_access_key = os.environ['SERVICE_BUS_SAS_KEY'] queue_name = os.environ['SERVICE_BUS_QUEUE_NAME']