[webpubsub] support AAD, Api management proxy

eng/tox/allowed_pylint_failures.py

@@ -55,6 +55,7 @@
     "azure-purview-scanning",
     "azure-purview-catalog",
     "azure-purview-account",
+    "azure-messaging-webpubsubservice",
     "azure-messaging-nspkg",
     "azure-agrifood-farming",
     "azure-eventhub",

sdk/webpubsub/azure-messaging-webpubsubservice/CHANGELOG.md

@@ -2,8 +2,11 @@
 
 ## 1.0.0b2 (Unreleased)
 
+- Add operations to client
+- Support AAD
+- Support Api Management Proxy
 
 ## 1.0.0b1 (2021-04-27)
 
-Initial version
+- Initial version
 

sdk/webpubsub/azure-messaging-webpubsubservice/MANIFEST.in

@@ -3,4 +3,4 @@ include azure/__init__.py
 include azure/messaging/__init__.py
 include LICENSE.txt
 recursive-include tests *.py
-recursive-include examples *.py *.md
+recursive-include samples *.py *.md

sdk/webpubsub/azure-messaging-webpubsubservice/README.md

@@ -43,14 +43,48 @@ python -m pip install azure-messaging-webpubsubservice
 
 ### Authenticating the client
 
-In order to interact with the Azure WebPubSub service, you'll need to create an instance of the [WebPubSubServiceClient][webpubsubservice_client_class] class. In order to authenticate against the service, you need to pass in an AzureKeyCredential instance with endpoint and api key. The endpoint and api key can be found on the azure portal.
+#### 1. Create with an API Key Credential
+
+You can get the [API key][api_key] or [Connection string][connection_string] in the [Azure Portal][azure_portal].
+Once you have the value for the API key, you can pass it as a string into an instance of [AzureKeyCredential][azure-key-credential]. 
+Use the key as the credential parameter to authenticate the client:
 
 ```python
 >>> from azure.messaging.webpubsubservice import WebPubSubServiceClient
 >>> from azure.core.credentials import AzureKeyCredential
->>> client = WebPubSubServiceClient(endpoint='<endpoint>', credential=AzureKeyCredential('somesecret'))
->>> client
-<WebPubSubServiceClient endpoint:'<endpoint>'>
+
+>>> client = WebPubSubServiceClient(endpoint='<endpoint>', credential=AzureKeyCredential("<api_key>"))
+```
+
+Once you have the value for the connection string, you can pass it as a string into the function `from_connection_string` and it will 
+authenticate the client:
+```python
+>>> from azure.messaging.webpubsubservice import WebPubSubServiceClient
+
+>>> client = WebPubSubServiceClient.from_connection_string(connection_string='<connection_string>')
+```
+
+#### 2. Create with an Azure Active Directory Credential
+To use an [Azure Active Directory (AAD) token credential][authenticate_with_token],
+provide an instance of the desired credential type obtained from the
+[azure-identity][azure_identity_credentials] library.
+
+To authenticate with AAD, you must first [pip][pip] install [`azure-identity`][azure_identity_pip] and
+[enable AAD authentication on your Webpubsub resource][enable_aad]
+
+After setup, you can choose which type of [credential][azure_identity_credentials] from azure.identity to use.
+As an example, [DefaultAzureCredential][default_azure_credential]
+can be used to authenticate the client:
+
+Set the values of the client ID, tenant ID, and client secret of the AAD application as environment variables:
+AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET
+
+Use the returned token credential to authenticate the client:
+
+```python
+>>> from azure.messaging.webpubsubservice import WebPubSubServiceClient
+>>> from azure.identity import DefaultAzureCredential
+>>> client = WebPubSubServiceClient(endpoint='<endpoint>', credential=DefaultAzureCredential())
 ```
 
 ## Examples
