diff --git a/sdk/monitor/azure-monitor-ingestion/README.md b/sdk/monitor/azure-monitor-ingestion/README.md index 36bcdc0b8f06..aee218f11994 100644 --- a/sdk/monitor/azure-monitor-ingestion/README.md +++ b/sdk/monitor/azure-monitor-ingestion/README.md @@ -69,7 +69,12 @@ logs_client = LogsIngestionClient(endpoint, credential) By default, `LogsIngestionClient` is configured to connect to the public Azure cloud. To connect to non-public Azure clouds, some additional configuration is required. The appropriate scope for authentication must be provided using the `credential_scopes` keyword argument. The following example shows how to configure the client to connect to Azure US Government: ```python -logs_client = LogsIngestionClient(endpoint, credential_scopes=["https://monitor.azure.us//.default"]) +from azure.identity import AzureAuthorityHosts, DefaultAzureCredential +from azure.monitor.ingestion import LogsIngestionClient + +# Authority can also be set via the AZURE_AUTHORITY_HOST environment variable. +credential = DefaultAzureCredential(authority=AzureAuthorityHosts.AZURE_GOVERNMENT) +logs_client = LogsIngestionClient(endpoint, credential, credential_scopes=["https://monitor.azure.us/.default"]) ``` ## Key concepts diff --git a/sdk/monitor/azure-monitor-ingestion/azure/monitor/ingestion/_patch.py b/sdk/monitor/azure-monitor-ingestion/azure/monitor/ingestion/_patch.py index 05533ce0eb19..ef7425309147 100644 --- a/sdk/monitor/azure-monitor-ingestion/azure/monitor/ingestion/_patch.py +++ b/sdk/monitor/azure-monitor-ingestion/azure/monitor/ingestion/_patch.py @@ -21,6 +21,24 @@ class LogsIngestionClient(GeneratedClient): :keyword api_version: Api Version. Default value is "2023-01-01". Note that overriding this default value may result in unsupported behavior. :paramtype api_version: str + + .. admonition:: Example: + + .. literalinclude:: ../samples/sample_authentication.py + :start-after: [START create_client_public_cloud] + :end-before: [END create_client_public_cloud] + :language: python + :dedent: 4 + :caption: Creating the LogsIngestionClient with DefaultAzureCredential. + + .. admonition:: Example: + + .. literalinclude:: ../samples/sample_authentication.py + :start-after: [START create_client_sovereign_cloud] + :end-before: [END create_client_sovereign_cloud] + :language: python + :dedent: 4 + :caption: Creating the LogsIngestionClient for use with a sovereign cloud (i.e. non-public cloud). """ diff --git a/sdk/monitor/azure-monitor-ingestion/azure/monitor/ingestion/aio/_patch.py b/sdk/monitor/azure-monitor-ingestion/azure/monitor/ingestion/aio/_patch.py index 7da806c76537..ef37c4edbdb2 100644 --- a/sdk/monitor/azure-monitor-ingestion/azure/monitor/ingestion/aio/_patch.py +++ b/sdk/monitor/azure-monitor-ingestion/azure/monitor/ingestion/aio/_patch.py @@ -21,6 +21,24 @@ class LogsIngestionClient(GeneratedClient): :keyword api_version: Api Version. Default value is "2023-01-01". Note that overriding this default value may result in unsupported behavior. :paramtype api_version: str + + .. admonition:: Example: + + .. literalinclude:: ../samples/async_samples/sample_authentication_async.py + :start-after: [START create_client_public_cloud_async] + :end-before: [END create_client_public_cloud_async] + :language: python + :dedent: 4 + :caption: Creating the LogsIngestionClient with DefaultAzureCredential. + + .. admonition:: Example: + + .. literalinclude:: ../samples/async_samples/sample_authentication_async.py + :start-after: [START create_client_sovereign_cloud_async] + :end-before: [END create_client_sovereign_cloud_async] + :language: python + :dedent: 4 + :caption: Creating the LogsIngestionClient for use with a sovereign cloud (i.e. non-public cloud). """ diff --git a/sdk/monitor/azure-monitor-ingestion/samples/README.md b/sdk/monitor/azure-monitor-ingestion/samples/README.md index 83c00bc25b86..b4393d44fab5 100644 --- a/sdk/monitor/azure-monitor-ingestion/samples/README.md +++ b/sdk/monitor/azure-monitor-ingestion/samples/README.md @@ -14,6 +14,7 @@ This library allows you to send data from virtually any source to supported buil |**File Name**|**Description**| |-------------|---------------| +|[sample_authentication.py][sample_authentication] and [sample_authentication_async.py][sample_authentication_async]|Authenticate a client with the public cloud and a sovereign cloud.| |[sample_send_small_logs.py][sample_send_small_logs] and [sample_send_small_logs_async.py][sample_send_small_logs_async]|Send a small number of logs to a Log Analytics workspace.| |[sample_custom_error_callback.py][sample_custom_error_callback] and [sample_custom_error_callback_async.py][sample_custom_error_callback_async]|Use error callbacks to customize how errors are handled during upload. | |[sample_upload_file_contents.py][sample_upload_file_contents] and [sample_upload_file_contents_async.py][sample_upload_file_contents_async]|Upload the contents of a file to a Log Analytics workspace.| @@ -72,6 +73,8 @@ To learn more about Azure Monitor, see the [Azure Monitor service documentation] +[sample_authentication]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/monitor/azure-monitor-ingestion/samples/sample_authentication.py +[sample_authentication_async]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/monitor/azure-monitor-ingestion/samples/async_samples/sample_authentication_async.py [sample_send_small_logs]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/monitor/azure-monitor-ingestion/samples/sample_send_small_logs.py [sample_send_small_logs_async]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/monitor/azure-monitor-ingestion/samples/async_samples/sample_send_small_logs_async.py [sample_custom_error_callback]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/monitor/azure-monitor-ingestion/samples/sample_custom_error_callback.py diff --git a/sdk/monitor/azure-monitor-ingestion/samples/async_samples/sample_authentication_async.py b/sdk/monitor/azure-monitor-ingestion/samples/async_samples/sample_authentication_async.py new file mode 100644 index 000000000000..1c076e709dd9 --- /dev/null +++ b/sdk/monitor/azure-monitor-ingestion/samples/async_samples/sample_authentication_async.py @@ -0,0 +1,51 @@ +# ------------------------------------------------------------------------- +# Copyright (c) Microsoft Corporation. All rights reserved. +# Licensed under the MIT License. See License.txt in the project root for +# license information. +# -------------------------------------------------------------------------- + +""" +FILE: sample_authentication_async.py + +DESCRIPTION: + This sample demonstrates how to authenticate the LogsIngestionClient. + + Note: This sample requires the azure-identity library. + +USAGE: + python sample_authentication_async.py +""" + +import asyncio + + +async def authenticate_public_cloud(): + # [START create_client_public_cloud_async] + from azure.identity.aio import DefaultAzureCredential + from azure.monitor.ingestion.aio import LogsIngestionClient + + credential = DefaultAzureCredential() + endpoint = "https://example.ingest.monitor.azure.com" + client = LogsIngestionClient(endpoint, credential) + # [END create_client_public_cloud_async] + + +async def authenticate_sovereign_cloud(): + # [START create_client_sovereign_cloud_async] + from azure.identity import AzureAuthorityHosts + from azure.identity.aio import DefaultAzureCredential + from azure.monitor.ingestion.aio import LogsIngestionClient + + credential = DefaultAzureCredential(authority=AzureAuthorityHosts.AZURE_GOVERNMENT) + endpoint = "https://example.ingest.monitor.azure.us" + client = LogsIngestionClient(endpoint, credential, credential_scopes=["https://monitor.azure.us/.default"]) + # [END create_client_sovereign_cloud_async] + + +async def main(): + await authenticate_public_cloud() + await authenticate_sovereign_cloud() + + +if __name__ == "__main__": + asyncio.run(main()) diff --git a/sdk/monitor/azure-monitor-ingestion/samples/sample_authentication.py b/sdk/monitor/azure-monitor-ingestion/samples/sample_authentication.py new file mode 100644 index 000000000000..9cb512de58bc --- /dev/null +++ b/sdk/monitor/azure-monitor-ingestion/samples/sample_authentication.py @@ -0,0 +1,44 @@ +# ------------------------------------------------------------------------- +# Copyright (c) Microsoft Corporation. All rights reserved. +# Licensed under the MIT License. See License.txt in the project root for +# license information. +# -------------------------------------------------------------------------- + +""" +FILE: sample_authentication.py + +DESCRIPTION: + This sample demonstrates how to authenticate the LogsIngestionClient. + + Note: This sample requires the azure-identity library. + +USAGE: + python sample_authentication.py +""" + + +def authenticate_public_cloud(): + # [START create_client_public_cloud] + from azure.identity import DefaultAzureCredential + from azure.monitor.ingestion import LogsIngestionClient + + credential = DefaultAzureCredential() + endpoint = "https://example.ingest.monitor.azure.com" + client = LogsIngestionClient(endpoint, credential) + # [END create_client_public_cloud] + + +def authenticate_sovereign_cloud(): + # [START create_client_sovereign_cloud] + from azure.identity import AzureAuthorityHosts, DefaultAzureCredential + from azure.monitor.ingestion import LogsIngestionClient + + credential = DefaultAzureCredential(authority=AzureAuthorityHosts.AZURE_GOVERNMENT) + endpoint = "https://example.ingest.monitor.azure.us" + client = LogsIngestionClient(endpoint, credential, credential_scopes=["https://monitor.azure.us/.default"]) + # [END create_client_sovereign_cloud] + + +if __name__ == "__main__": + authenticate_public_cloud() + authenticate_sovereign_cloud() diff --git a/sdk/monitor/azure-monitor-query/README.md b/sdk/monitor/azure-monitor-query/README.md index 275da0c8b242..3103aa7f99de 100644 --- a/sdk/monitor/azure-monitor-query/README.md +++ b/sdk/monitor/azure-monitor-query/README.md @@ -73,8 +73,15 @@ async_metrics_client = MetricsClient("https://", credential) By default, `LogsQueryClient` and `MetricsQueryClient` are configured to connect to the public Azure cloud. These can be configured to connect to non-public Azure clouds by passing in the correct `endpoint` argument: For example: ```python -logs_query_client = LogsQueryClient(credential, endpoint="https://api.loganalytics.azure.cn/v1") -metrics_query_client = MetricsQueryClient(credential, endpoint="https://management.chinacloudapi.cn") +from azure.identity import AzureAuthorityHosts, DefaultAzureCredential +from azure.monitor.query import LogsQueryClient, MetricsQueryClient + +# Authority can also be set via the AZURE_AUTHORITY_HOST environment variable. +credential = DefaultAzureCredential(authority=AzureAuthorityHosts.AZURE_GOVERNMENT) + +logs_query_client = LogsQueryClient(credential, endpoint="https://api.loganalytics.us/v1") +metrics_query_client = MetricsQueryClient(credential, endpoint="https://management.usgovcloudapi.net") + ``` **Note**: Currently, `MetricsQueryClient` uses the Azure Resource Manager (ARM) endpoint for querying metrics, so you will need the corresponding management endpoint for your cloud when using this client. This is subject to change in the future. diff --git a/sdk/monitor/azure-monitor-query/azure/monitor/query/_logs_query_client.py b/sdk/monitor/azure-monitor-query/azure/monitor/query/_logs_query_client.py index e0c3ea902984..75ad359d3e3c 100644 --- a/sdk/monitor/azure-monitor-query/azure/monitor/query/_logs_query_client.py +++ b/sdk/monitor/azure-monitor-query/azure/monitor/query/_logs_query_client.py @@ -48,6 +48,15 @@ class LogsQueryClient(object): # pylint: disable=client-accepts-api-version-key :language: python :dedent: 4 :caption: Creating the LogsQueryClient with a TokenCredential. + + .. admonition:: Example: + + .. literalinclude:: ../samples/sample_authentication.py + :start-after: [START create_logs_query_client_sovereign_cloud] + :end-before: [END create_logs_query_client_sovereign_cloud] + :language: python + :dedent: 4 + :caption: Creating the LogsQueryClient for use with a sovereign cloud (i.e. non-public cloud). """ def __init__(self, credential: TokenCredential, **kwargs: Any) -> None: diff --git a/sdk/monitor/azure-monitor-query/azure/monitor/query/_metrics_query_client.py b/sdk/monitor/azure-monitor-query/azure/monitor/query/_metrics_query_client.py index 7bae95c6863d..a0f3c4980415 100644 --- a/sdk/monitor/azure-monitor-query/azure/monitor/query/_metrics_query_client.py +++ b/sdk/monitor/azure-monitor-query/azure/monitor/query/_metrics_query_client.py @@ -38,6 +38,15 @@ class MetricsQueryClient(object): # pylint: disable=client-accepts-api-version- :language: python :dedent: 4 :caption: Creating the MetricsQueryClient with a TokenCredential. + + .. admonition:: Example: + + .. literalinclude:: ../samples/sample_authentication.py + :start-after: [START create_metrics_query_client_sovereign_cloud] + :end-before: [END create_metrics_query_client_sovereign_cloud] + :language: python + :dedent: 4 + :caption: Creating the MetricsQueryClient for use with a sovereign cloud (i.e. non-public cloud). """ def __init__(self, credential: TokenCredential, **kwargs: Any) -> None: diff --git a/sdk/monitor/azure-monitor-query/azure/monitor/query/aio/_logs_query_client_async.py b/sdk/monitor/azure-monitor-query/azure/monitor/query/aio/_logs_query_client_async.py index 1207b891c9ba..016611f22a1f 100644 --- a/sdk/monitor/azure-monitor-query/azure/monitor/query/aio/_logs_query_client_async.py +++ b/sdk/monitor/azure-monitor-query/azure/monitor/query/aio/_logs_query_client_async.py @@ -43,6 +43,15 @@ class LogsQueryClient(object): # pylint: disable=client-accepts-api-version-key :language: python :dedent: 4 :caption: Creating the asynchronous LogsQueryClient with a TokenCredential. + + .. admonition:: Example: + + .. literalinclude:: ../samples/async_samples/sample_authentication_async.py + :start-after: [START create_logs_query_client_sovereign_cloud_async] + :end-before: [END create_logs_query_client_sovereign_cloud_async] + :language: python + :dedent: 4 + :caption: Creating the LogsQueryClient for use with a sovereign cloud (i.e. non-public cloud). """ def __init__(self, credential: AsyncTokenCredential, **kwargs: Any) -> None: diff --git a/sdk/monitor/azure-monitor-query/azure/monitor/query/aio/_metrics_query_client_async.py b/sdk/monitor/azure-monitor-query/azure/monitor/query/aio/_metrics_query_client_async.py index 657659065191..a3d6e84f1d61 100644 --- a/sdk/monitor/azure-monitor-query/azure/monitor/query/aio/_metrics_query_client_async.py +++ b/sdk/monitor/azure-monitor-query/azure/monitor/query/aio/_metrics_query_client_async.py @@ -37,6 +37,15 @@ class MetricsQueryClient(object): # pylint: disable=client-accepts-api-version- :language: python :dedent: 4 :caption: Creating the asynchronous MetricsQueryClient with a TokenCredential. + + .. admonition:: Example: + + .. literalinclude:: ../samples/async_samples/sample_authentication_async.py + :start-after: [START create_metrics_query_client_sovereign_cloud_async] + :end-before: [END create_metrics_query_client_sovereign_cloud_async] + :language: python + :dedent: 4 + :caption: Creating the MetricsQueryClient for use with a sovereign cloud (i.e. non-public cloud). """ def __init__(self, credential: AsyncTokenCredential, **kwargs: Any) -> None: diff --git a/sdk/monitor/azure-monitor-query/samples/async_samples/sample_authentication_async.py b/sdk/monitor/azure-monitor-query/samples/async_samples/sample_authentication_async.py index 8d55b0867860..2ca9ce52d774 100644 --- a/sdk/monitor/azure-monitor-query/samples/async_samples/sample_authentication_async.py +++ b/sdk/monitor/azure-monitor-query/samples/async_samples/sample_authentication_async.py @@ -24,6 +24,17 @@ async def create_logs_query_client_async(): # [END create_logs_query_client_async] +async def create_logs_query_client_sovereign_cloud_async(): + # [START create_logs_query_client_sovereign_cloud_async] + from azure.identity import AzureAuthorityHosts + from azure.identity.aio import DefaultAzureCredential + from azure.monitor.query.aio import LogsQueryClient + + credential = DefaultAzureCredential(authority=AzureAuthorityHosts.AZURE_GOVERNMENT) + client = LogsQueryClient(credential, endpoint="https://api.loganalytics.us/v1") + # [END create_logs_query_client_sovereign_cloud_async] + + async def create_metrics_query_client_async(): # [START create_metrics_query_client_async] from azure.identity.aio import DefaultAzureCredential @@ -34,9 +45,22 @@ async def create_metrics_query_client_async(): # [END create_metrics_query_client_async] +async def create_metrics_query_client_sovereign_cloud_async(): + # [START create_metrics_query_client_sovereign_cloud_async] + from azure.identity import AzureAuthorityHosts + from azure.identity.aio import DefaultAzureCredential + from azure.monitor.query.aio import MetricsQueryClient + + credential = DefaultAzureCredential(authority=AzureAuthorityHosts.AZURE_GOVERNMENT) + client = MetricsQueryClient(credential, endpoint="https://management.usgovcloudapi.net") + # [END create_metrics_query_client_sovereign_cloud_async] + + async def main(): await create_logs_query_client_async() + await create_logs_query_client_sovereign_cloud_async() await create_metrics_query_client_async() + await create_metrics_query_client_sovereign_cloud_async() if __name__ == '__main__': diff --git a/sdk/monitor/azure-monitor-query/samples/sample_authentication.py b/sdk/monitor/azure-monitor-query/samples/sample_authentication.py index 00f148065b6b..d2c7ab28fc6c 100644 --- a/sdk/monitor/azure-monitor-query/samples/sample_authentication.py +++ b/sdk/monitor/azure-monitor-query/samples/sample_authentication.py @@ -23,6 +23,16 @@ def create_logs_query_client(): # [END create_logs_query_client] +def create_logs_query_client_sovereign_cloud(): + # [START create_logs_query_client_sovereign_cloud] + from azure.identity import AzureAuthorityHosts, DefaultAzureCredential + from azure.monitor.query import LogsQueryClient + + credential = DefaultAzureCredential(authority=AzureAuthorityHosts.AZURE_GOVERNMENT) + client = LogsQueryClient(credential, endpoint="https://api.loganalytics.us/v1") + # [END create_logs_query_client_sovereign_cloud] + + def create_metrics_query_client(): # [START create_metrics_query_client] from azure.identity import DefaultAzureCredential @@ -33,6 +43,18 @@ def create_metrics_query_client(): # [END create_metrics_query_client] +def create_metrics_query_client_sovereign_cloud(): + # [START create_metrics_query_client_sovereign_cloud] + from azure.identity import AzureAuthorityHosts, DefaultAzureCredential + from azure.monitor.query import MetricsQueryClient + + credential = DefaultAzureCredential(authority=AzureAuthorityHosts.AZURE_GOVERNMENT) + client = MetricsQueryClient(credential, endpoint="https://management.usgovcloudapi.net") + # [END create_metrics_query_client_sovereign_cloud] + + if __name__ == '__main__': create_logs_query_client() + create_logs_query_client_sovereign_cloud() create_metrics_query_client() + create_metrics_query_client_sovereign_cloud()