diff --git a/sdk/servicebus/azure-servicebus/CHANGELOG.md b/sdk/servicebus/azure-servicebus/CHANGELOG.md index e28ce2ec1403..e28649f91794 100644 --- a/sdk/servicebus/azure-servicebus/CHANGELOG.md +++ b/sdk/servicebus/azure-servicebus/CHANGELOG.md @@ -1,5 +1,13 @@ # Release History +## 1.0.0b1 (2020-3-20) + +**Features** + +* Simplified API and set of clients +* Support for Azure Identity +* Support Sending and Receiving on queues + ## 0.50.2 (2019-12-9) **Features** diff --git a/sdk/servicebus/azure-servicebus/README.md b/sdk/servicebus/azure-servicebus/README.md index cd4e0f53c593..99bc2294f68e 100644 --- a/sdk/servicebus/azure-servicebus/README.md +++ b/sdk/servicebus/azure-servicebus/README.md @@ -1,78 +1,170 @@ -# Microsoft Azure Service Bus SDK for Python +# Azure Service Bus client library for Python -This is the Microsoft Azure Service Bus Client Library. -This package has been tested with Python 2.7, 3.4, 3.5, 3.6 and 3.7. +Azure Service Bus is a high performance cloud-managed messaging service for providing real-time and fault-tolerant communication between distributed senders and receivers. -Microsoft Azure Service Bus supports a set of cloud-based, message-oriented middleware technologies including reliable message queuing and durable publish/subscribe messaging. +Service Bus provides multiple mechanisms for asynchronous highly reliable communication, such as structured first-in-first-out messaging, +publish/subscribe capabilities, and the ability to easily scale as your needs grow. -* [SDK source code](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/servicebus/azure-servicebus) -* [SDK reference documentation](https://docs.microsoft.com/python/api/overview/azure/servicebus/client?view=azure-python) -* [Service Bus documentation](https://docs.microsoft.com/azure/service-bus-messaging/) +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 +* Send and receive messages within your Service Bus channels. +* Utilize message locks, sessions, and dead letter functionality to implement complex messaging patterns. -## What's new in v0.50.2? +[Source code](./) | [Package (PyPi)](pypi) | [API reference documentation](api_docs) | [Product documentation](product_docs) | [Samples](./samples) | [Changelog][./CHANGELOG.md] -As of version 0.50.2 a new AMQP-based API is available for sending and receiving messages. This update involves **breaking changes**. -Please read [Migration from 0.21.1 to 0.50.2](#migration-from-0211-to-0502) to determine if upgrading is -right for you at this time. +## Getting started -The new AMQP-based API offers improved message passing reliability, performance and expanded feature support going forward. -The new API also offers support for asynchronous operations (based on asyncio) for sending, receiving and handling messages. +### Install the package -For documentation on the legacy HTTP-based operations please see [Using HTTP-based operations of the legacy API](https://docs.microsoft.com/python/api/overview/azure/servicebus?view=azure-python#using-http-based-operations-of-the-legacy-api). +Install the Azure Service Bus client library for Python with [pip][pip]: +```Bash +pip install azure-servicebus --pre +``` + +**Prerequisites**: +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] + +If you need an azure service bus namespace and do not wish to use the graphical portal UI, you can use the Azure CLI via [Cloud Shell][cloud_shell_bash], or Azure CLI run locally, to create one with this Azure CLI command: + +```Bash +az servicebus namespace create --resource-group --name --location +``` + +### Authenticate the client -## Prerequisites +Interaction with Service Bus starts with an instance of the `ServiceBusClient` class. You either need a **connection string with SAS key**, or a **namespace** and one of its **account keys** to instantiate the client object. -* Azure subscription - [Create a free account](https://azure.microsoft.com/free/) -* Azure Service Bus [namespace and management credentials](https://docs.microsoft.com/azure/service-bus-messaging/service-bus-create-namespace-portal) +#### Get credentials +Use the [Azure CLI][azure_cli] snippet below to populate an environment variable with the service bus connection string (you can also find these values in the [Azure portal][azure_portal]. The snippet is formatted for the Bash shell. -## Installation +```Bash +RES_GROUP= +NAMESPACE_NAME= -```shell -pip install azure-servicebus +export SERVICE_BUS_CONN_STR=$(az servicebus namespace authorization-rule keys list --resource-group $RES_GROUP --namespace-name $NAMESPACE_NAME --query RootManageSharedAccessKey --output tsv) ``` -## Migration from 0.21.1 to 0.50.2 +#### Create client + +Once you've populated the `SERVICE_BUS_CONN_STR` environment variable, you can create the `ServiceBusClient`. + +```Python +from azure.servicebus import ServiceBusClient + +import os +connstr = os.environ['SERVICE_BUS_CONN_STR'] + +with ServiceBusClient.from_connection_string(connstr) as client: + ... +``` + +Note: client can be initialized without a context manager, but must be manually closed via client.close() to not leak resources. + +## Key concepts + +Once you've initialized a `ServiceBusClient`, you can interact with the primary resource types within a Service Bus Namespace, of which multiple can exist and on which actual message transmission takes place, the namespace often serving as an application container: + +* Queue: Allows for Sending and Receiving of messages, ordered first-in-first-out. Often used for point-to-point communication. -Major breaking changes were introduced in version 0.50.2. -The original HTTP-based API is still available in v0.50.2 - however it now exists under a new namesapce: `azure.servicebus.control_client`. +* Topic: As opposed to Queues, Topics are better suited to publish/subscribe scenarios. A topic can be sent to, but requires a subscription, of which there can be multiple in parallel, to consume from. -### Should I upgrade? +* Subscription: The mechanism to consume from a Topic. Each subscription is independent, and receaves a copy of each message sent to the topic. Rules and Filters can be used to tailor which messages are received by a specific subscription. -The new package (v0.50.2) offers no improvements in HTTP-based operations over v0.21.1. The HTTP-based API is identical except that it now -exists under a new namespace. For this reason if you only wish to use HTTP-based operations (`create_queue`, `delete_queue` etc) - there will be -no additional benefit in upgrading at this time. +For more information about these resources, see [What is Azure Service Bus?][service_bus_overview]. +## Examples -### How do I migrate my code to the new version? +The following sections provide several code snippets covering some of the most common Service Bus tasks, including: -Code written against v0.21.0 can be ported to version 0.50.2 by simply changing the import namespace: +* [Send a message to a queue](#send-to-a-queue) +* [Receive a message from a queue](#receive-from-a-queue) +* [Deadletter a message on receipt](#deadletter-a-message) -```python -# from azure.servicebus import ServiceBusService <- This will now raise an ImportError -from azure.servicebus.control_client import ServiceBusService -key_name = 'RootManageSharedAccessKey' # SharedAccessKeyName from Azure portal -key_value = '' # SharedAccessKey from Azure portal -sbs = ServiceBusService(service_namespace, - shared_access_key_name=key_name, - shared_access_key_value=key_value) +### Send 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. + +```Python +with client.get_queue_sender(queue_name): + + message = Message("Single message") + queue_sender.send(message) +``` + +### Receive from a queue + +To receive from a queue, you can either perform a one-off receive via "receiver.receive()" or receive persistently as follows: + +```Python +with client.get_queue_receiver(queue_name) as receiver: + for msg in receiver: + print(str(msg)) + msg.complete() ``` +### Deadletter a message + +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 send the message to the dead letter queue: + +```Python +with client.get_queue_receiver(queue_name) as receiver: + for msg in receiver: + print(str(msg)) + msg.dead_letter() +``` + +## Next steps + +### More sample code + +Please find further examples in the [samples](./samples) directory demonstrating common Service Bus scenarios such as sending, receiving, and message handling. + +### Additional documentation + +For more extensive documentation on the Service Bus service, see the [Service Bus DB documentation][service_bus_docs] on docs.microsoft.com. -# Usage +### Logging -For reference documentation and code snippets see [Service Bus](https://docs.microsoft.com/python/api/overview/azure/servicebus) -on docs.microsoft.com. +- Enable `azure.servicebus` logger to collect traces from the library. +- Enable `uamqp` logger to collect traces from the underlying uAMQP library. +- Enable AMQP frame level trace by setting `logging_enable=True` when creating the client. +## Contributing -# Provide Feedback +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 https://cla.microsoft.com. -If you encounter any bugs or have suggestions, please file an issue in the -[Issues](https://github.com/Azure/azure-sdk-for-python/issues) -section of the project. +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](https://opensource.microsoft.com/codeofconduct/). +For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or +contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. -![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-python%2Fazure-servicebus%2FREADME.png) + +[azure_cli]: https://docs.microsoft.com/cli/azure +[api_docs]: https://docs.microsoft.com/python/api/overview/azure/servicebus/client?view=azure-python +[product_docs]: https://docs.microsoft.com/azure/service-bus-messaging/ +[azure_portal]: https://portal.azure.com +[azure_sub]: https://azure.microsoft.com/free/ +[cloud_shell]: https://docs.microsoft.com/azure/cloud-shell/overview +[cloud_shell_bash]: https://shell.azure.com/bash +[pip]: https://pypi.org/project/pip/ +[pypi]: https://pypi.org/project/azure-servicebus/ +[python]: https://www.python.org/downloads/ +[venv]: https://docs.python.org/3/library/venv.html +[virtualenv]: https://virtualenv.pypa.io +[service_bus_namespace]: https://docs.microsoft.com/azure/service-bus-messaging/service-bus-create-namespace-portal +[service_bus_overview]: https://docs.microsoft.com/azure/service-bus-messaging/service-bus-messaging-overview +[queue_status_codes]: https://docs.microsoft.com/rest/api/servicebus/create-queue#response-codes +[service_bus_docs]: https://docs.microsoft.com/azure/service-bus/ \ No newline at end of file diff --git a/sdk/servicebus/azure-servicebus/azure/servicebus/_version.py b/sdk/servicebus/azure-servicebus/azure/servicebus/_version.py index 8bbaebb97523..b17051749942 100644 --- a/sdk/servicebus/azure-servicebus/azure/servicebus/_version.py +++ b/sdk/servicebus/azure-servicebus/azure/servicebus/_version.py @@ -3,4 +3,4 @@ # Licensed under the MIT License. # ------------------------------------ -VERSION = '0.50.2' \ No newline at end of file +VERSION = '1.0.0b1' \ No newline at end of file diff --git a/sdk/servicebus/azure-servicebus/samples/README.md b/sdk/servicebus/azure-servicebus/samples/README.md index ecbca90beec0..2a8e34c841fb 100644 --- a/sdk/servicebus/azure-servicebus/samples/README.md +++ b/sdk/servicebus/azure-servicebus/samples/README.md @@ -13,7 +13,7 @@ urlFragment: servicebus-samples These are code samples that show common scenario operations with the Azure Service Bus client library. Both [sync version](./sync_sampes) and [async version](./async_samples) of samples are provided, async samples require Python 3.5 or later. -- [topic_send.py](./sync_samples/topic_send.py) ([async version](./async_samples/topic_send_async.py)) - Examples to send messages on a service bus topic: +- [send_queue.py](./sync_samples/send_queue.py) ([async version](./async_samples/send_queue_async.py)) - Examples to send messages on a service bus queue: - From a connection string - Enabling Logging @@ -35,10 +35,7 @@ pip install azure-servicebus 1. Open a terminal window and `cd` to the directory that the samples are saved in. 2. Set the environment variables specified in the sample file you wish to run. -3. Follow the usage described in the file, e.g. `python topic_send.py`. - - Note: If the sample in question uses pytest (look for @livetest marks) please run via pytest specifying the test name, and have the servicebus credentials present in environment variables - as described in conftest.py. +3. Follow the usage described in the file, e.g. `python send_queue.py`. ## Next steps diff --git a/sdk/servicebus/azure-servicebus/samples/sync_samples/send_queue.py b/sdk/servicebus/azure-servicebus/samples/sync_samples/send_queue.py index af0f136281ad..61d228e0fa8b 100644 --- a/sdk/servicebus/azure-servicebus/samples/sync_samples/send_queue.py +++ b/sdk/servicebus/azure-servicebus/samples/sync_samples/send_queue.py @@ -17,7 +17,7 @@ CONNECTION_STR = os.environ['SERVICE_BUS_CONNECTION_STR'] QUEUE_NAME = os.environ["SERVICE_BUS_QUEUE_NAME"] -servicebus_client = ServiceBusClient.from_connection_string(conn_str=CONNECTION_STR) +servicebus_client = ServiceBusClient.from_connection_string(conn_str=CONNECTION_STR, logging_enable=True) sender = servicebus_client.get_queue_sender( queue_name=QUEUE_NAME