|
| 1 | +# Azure Purview Administration client library for Python |
| 2 | + |
| 3 | +Azure Purview is a fully managed cloud service. |
| 4 | + |
| 5 | +**Please rely heavily on the [service's documentation][account_product_documentation] to use this library** |
| 6 | + |
| 7 | +[Source code][source_code] | [Package (PyPI)][account_pypi] | [API reference documentation][account_ref_docs]| [Product documentation][account_product_documentation] |
| 8 | + |
| 9 | +## _Disclaimer_ |
| 10 | + |
| 11 | +_Azure SDK Python packages support for Python 2.7 is ending 01 January 2022. For more information and questions, please refer to https://github.com/Azure/azure-sdk-for-python/issues/20691_ |
| 12 | + |
| 13 | +## Getting started |
| 14 | + |
| 15 | +### Prerequisites |
| 16 | + |
| 17 | +- Python 2.7, or 3.6 or later is required to use this package. |
| 18 | +- You must have an [Azure subscription][azure_subscription] and a [Purview][purview_resource] to use this package. |
| 19 | + |
| 20 | +#### Create a Purview Resource |
| 21 | + |
| 22 | +Follow [these][purview_resource] instructions to create your Purview resource |
| 23 | + |
| 24 | +### Install the package |
| 25 | + |
| 26 | +Install the Azure Purview Account client library for Python with [pip][pip]: |
| 27 | + |
| 28 | +```bash |
| 29 | +pip install azure-purview-administration |
| 30 | +``` |
| 31 | + |
| 32 | +### Authenticate the client |
| 33 | + |
| 34 | +To use an [Azure Active Directory (AAD) token credential][authenticate_with_token], |
| 35 | +provide an instance of the desired credential type obtained from the |
| 36 | +[azure-identity][azure_identity_credentials] library. |
| 37 | + |
| 38 | +To authenticate with AAD, you must first [pip][pip] install [`azure-identity`][azure_identity_pip] and |
| 39 | +[enable AAD authentication on your Purview resource][enable_aad] |
| 40 | + |
| 41 | +After setup, you can choose which type of [credential][azure_identity_credentials] from azure.identity to use. |
| 42 | +As an example, [DefaultAzureCredential][default_azure_credential] |
| 43 | +can be used to authenticate the client: |
| 44 | + |
| 45 | +Set the values of the client ID, tenant ID, and client secret of the AAD application as environment variables: |
| 46 | +AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET |
| 47 | + |
| 48 | +Use the returned token credential to authenticate the client: |
| 49 | + |
| 50 | +```python |
| 51 | +from azure.purview.administration.account import PurviewAccountClient |
| 52 | +from azure.purview.administration.metadatapolicies import PurviewMetadataPoliciesClient |
| 53 | +from azure.identity import DefaultAzureCredential |
| 54 | + |
| 55 | +credential = DefaultAzureCredential() |
| 56 | +endpoint = "https://<my-account-name>.purview.azure.com" |
| 57 | +account_client = PurviewAccountClient(endpoint=endpoint, credential=credential) |
| 58 | +metadatapolicy_client = PurviewMetadataPoliciesClient(endpoint=endpoint, credential=credential) |
| 59 | +``` |
| 60 | + |
| 61 | +## Key concepts |
| 62 | + |
| 63 | +### Client |
| 64 | + |
| 65 | +The package contains two kinds of client: `PurviewAccountClient` and `PurviewMetadataPoliciesClient`. You could use them |
| 66 | +with one package according to your requirements. |
| 67 | + |
| 68 | +## Examples |
| 69 | + |
| 70 | +The following section shows you how to initialize and authenticate your client, then list all of your keys. |
| 71 | + |
| 72 | +- [Get Keys](#get-keys "Get All Keys") |
| 73 | + |
| 74 | +### Get Keys |
| 75 | + |
| 76 | +```python |
| 77 | +from azure.purview.administration.account import PurviewAccountClient |
| 78 | +from azure.identity import DefaultAzureCredential |
| 79 | + |
| 80 | +credential = DefaultAzureCredential() |
| 81 | +client = PurviewAccountClient(endpoint="https://<my-account-name>.purview.azure.com", credential=credential) |
| 82 | +response = client.accounts.get_access_keys() |
| 83 | +print(response) |
| 84 | +``` |
| 85 | + |
| 86 | +The following section shows you how to initialize and authenticate your client, then list all of your roles. |
| 87 | + |
| 88 | +- [List_Roles](#list-roles "List Roles") |
| 89 | + |
| 90 | +### List Roles |
| 91 | + |
| 92 | +```python |
| 93 | +from azure.purview.administration.metadatapolicies import PurviewMetadataPoliciesClient |
| 94 | +from azure.identity import DefaultAzureCredential |
| 95 | + |
| 96 | +credential = DefaultAzureCredential() |
| 97 | +client = PurviewMetadataPoliciesClient(endpoint="https://<my-account-name>.purview.azure.com", credential=credential) |
| 98 | +response = client.metadata_roles.list() |
| 99 | +result = [item for item in response] |
| 100 | +print(result) |
| 101 | +``` |
| 102 | + |
| 103 | +## Troubleshooting |
| 104 | + |
| 105 | +### General |
| 106 | + |
| 107 | +The Purview client will raise exceptions if status code of your responses is not defined. |
| 108 | + |
| 109 | +### Logging |
| 110 | + |
| 111 | +This library uses the standard |
| 112 | +[logging][python_logging] library for logging. |
| 113 | +Basic information about HTTP sessions (URLs, headers, etc.) is logged at INFO |
| 114 | +level. |
| 115 | + |
| 116 | +Detailed DEBUG level logging, including request/response bodies and unredacted |
| 117 | +headers, can be enabled on a client with the `logging_enable` keyword argument: |
| 118 | + |
| 119 | +```python |
| 120 | +import sys |
| 121 | +import logging |
| 122 | +from azure.identity import DefaultAzureCredential |
| 123 | +from azure.purview.administration.account import PurviewAccountClient |
| 124 | + |
| 125 | +# Create a logger for the 'azure' SDK |
| 126 | +logger = logging.getLogger('azure') |
| 127 | +logger.setLevel(logging.DEBUG) |
| 128 | + |
| 129 | +# Configure a console output |
| 130 | +handler = logging.StreamHandler(stream=sys.stdout) |
| 131 | +logger.addHandler(handler) |
| 132 | + |
| 133 | +endpoint = "https://<my-account-name>.purview.azure.com" |
| 134 | +credential = DefaultAzureCredential() |
| 135 | + |
| 136 | +# This client will log detailed information about its HTTP sessions, at DEBUG level |
| 137 | +client = PurviewAccountClient(endpoint=endpoint, credential=credential, logging_enable=True) |
| 138 | +``` |
| 139 | + |
| 140 | +Similarly, `logging_enable` can enable detailed logging for a single call, |
| 141 | +even when it isn't enabled for the client: |
| 142 | + |
| 143 | +```python |
| 144 | +result = client.accounts.get_access_keys(logging_enable=True) |
| 145 | +``` |
| 146 | + |
| 147 | +## Next steps |
| 148 | + |
| 149 | +For more generic samples, see our [client docs][request_builders_and_client]. |
| 150 | + |
| 151 | +## Contributing |
| 152 | + |
| 153 | +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 [cla.microsoft.com][cla]. |
| 154 | + |
| 155 | +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. |
| 156 | + |
| 157 | +This project has adopted the [Microsoft Open Source Code of Conduct ][code_of_conduct]. For more information see the [Code of Conduct FAQ ][coc_faq] or contact [[email protected]][coc_contact] with any additional questions or comments. |
| 158 | + |
| 159 | +<!-- LINKS --> |
| 160 | + |
| 161 | +[source_code]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/purview/ |
| 162 | +[account_pypi]: https://pypi.org/project/azure-purview-catalog/#history |
| 163 | +[account_ref_docs]: https://azure.github.io/azure-sdk-for-python/ |
| 164 | +[account_product_documentation]: https://azure.microsoft.com/services/purview/ |
| 165 | +[azure_subscription]: https://azure.microsoft.com/free/ |
| 166 | +[purview_resource]: https://docs.microsoft.com/azure/purview/create-catalog-portal |
| 167 | +[pip]: https://pypi.org/project/pip/ |
| 168 | +[authenticate_with_token]: https://docs.microsoft.com/azure/cognitive-services/authentication?tabs=powershell#authenticate-with-an-authentication-token |
| 169 | +[azure_identity_credentials]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/identity/azure-identity#credentials |
| 170 | +[azure_identity_pip]: https://pypi.org/project/azure-identity/ |
| 171 | +[default_azure_credential]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/identity/azure-identity#defaultazurecredential |
| 172 | +[enable_aad]: https://docs.microsoft.com/azure/purview/create-catalog-portal#add-a-security-principal-to-a-data-plane-role |
| 173 | +[python_logging]: https://docs.python.org/3.5/library/logging.html |
| 174 | +[cla]: https://cla.microsoft.com |
| 175 | +[code_of_conduct]: https://opensource.microsoft.com/codeofconduct/ |
| 176 | +[coc_faq]: https://opensource.microsoft.com/codeofconduct/faq/ |
| 177 | +[coc_contact]: mailto:[email protected] |
| 178 | +[request_builders_and_client]: https://aka.ms/azsdk/python/protocol/quickstart |
0 commit comments