Skip to content

Commit

Permalink
[ServiceBus] Clean up README prior to P6 with doc-owner recommendatio…
Browse files Browse the repository at this point in the history 
…ns. (Azure#13511)

* Remove long-form samples from readme authentication section and move them into formal samples with URIs. (This by recommendation of docs folks, and supported via UX interview with user stating that the README was getting long in the teeth with this section being less critical)
  • Loading branch information
@KieranBrantnerMagee @rakshith91
KieranBrantnerMagee authored and rakshith91 committed Sep 4, 2020
1 parent 637a6da commit 9507849
Show file tree
Hide file tree
Showing 4 changed files with 98 additions and 56 deletions.
85 changes: 29 additions & 56 deletions sdk/servicebus/azure-servicebus/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -47,43 +47,13 @@ az servicebus namespace create --resource-group <resource-group-name> --name <se
### Authenticate the client

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.
Please find the samples linked below for demonstration as to how to authenticate via either approach.

#### Create client from connection string
#### [Create client from connection string][sample_authenticate_client_connstr]

- 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] by following the step-by-step guide to [Get a service bus connection string][get_servicebus_conn_str]). The snippet is formatted for the Bash shell.
- To obtain the required credentials, one can use the [Azure CLI][azure_cli] snippet (Formatted for Bash Shell) at the top of the linked sample to populate an environment variable with the service bus connection string (you can also find these values in the [Azure Portal][azure_portal] by following the step-by-step guide to [Get a service bus connection string][get_servicebus_conn_str]).

```Bash
RES_GROUP=<resource-group-name>
NAMESPACE_NAME=<servicebus-namespace-name>

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)
```

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:
...
```

#### 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):
...
```
#### [Create client using the azure-identity library][sample_authenticate_client_aad]:

- This constructor takes the fully qualified namespace of your Service Bus instance and a credential that implements the
[TokenCredential][token_credential_interface]
Expand All @@ -93,7 +63,7 @@ protocol. There are implementations of the `TokenCredential` protocol available
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.
>**Note:** client can be initialized without a context manager, but must be manually closed via client.close() to not leak resources.
## Key concepts