@@ -59,22 +93,16 @@ In order to interact with the Azure WebPubSub service, you'll need to create an
 
 ```python
 >>> from azure.messaging.webpubsubservice import WebPubSubServiceClient
->>> from azure.core.credentials import AzureKeyCredential
->>> from azure.messaging.webpubsubservice.rest import build_send_to_all_request
->>> client = WebPubSubServiceClient(endpoint='<endpoint>', credential=AzureKeyCredential('somesecret'))
->>> request = build_send_to_all_request('default', json={ 'Hello':  'webpubsub!' })
->>> request
-<HttpRequest [POST], url: '/api/hubs/default/:send?api-version=2020-10-01'>
->>> response = client.send_request(request)
->>> response
-<RequestsTransportResponse: 202 Accepted>
->>> response.status_code
-202
+>>> from azure.identity import DefaultAzureCredential
+>>> from azure.core.exceptions import HttpResponseError
+
+>>> client = WebPubSubServiceClient(endpoint='<endpoint>', credential=DefaultAzureCredential())
 >>> with open('file.json', 'r') as f:
->>>    request = build_send_to_all_request('ahub', content=f, content_type='application/json')
->>>    response = client.send_request(request)
->>> print(response)
-<RequestsTransportResponse: 202 Accepted>
+    try:
+        client.send_to_all('ahub', content=f, content_type='application/json')
+    except HttpResponseError as e:
+        print('service responds error: {}'.format(e.response.json()))
+
 ```
 
 ## Key concepts
@@ -107,10 +135,32 @@ This SDK uses Python standard logging library.
 You can configure logging print out debugging information to the stdout or anywhere you want.
 
 ```python
+import sys
 import logging
+from azure.identity import DefaultAzureCredential
+>>> from azure.messaging.webpubsubservice import WebPubSubServiceClient
+
+# Create a logger for the 'azure' SDK
+logger = logging.getLogger('azure')
+logger.setLevel(logging.DEBUG)
 
-logging.basicConfig(level=logging.DEBUG)
-````
+# Configure a console output
+handler = logging.StreamHandler(stream=sys.stdout)
+logger.addHandler(handler)
+
+endpoint = "<endpoint>"
+credential = DefaultAzureCredential()
+
+# This client will log detailed information about its HTTP sessions, at DEBUG level
+client = WebPubSubServiceClient(endpoint=endpoint, credential=credential, logging_enable=True)
+```
+
+Similarly, `logging_enable` can enable detailed logging for a single call,
+even when it isn't enabled for the client:
+
+```python
+result = client.send_to_all(..., logging_enable=True)
+```
 
 Http request and response details are printed to stdout with this logging config.
 
@@ -139,10 +189,19 @@ additional questions or comments.
 [webpubsubservice_docs]: https://aka.ms/awps/doc
 [azure_cli]: https://docs.microsoft.com/cli/azure
 [azure_sub]: https://azure.microsoft.com/free/
-[webpubsubservice_client_class]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/webpubsub/azure-messaging-webpubsubservice/azure/messaging/webpubsubservice/__init__.py
 [package]: https://pypi.org/project/azure-messaging-webpubsubservice/
 [default_cred_ref]: https://aka.ms/azsdk-python-identity-default-cred-ref
 [cla]: https://cla.microsoft.com
 [code_of_conduct]: https://opensource.microsoft.com/codeofconduct/
 [coc_faq]: https://opensource.microsoft.com/codeofconduct/faq/
 [coc_contact]: mailto:[email protected]
+[authenticate_with_token]: https://docs.microsoft.com/azure/cognitive-services/authentication?tabs=powershell#authenticate-with-an-authentication-token
+[azure_identity_credentials]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/identity/azure-identity#credentials
+[azure_identity_pip]: https://pypi.org/project/azure-identity/
+[default_azure_credential]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/identity/azure-identity#defaultazurecredential
+[pip]: https://pypi.org/project/pip/
+[enable_aad]: https://docs.microsoft.com/azure/azure-web-pubsub/howto-develop-create-instance
+[api_key]: https://docs.microsoft.com/azure/azure-web-pubsub/howto-websocket-connect?tabs=browser#authorization
+[connection_string]: https://docs.microsoft.com/azure/azure-web-pubsub/howto-websocket-connect?tabs=browser#authorization
+[azure_portal]: https://docs.microsoft.com/azure/azure-web-pubsub/howto-develop-create-instance
+[azure-key-credential]: https://aka.ms/azsdk-python-core-azurekeycredential