Expand Down Expand Up @@ -126,6 +96,7 @@ The following sections provide several code snippets covering some of the most c
* [Send and receive a message from a session enabled queue](#send-and-receive-a-message-from-a-session-enabled-queue)
* [Working with topics and subscriptions](#working-with-topics-and-subscriptions)
* [Settle a message after receipt](#settle-a-message-after-receipt)
* [Automatically renew Message or Session locks](#automatically-renew-message-or-session-locks)

To perform management tasks such as creating and deleting queues/topics/subscriptions, please utilize the azure-mgmt-servicebus library, available [here][servicebus_management_repository].

Expand Down Expand Up @@ -346,27 +317,7 @@ with ServiceBusClient.from_connection_string(connstr) as client:
msg.defer()
```

## Troubleshooting

### Logging

- 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.

### Timeouts

There are various timeouts a user should be aware of within the library.
- 10 minute service side link closure: A link, once opened, will be closed after 10 minutes idle to protect the service against resource leakage. This should largely
be transparent to a user, but if you notice a reconnect occurring after such a duration, this is why. Performing any operations, including management operations, on the
link will extend this timeout.
- max_wait_time: Provided on creation of a receiver or when calling `receive_messages()` or `get_streaming_message_iter()`, the time after which receiving messages will halt after no traffic. This applies both to the imperative `receive_messages()` function as well as the length
a generator-style receive will run for before exiting if there are no messages. Passing None (default) will wait forever, up until the 10 minute threshold if no other action is taken.

> **NOTE:** If processing of a message or session is sufficiently long as to cause timeouts, as an alternative to calling `renew_lock()` manually, one can
> leverage the `AutoLockRenew` functionality detailed below.
### [AutoLockRenew][autolockrenew_reference]
### [Automatically renew Message or Session locks][autolockrenew_reference]

`AutoLockRenew` is a simple method for ensuring your message or session remains locked even over long periods of time, if calling `renew_lock()` is impractical or undesired.
Internally, it is not much more than shorthand for creating a concurrent watchdog to call `renew_lock()` if the object is nearing expiry.
Expand Down Expand Up @@ -395,6 +346,26 @@ renewer.close()
If for any reason auto-renewal has been interrupted or failed, this can be observed via the `auto_renew_error` property on the object being renewed.
It would also manifest when trying to take action (such as completing a message) on the specified object.

## Troubleshooting

### Logging

- 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.

### Timeouts

There are various timeouts a user should be aware of within the library.
- 10 minute service side link closure: A link, once opened, will be closed after 10 minutes idle to protect the service against resource leakage. This should largely
be transparent to a user, but if you notice a reconnect occurring after such a duration, this is why. Performing any operations, including management operations, on the
link will extend this timeout.
- max_wait_time: Provided on creation of a receiver or when calling `receive_messages()` or `get_streaming_message_iter()`, the time after which receiving messages will halt after no traffic. This applies both to the imperative `receive_messages()` function as well as the length
a generator-style receive will run for before exiting if there are no messages. Passing None (default) will wait forever, up until the 10 minute threshold if no other action is taken.

> **NOTE:** If processing of a message or session is sufficiently long as to cause timeouts, as an alternative to calling `renew_lock()` manually, one can
> leverage the `AutoLockRenew` functionality detailed [above](#automatically-renew-message-or-session-locks).
### Common Exceptions

Please view the [exceptions reference docs][exception_reference] for detailed descriptions of our common Exception types.
Expand Down Expand Up @@ -473,6 +444,8 @@ contact [[email protected]](mailto:[email protected]) with any additio
[exception_reference]: https://azuresdkdocs.blob.core.windows.net/$web/python/azure-servicebus/latest/azure.servicebus.html#module-azure.servicebus.exceptions
[subscription_reference]: https://azuresdkdocs.blob.core.windows.net/$web/python/azure-servicebus/latest/azure.servicebus.aio.html?highlight=subscription#azure.servicebus.aio.ServiceBusClient.get_subscription_receiver
[topic_reference]: https://azuresdkdocs.blob.core.windows.net/$web/python/azure-servicebus/latest/azure.servicebus.html?highlight=topic#azure.servicebus.ServiceBusClient.get_topic_sender
[sample_authenticate_client_connstr]: https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/servicebus/azure-servicebus/samples/sync_samples/authenticate_client_connstr.py
[sample_authenticate_client_aad]: https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/servicebus/azure-servicebus/samples/sync_samples/client_identity_authentication.py
[0_50_source]: https://github.com/Azure/azure-sdk-for-python/tree/servicebus_v0.50.3/sdk/servicebus/azure-servicebus/
[0_50_pypi]: https://pypi.org/project/azure-servicebus/0.50.3/
[0_50_api_docs]:https://azuresdkdocs.blob.core.windows.net/$web/python/azure-servicebus/0.50.3/index.html
Expand Down
2 changes: 2 additions & 0 deletions sdk/servicebus/azure-servicebus/samples/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,8 @@ Both [sync version](./sync_samples) and [async version](./async_samples) of samp
- Cancel scheduled messages from a topic
- [client_identity_authentication.py](./sync_samples/client_identity_authentication.py) ([async_version](./async_samples/client_identity_authentication_async.py)) - Examples to authenticate the client by Azure Activate Directory
- Authenticate and create the client utilizing the `azure.identity` library
- [authenticate_client_connstr.py](./sync_samples/authenticate_client_connstr.py) ([async_version](./async_samples/authenticate_client_connstr_async.py)) - Examples to authenticate the client by Connection String
- Authenticate and create the client utilizing the connection string available in the Azure portal or via Azure CLI.
- [proxy.py](./sync_samples/proxy.py) ([async_version](./async_samples/proxy_async.py)) - Examples to send message behind a proxy:
- Send message behind a proxy
- [auto_lock_renew.py](./sync_samples/auto_lock_renew.py) ([async_version](./async_samples/auto_lock_renew_async.py)) - Examples to show usage of AutoLockRenew:
Expand Down
36 changes: 36 additions & 0 deletions sdk/servicebus/azure-servicebus/samples/async_samples/authenticate_client_connstr_async.py
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
#!/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.
# --------------------------------------------------------------------------------------------

"""
Example to show connection-string based authentication of the ServiceBusClient.
Note: To get credentials, one can either obtain the connection string from the Azure Portal,
or use the Azure CLI snippet below to populate an environment variable with the service bus connection string. The following is in bash:
```bash
RES_GROUP=<resource-group-name>
NAMESPACE_NAME=<servicebus-namespace-name>
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)
```
"""

# pylint: disable=C0111

from azure.servicebus.aio import ServiceBusClient

import os
import asyncio

connstr = os.environ['SERVICE_BUS_CONN_STR']

async def run():
async with ServiceBusClient.from_connection_string(connstr) as client:
pass # Client is now initialized and can be used.

loop = asyncio.get_event_loop()
loop.run_until_complete(run())
31 changes: 31 additions & 0 deletions sdk/servicebus/azure-servicebus/samples/sync_samples/authenticate_client_connstr.py
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
#!/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.
# --------------------------------------------------------------------------------------------

"""
Example to show connection-string based authentication of the ServiceBusClient.
Note: To get credentials, one can either obtain the connection string from the Azure Portal,
or use the Azure CLI snippet below to populate an environment variable with the service bus connection string. The following is in bash:
```bash
RES_GROUP=<resource-group-name>
NAMESPACE_NAME=<servicebus-namespace-name>
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)
```
"""

# pylint: disable=C0111

from azure.servicebus import ServiceBusClient

import os
connstr = os.environ['SERVICE_BUS_CONN_STR']

with ServiceBusClient.from_connection_string(connstr) as client:
pass # Client is now initialized and can be used.

0 comments on commit 9507849

Please sign in to comment.