# Azure Purview Sharing client library for Python
Microsoft Purview Share is a fully managed cloud service.
**Please rely heavily on the [service's documentation][sharing_product_documentation] and our [protocol client docs][request_builders_and_client] to use this library**
[Source code][source_code] | [Package (PyPI)][client_pypi_package] | [Product documentation][sharing_product_documentation]
## Getting started
### Install the package
Install the Azure Purview Sharing client library for Python with [pip][pip]:
```bash
pip install azure-purview-sharing
```
### Prerequisites
- You must have an [Azure subscription][azure_subscription] and a [Purview resource][purview_resource] to use this package.
- Python 3.6 or later is required to use this package.
### Authenticate the client
#### Using Azure Active Directory
This document demonstrates using [DefaultAzureCredential][default_azure_credential] to authenticate via Azure Active Directory. However, any of the credentials offered by the [azure-identity package][azure_identity_pip] will be accepted. See the [azure-identity][azure_identity_credentials] documentation for more information about other credentials.
Once you have chosen and configured your credential, you can create instances of the `PurviewSharingClient`.
```python
from azure.purview.sharing import PurviewSharingClient
from azure.identity import DefaultAzureCredential
credential = DefaultAzureCredential()
client = PurviewSharingClient(endpoint="https://<my-account-name>.purview.azure.com", credential=credential)
```
## Key concepts
**Data Provider:** A data provider is the individual who creates a share by selecting a data source, choosing which files and folders to share, and who to share them with. Microsoft Purview then sends an invitation to each data consumer.
**Data Consumer:** A data consumer is the individual who accepts the invitation by specifying a target storage account in their own Azure subscription that they'll use to access the shared data.
## Examples
Table of Contents:
- [Data Provider](#data-provider-examples)
- [Data Consumer](#data-consumer-examples)
- [Share Resource](#share-resource-examples)
## Data Provider Examples
The following code examples demonstrate how data providers can use the Microsoft Azure Python SDK for Purview Sharing to manage their sharing activity.
### Create a Sent Share Client
```python Snippet:create_a_sent_share_client
import os, uuid, json
from azure.purview.sharing import PurviewSharingClient
from azure.identity import DefaultAzureCredential
endpoint = os.environ["ENDPOINT"]
credential = DefaultAzureCredential()
client = PurviewSharingClient(endpoint=endpoint, credential=credential)
```
### Create Share
To begin sharing data, the data provider must first create a sent share that identifies the data they would like to share.
```python Snippet:create_a_sent_share
import os, uuid, json
from azure.purview.sharing import PurviewSharingClient
from azure.identity import DefaultAzureCredential
endpoint = os.environ["ENDPOINT"]
credential = DefaultAzureCredential()
client = PurviewSharingClient(endpoint=endpoint, credential=credential)
sent_share_id = uuid.uuid4()
artifact = {
"properties": {
"paths": [
{
"containerName": "container-name",
"receiverPath": "shared-file-name.txt",
"senderPath": "original/file-name.txt"
}
]
},
"storeKind": "AdlsGen2Account",
"storeReference": {
"referenceName": "/subscriptions/{subscription-id}/resourceGroups/provider-storage-rg/providers/Microsoft.Storage/storageAccounts/providerstorage",
"type": "ArmResourceReference"
}
}
sent_share = {
"properties": {
"artifact": artifact,
"displayName": "sampleShare",
"description": "A sample share"
},
"shareKind": "InPlace"
}
request = client.sent_shares.begin_create_or_replace(
str(sent_share_id),
sent_share=sent_share)
response = request.result()
print(response)
```
### Send Share Invitation to a User
After creating a sent share, the data provider can extend invitations to consumers who may then view the shared data. In this example, an invitation is extended to an individual by specifying their email address.
```python Snippet:send_a_user_invitation
import os, uuid
from azure.purview.sharing import PurviewSharingClient
from azure.identity import DefaultAzureCredential
from datetime import date
endpoint = os.environ["ENDPOINT"]
credential = DefaultAzureCredential()
client = PurviewSharingClient(endpoint=endpoint, credential=credential)
sent_share_id = uuid.uuid4()
sent_share_invitation_id = uuid.uuid4()
consumerEmail = "consumer@contoso.com"
today = date.today()
invitation = {
"invitationKind": "User",
"properties": {
"targetEmail": consumerEmail,
"notify": "true",
"expirationDate": date(today.year+1,today.month,today.day).strftime("%Y-%m-%d") + " 00:00:00"
}
}
invitation_request = client.sent_shares.create_invitation(
sent_share_id=str(sent_share_id),
sent_share_invitation_id=str(sent_share_invitation_id),
sent_share_invitation=invitation)
invitation_response = invitation_request.result()
created_invitation = json.loads(invitation_response)
print(created_invitation)
```
### Send Share Invitation to a Service
Data providers can also extend invitations to services or applications by specifying the tenant id and object id of the service. _The object id used for sending an invitation to a service must be the object id associated with the Enterprise Application (not the application registration)._
```python Snippet:send_a_service_invitation
import os, uuid
from azure.purview.sharing import PurviewSharingClient
from azure.identity import DefaultAzureCredential
endpoint = os.environ["ENDPOINT"]
credential = DefaultAzureCredential()
client = PurviewSharingClient(endpoint=endpoint, credential=credential)
targetActiveDirectoryId = uuid.uuid4()
targetObjectId = uuid.uuid4()
sent_share_invitation = {
"invitationKind": "Service",
"properties": {
"targetActiveDirectoryId": str(targetActiveDirectoryId),
"targetObjectId": str(targetObjectId)
}
}
invitation_response = client.sent_shares.create_invitation(
sent_share_id=str(sent_share_id),
sent_share_invitation_id=str(sent_share_invitation_id),
sent_share_invitation=sent_share_invitation)
print(invitation_response)
```
### Get Sent Share
After creating a sent share, data providers can retrieve it.
```python Snippet:get_a_sent_share
import os, uuid
from azure.purview.sharing import PurviewSharingClient
from azure.identity import DefaultAzureCredential
endpoint = os.environ["ENDPOINT"]
credential = DefaultAzureCredential()
sent_share_id = uuid.uuid4()
client = PurviewSharingClient(endpoint=endpoint, credential=credential)
retrieved_sent_share = client.sent_shares.get(sent_share_id=str(sent_share_id))
print(retrieved_sent_share)
```
### List Sent Shares
Data providers can also retrieve a list of the sent shares they have created.
```python Snippet:get_all_sent_shares
import os
from azure.purview.sharing import PurviewSharingClient
from azure.identity import DefaultAzureCredential
endpoint = os.environ["ENDPOINT"]
credential = DefaultAzureCredential()
client = PurviewSharingClient(endpoint=endpoint, credential=credential)
provider_storage_account_resource_id = "/subscriptions/{subscription-id}/resourceGroups/provider-storage-rg/providers/Microsoft.Storage/storageAccounts/providerstorage"
list_request = client.sent_shares.list(
reference_name=provider_storage_account_resource_id,
orderby="properties/createdAt desc")
for list_response in list_request:
print(list_response)
```
### Delete Sent Share
A sent share can be deleted by the data provider to stop sharing their data with all data consumers.
```python Snippet:delete_a_sent_share
import os
from azure.purview.sharing import PurviewSharingClient
from azure.identity import DefaultAzureCredential
endpoint = os.environ["ENDPOINT"]
credential = DefaultAzureCredential()
client = PurviewSharingClient(endpoint=endpoint,credential=credential)
sent_share_id = uuid.uuid4()
delete_request = client.sent_shares.begin_delete(sent_share_id=str(sent_share_id))
delete_response = delete_request.result()
print(delete_response)
```
### Get Sent Share Invitation
After creating a sent share invitation, data providers can retrieve it.
```python Snippet:get_a_sent_share_invitation
import os, uuid, json
from azure.purview.sharing import PurviewSharingClient
from azure.identity import DefaultAzureCredential
endpoint = os.environ["ENDPOINT"]
credential = DefaultAzureCredential()
client = PurviewSharingClient(endpoint=endpoint,credential=credential)
sent_share_id = uuid.uuid4()
sent_share_invitation_id = uuid.uuid4()
get_invitation_response = client.sent_shares.get_invitation(
sent_share_id=str(sent_share_id),
sent_share_invitation_id=str(sent_share_invitation_id))
retrieved_share_invitation = json.loads(get_invitation_response)
print(retrieved_share_invitation)
```
### List Sent Share Invitations
Data providers can also retrieve a list of the sent share invitations they have created.
```python Snippet:view_sent_invitations
import os, uuid, json
from azure.purview.sharing import PurviewSharingClient
from azure.identity import DefaultAzureCredential
endpoint = os.environ["ENDPOINT"]
credential = DefaultAzureCredential()
client = PurviewSharingClient(endpoint=endpoint, credential=credential)
sent_share_id = uuid.uuid4()
list_request = client.sent_shares.list_invitations(sent_share_id=str(sent_share_id))
for list_response in list_request:
print(list_response)
```
### Delete Sent Share Invitation
An individual sent share invitation can be deleted by the data provider to stop sharing their data with the specific data consumer to whom the invitation was addressed.
```python Snippet:delete_a_sent_share_invitation
import os, uuid, json
from azure.purview.sharing import PurviewSharingClient
from azure.identity import DefaultAzureCredential
endpoint = os.environ["ENDPOINT"]
credential = DefaultAzureCredential()
client = PurviewSharingClient(endpoint=endpoint,credential=credential)
sent_share_id = uuid.uuid4()
sent_share_invitation_id = uuid.uuid4()
delete_invitation_request = client.sent_shares.begin_delete_invitation(
sent_share_id=str(sent_share_id),
sent_share_invitation_id=str(sent_share_invitation_id))
delete_invitation_response = delete_invitation_request.result()
print(delete_invitation_response)
```
## Data Consumer Examples
The following code examples demonstrate how data consumers can use the Microsoft Azure Python SDK for Purview Sharing to manage their sharing activity.
### Create a Received Share Client
```python Snippet:create_received_share_client
import os
from azure.purview.sharing import PurviewSharingClient
from azure.identity import DefaultAzureCredential
endpoint = os.environ["ENDPOINT"]
credential = DefaultAzureCredential()
client = PurviewSharingClient(endpoint=endpoint,credential=credential)
```
### List Detached Received Shares
To begin viewing data shared with them, a data consumer must first retrieve a list of detached received shares. Within this list, they can identify a detached received share to attach. A "detached" received share refers to a received share that has never been attached or has been detached.
```python Snippet:get_all_detached_received_shares
import os
from azure.purview.sharing import PurviewSharingClient
from azure.identity import DefaultAzureCredential
endpoint = os.environ["ENDPOINT"]
credential = DefaultAzureCredential()
client = PurviewSharingClient(endpoint=endpoint,credential=credential)
list_detached_response = client.received_shares.list_detached(orderby="properties/createdAt desc")
print(list_detached_response)
```
### Attach a Received Share
Once the data consumer has identified a received share, they can attach the received share to a location where they can access the shared data. If the received share is already attached, the shared data will be made accessible at the new location specified.
```python Snippet:attach_a_received_share
import os, json
from azure.purview.sharing import PurviewSharingClient
from azure.identity import DefaultAzureCredential
endpoint = os.environ["ENDPOINT"]
credential = DefaultAzureCredential()
client = PurviewSharingClient(endpoint=endpoint,credential=credential)
consumer_storage_account_resource_id = "/subscriptions/{subscription-id}/resourceGroups/consumer-storage-rg/providers/Microsoft.Storage/storageAccounts/consumerstorage"
list_detached_response = client.received_shares.list_detached(orderby="properties/createdAt desc")
received_share = next(x for x in list_detached_response)
store_reference = {
"referenceName": consumer_storage_account_resource_id,
"type": "ArmResourceReference"
}
sink = {
"properties": {
"containerName": "container-test",
"folder": "folder-test",
"mountPath": "mountPath-test",
},
"storeKind": "AdlsGen2Account",
"storeReference": store_reference
}
received_share['properties']['sink'] = sink
update_request = client.received_shares.begin_create_or_replace(
received_share['id'],
content_type="application/json",
content=json.dumps(received_share))
update_response = update_request.result()
print(update_response)
```
### Get Received Share
A data consumer can retrieve an individual received share.
```python Snippet:get_a_received_share
import os
from azure.purview.sharing import PurviewSharingClient
from azure.identity import DefaultAzureCredential
endpoint = os.environ["ENDPOINT"]
credential = DefaultAzureCredential()
client = PurviewSharingClient(endpoint=endpoint,credential=credential)
list_detached_response = client.received_shares.list_detached(orderby="properties/createdAt desc")
list_detached = json.loads(list_detached_response)
received_share = list_detached[0]
get_share_response = client.received_shares.get(received_share_id=received_share['id'])
retrieved_share = json.loads(get_share_response)
print(retrieved_share)
```
### List Attached Received Shares
Data consumers can also retrieve a list of their attached received shares.
```python Snippet:list_attached_received_shares
import os
from azure.purview.sharing import PurviewSharingClient
from azure.identity import DefaultAzureCredential
endpoint = os.environ["ENDPOINT"]
credential = DefaultAzureCredential()
client = PurviewSharingClient(endpoint=endpoint,credential=credential)
consumer_storage_account_resource_id = "/subscriptions/{subscription-id}/resourceGroups/consumer-storage-rg/providers/Microsoft.Storage/storageAccounts/consumerstorage"
list_attached_response = client.received_shares.list_attached(
reference_name=consumer_storage_account_resource_id,
orderby="properties/createdAt desc")
print(list_attached_response)
```
### Delete Received Share
A received share can be deleted by the data consumer to terminate their access to shared data.
```python Snippet:delete_a_received_share
import os
from azure.purview.sharing import PurviewSharingClient
from azure.identity import DefaultAzureCredential
endpoint = os.environ["ENDPOINT"]
credential = DefaultAzureCredential()
client = PurviewSharingClient(endpoint=endpoint,credential=credential)
delete_received_share_request = client.received_shares.begin_delete(received_share_id=received_share['id'])
delete_received_share_response = delete_received_share_request.result()
print(delete_received_share_response)
```
## Share Resource Examples
The following code examples demonstrate how to use the Microsoft Azure Python SDK for Purview Sharing to view share resources. A share resource is the underlying resource from which a provider shares data or the destination where a consumer attaches data shared with them.
### List Share Resources
A list of share resources can be retrieved to view all resources within an account where sharing activities have taken place.
```python Snippet:list_share_resources
import os
from azure.purview.sharing import PurviewSharingClient
from azure.identity import DefaultAzureCredential
endpoint = os.environ["ENDPOINT"]
credential = DefaultAzureCredential()
client = PurviewSharingClient(endpoint=endpoint,credential=credential)
list_request = client.share_resources.list(
filter="properties/storeKind eq 'AdlsGen2Account'",
orderby="properties/createdAt desc")
for list_response in list_request:
print(list_response)
```
## Troubleshooting
### General
The Purview Catalog client will raise exceptions defined in [Azure Core][azure_core] if you call `.raise_for_status()` on your responses.
### Logging
This library uses the standard
[logging][python_logging] library for logging.
Basic information about HTTP sessions (URLs, headers, etc.) is logged at INFO
level.
Detailed DEBUG level logging, including request/response bodies and unredacted
headers, can be enabled on a client with the `logging_enable` keyword argument:
```python
import sys
import logging
from azure.identity import DefaultAzureCredential
from azure.purview.sharing import PurviewSharingClient
# Create a logger for the 'azure' SDK
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)
# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)
endpoint = "https://<my-account-name>.share.purview.azure.com"
credential = DefaultAzureCredential()
# This client will log detailed information about its HTTP sessions, at DEBUG level
client = PurviewSharingClient(endpoint=endpoint, credential=credential, logging_enable=True)
```
Similarly, `logging_enable` can enable detailed logging for a single `send_request` call,
even when it isn't enabled for the client:
```python
result = client.types.get_all_type_definitions(logging_enable=True)
```
## Next steps
For more generic samples, see our [samples][samples].
## Contributing
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].
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][code_of_conduct]. For more information see the [Code of Conduct FAQ][coc_faq] or contact [opencode@microsoft.com][coc_contact] with any additional questions or comments.
<!-- LINKS -->
[source_code]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/purview/azure-purview-sharing/azure/purview/sharing
[client_pypi_package]: https://aka.ms/azsdk/python/purviewsharing/pypi
[sharing_ref_docs]: https://aka.ms/azsdk/python/purviewcatalog/ref-docs
[sharing_product_documentation]: https://azure.microsoft.com/services/purview/
[azure_subscription]: https://azure.microsoft.com/free/
[purview_resource]: https://docs.microsoft.com/azure/purview
[pip]: https://pypi.org/project/pip/
[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://azuresdkdocs.blob.core.windows.net/$web/python/azure-identity/latest/azure.identity.html#azure.identity.DefaultAzureCredential
[request_builders_and_client]: https://aka.ms/azsdk/python/protocol/quickstart
[enable_aad]: https://docs.microsoft.com/azure/purview/
[azure_core]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/core/azure-core/README.md
[python_logging]: https://docs.python.org/3.5/library/logging.html
[cla]: https://cla.microsoft.com
[code_of_conduct]: https://opensource.microsoft.com/codeofconduct/
[coc_faq]: https://opensource.microsoft.com/codeofconduct/faq/
[coc_contact]: mailto:opencode@microsoft.com
[samples]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/purview/azure-purview-sharing/samples
Raw data
{
"_id": null,
"home_page": "https://github.com/Azure/azure-sdk-for-python/tree/main/sdk",
"name": "azure-purview-sharing",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "azure,azure sdk",
"author": "Microsoft Corporation",
"author_email": "azpysdkhelp@microsoft.com",
"download_url": "https://files.pythonhosted.org/packages/64/e3/0c235e7c70ff731c471e1b061ef54398f12d0d59a4466530dd17ac4f5edb/azure-purview-sharing-1.0.0b3.zip",
"platform": null,
"description": "# Azure Purview Sharing client library for Python\n\nMicrosoft Purview Share is a fully managed cloud service.\n\n**Please rely heavily on the [service's documentation][sharing_product_documentation] and our [protocol client docs][request_builders_and_client] to use this library**\n\n[Source code][source_code] | [Package (PyPI)][client_pypi_package] | [Product documentation][sharing_product_documentation]\n\n## Getting started\n\n### Install the package\n\nInstall the Azure Purview Sharing client library for Python with [pip][pip]:\n\n```bash\npip install azure-purview-sharing\n```\n\n### Prerequisites\n\n- You must have an [Azure subscription][azure_subscription] and a [Purview resource][purview_resource] to use this package.\n- Python 3.6 or later is required to use this package.\n\n### Authenticate the client\n\n#### Using Azure Active Directory\n\nThis document demonstrates using [DefaultAzureCredential][default_azure_credential] to authenticate via Azure Active Directory. However, any of the credentials offered by the [azure-identity package][azure_identity_pip] will be accepted. See the [azure-identity][azure_identity_credentials] documentation for more information about other credentials.\n\nOnce you have chosen and configured your credential, you can create instances of the `PurviewSharingClient`.\n\n```python\nfrom azure.purview.sharing import PurviewSharingClient\nfrom azure.identity import DefaultAzureCredential\n\ncredential = DefaultAzureCredential()\nclient = PurviewSharingClient(endpoint=\"https://<my-account-name>.purview.azure.com\", credential=credential)\n```\n\n## Key concepts\n\n**Data Provider:** A data provider is the individual who creates a share by selecting a data source, choosing which files and folders to share, and who to share them with. Microsoft Purview then sends an invitation to each data consumer.\n\n**Data Consumer:** A data consumer is the individual who accepts the invitation by specifying a target storage account in their own Azure subscription that they'll use to access the shared data.\n\n## Examples\n\nTable of Contents: \n- [Data Provider](#data-provider-examples)\n- [Data Consumer](#data-consumer-examples)\n- [Share Resource](#share-resource-examples)\n\n## Data Provider Examples\n\nThe following code examples demonstrate how data providers can use the Microsoft Azure Python SDK for Purview Sharing to manage their sharing activity.\n\n### Create a Sent Share Client\n\n```python Snippet:create_a_sent_share_client\nimport os, uuid, json\n\nfrom azure.purview.sharing import PurviewSharingClient\nfrom azure.identity import DefaultAzureCredential\n\nendpoint = os.environ[\"ENDPOINT\"]\ncredential = DefaultAzureCredential()\n\nclient = PurviewSharingClient(endpoint=endpoint, credential=credential)\n```\n\n### Create Share\n\nTo begin sharing data, the data provider must first create a sent share that identifies the data they would like to share.\n\n```python Snippet:create_a_sent_share\nimport os, uuid, json\n\nfrom azure.purview.sharing import PurviewSharingClient\nfrom azure.identity import DefaultAzureCredential\n\nendpoint = os.environ[\"ENDPOINT\"]\ncredential = DefaultAzureCredential()\n\nclient = PurviewSharingClient(endpoint=endpoint, credential=credential)\n\nsent_share_id = uuid.uuid4()\n\nartifact = {\n \"properties\": {\n \"paths\": [\n {\n \"containerName\": \"container-name\",\n \"receiverPath\": \"shared-file-name.txt\",\n \"senderPath\": \"original/file-name.txt\"\n }\n ]\n },\n \"storeKind\": \"AdlsGen2Account\",\n \"storeReference\": {\n \"referenceName\": \"/subscriptions/{subscription-id}/resourceGroups/provider-storage-rg/providers/Microsoft.Storage/storageAccounts/providerstorage\",\n \"type\": \"ArmResourceReference\"\n }\n}\n\nsent_share = {\n \"properties\": {\n \"artifact\": artifact,\n \"displayName\": \"sampleShare\",\n \"description\": \"A sample share\"\n },\n \"shareKind\": \"InPlace\"\n}\n\nrequest = client.sent_shares.begin_create_or_replace(\n str(sent_share_id),\n sent_share=sent_share)\n\nresponse = request.result()\nprint(response)\n```\n\n### Send Share Invitation to a User\n\nAfter creating a sent share, the data provider can extend invitations to consumers who may then view the shared data. In this example, an invitation is extended to an individual by specifying their email address.\n\n```python Snippet:send_a_user_invitation\nimport os, uuid\n\nfrom azure.purview.sharing import PurviewSharingClient\nfrom azure.identity import DefaultAzureCredential\nfrom datetime import date\n\nendpoint = os.environ[\"ENDPOINT\"]\ncredential = DefaultAzureCredential()\n\nclient = PurviewSharingClient(endpoint=endpoint, credential=credential)\n\nsent_share_id = uuid.uuid4()\nsent_share_invitation_id = uuid.uuid4()\n\nconsumerEmail = \"consumer@contoso.com\"\ntoday = date.today()\ninvitation = {\n \"invitationKind\": \"User\",\n \"properties\": {\n \"targetEmail\": consumerEmail,\n \"notify\": \"true\",\n \"expirationDate\": date(today.year+1,today.month,today.day).strftime(\"%Y-%m-%d\") + \" 00:00:00\"\n }\n}\n\ninvitation_request = client.sent_shares.create_invitation(\n sent_share_id=str(sent_share_id),\n sent_share_invitation_id=str(sent_share_invitation_id),\n sent_share_invitation=invitation)\n\ninvitation_response = invitation_request.result()\ncreated_invitation = json.loads(invitation_response)\nprint(created_invitation)\n```\n### Send Share Invitation to a Service\n\nData providers can also extend invitations to services or applications by specifying the tenant id and object id of the service. _The object id used for sending an invitation to a service must be the object id associated with the Enterprise Application (not the application registration)._\n\n```python Snippet:send_a_service_invitation\nimport os, uuid\n\nfrom azure.purview.sharing import PurviewSharingClient\nfrom azure.identity import DefaultAzureCredential\n\nendpoint = os.environ[\"ENDPOINT\"]\ncredential = DefaultAzureCredential()\n\nclient = PurviewSharingClient(endpoint=endpoint, credential=credential)\n\ntargetActiveDirectoryId = uuid.uuid4()\ntargetObjectId = uuid.uuid4()\n\nsent_share_invitation = {\n \"invitationKind\": \"Service\",\n \"properties\": {\n \"targetActiveDirectoryId\": str(targetActiveDirectoryId),\n \"targetObjectId\": str(targetObjectId)\n }\n}\n\ninvitation_response = client.sent_shares.create_invitation(\n sent_share_id=str(sent_share_id),\n sent_share_invitation_id=str(sent_share_invitation_id),\n sent_share_invitation=sent_share_invitation)\n\nprint(invitation_response)\n```\n\n### Get Sent Share\n\nAfter creating a sent share, data providers can retrieve it.\n\n```python Snippet:get_a_sent_share\nimport os, uuid\n\nfrom azure.purview.sharing import PurviewSharingClient\nfrom azure.identity import DefaultAzureCredential\n\nendpoint = os.environ[\"ENDPOINT\"]\ncredential = DefaultAzureCredential()\nsent_share_id = uuid.uuid4()\n\nclient = PurviewSharingClient(endpoint=endpoint, credential=credential)\n\nretrieved_sent_share = client.sent_shares.get(sent_share_id=str(sent_share_id))\nprint(retrieved_sent_share)\n```\n\n### List Sent Shares\n\nData providers can also retrieve a list of the sent shares they have created.\n\n```python Snippet:get_all_sent_shares\nimport os\n\nfrom azure.purview.sharing import PurviewSharingClient\nfrom azure.identity import DefaultAzureCredential\n\nendpoint = os.environ[\"ENDPOINT\"]\ncredential = DefaultAzureCredential()\n\nclient = PurviewSharingClient(endpoint=endpoint, credential=credential)\n\nprovider_storage_account_resource_id = \"/subscriptions/{subscription-id}/resourceGroups/provider-storage-rg/providers/Microsoft.Storage/storageAccounts/providerstorage\"\n\nlist_request = client.sent_shares.list(\n reference_name=provider_storage_account_resource_id,\n orderby=\"properties/createdAt desc\")\n\nfor list_response in list_request:\n print(list_response)\n```\n\n### Delete Sent Share\n\nA sent share can be deleted by the data provider to stop sharing their data with all data consumers.\n\n```python Snippet:delete_a_sent_share\nimport os\n\nfrom azure.purview.sharing import PurviewSharingClient\nfrom azure.identity import DefaultAzureCredential\n\nendpoint = os.environ[\"ENDPOINT\"]\ncredential = DefaultAzureCredential()\n\nclient = PurviewSharingClient(endpoint=endpoint,credential=credential)\n\nsent_share_id = uuid.uuid4()\n\ndelete_request = client.sent_shares.begin_delete(sent_share_id=str(sent_share_id))\ndelete_response = delete_request.result()\nprint(delete_response)\n```\n\n### Get Sent Share Invitation\n\nAfter creating a sent share invitation, data providers can retrieve it.\n\n```python Snippet:get_a_sent_share_invitation\nimport os, uuid, json\n\nfrom azure.purview.sharing import PurviewSharingClient\nfrom azure.identity import DefaultAzureCredential\n\nendpoint = os.environ[\"ENDPOINT\"]\ncredential = DefaultAzureCredential()\n\nclient = PurviewSharingClient(endpoint=endpoint,credential=credential)\n\nsent_share_id = uuid.uuid4()\nsent_share_invitation_id = uuid.uuid4()\n\nget_invitation_response = client.sent_shares.get_invitation(\n sent_share_id=str(sent_share_id), \n sent_share_invitation_id=str(sent_share_invitation_id))\n\nretrieved_share_invitation = json.loads(get_invitation_response)\nprint(retrieved_share_invitation)\n```\n\n### List Sent Share Invitations\n\nData providers can also retrieve a list of the sent share invitations they have created.\n\n```python Snippet:view_sent_invitations\nimport os, uuid, json\n\nfrom azure.purview.sharing import PurviewSharingClient\nfrom azure.identity import DefaultAzureCredential\n\nendpoint = os.environ[\"ENDPOINT\"]\ncredential = DefaultAzureCredential()\n\nclient = PurviewSharingClient(endpoint=endpoint, credential=credential)\n\nsent_share_id = uuid.uuid4()\n\nlist_request = client.sent_shares.list_invitations(sent_share_id=str(sent_share_id))\n\nfor list_response in list_request:\n print(list_response)\n```\n\n### Delete Sent Share Invitation\n\nAn individual sent share invitation can be deleted by the data provider to stop sharing their data with the specific data consumer to whom the invitation was addressed.\n\n```python Snippet:delete_a_sent_share_invitation\nimport os, uuid, json\n\nfrom azure.purview.sharing import PurviewSharingClient\nfrom azure.identity import DefaultAzureCredential\n\nendpoint = os.environ[\"ENDPOINT\"]\ncredential = DefaultAzureCredential()\n\nclient = PurviewSharingClient(endpoint=endpoint,credential=credential)\n\nsent_share_id = uuid.uuid4()\nsent_share_invitation_id = uuid.uuid4()\n\ndelete_invitation_request = client.sent_shares.begin_delete_invitation(\n sent_share_id=str(sent_share_id),\n sent_share_invitation_id=str(sent_share_invitation_id))\ndelete_invitation_response = delete_invitation_request.result()\nprint(delete_invitation_response)\n```\n\n## Data Consumer Examples\n\nThe following code examples demonstrate how data consumers can use the Microsoft Azure Python SDK for Purview Sharing to manage their sharing activity.\n\n### Create a Received Share Client\n\n```python Snippet:create_received_share_client\nimport os\n\nfrom azure.purview.sharing import PurviewSharingClient\nfrom azure.identity import DefaultAzureCredential\n\nendpoint = os.environ[\"ENDPOINT\"]\ncredential = DefaultAzureCredential()\n\nclient = PurviewSharingClient(endpoint=endpoint,credential=credential)\n```\n\n### List Detached Received Shares\n\nTo begin viewing data shared with them, a data consumer must first retrieve a list of detached received shares. Within this list, they can identify a detached received share to attach. A \"detached\" received share refers to a received share that has never been attached or has been detached.\n\n```python Snippet:get_all_detached_received_shares\nimport os\n\nfrom azure.purview.sharing import PurviewSharingClient\nfrom azure.identity import DefaultAzureCredential\n\nendpoint = os.environ[\"ENDPOINT\"]\ncredential = DefaultAzureCredential()\n\nclient = PurviewSharingClient(endpoint=endpoint,credential=credential)\n\nlist_detached_response = client.received_shares.list_detached(orderby=\"properties/createdAt desc\")\nprint(list_detached_response)\n```\n\n### Attach a Received Share\n\nOnce the data consumer has identified a received share, they can attach the received share to a location where they can access the shared data. If the received share is already attached, the shared data will be made accessible at the new location specified.\n\n```python Snippet:attach_a_received_share\nimport os, json\n\nfrom azure.purview.sharing import PurviewSharingClient\nfrom azure.identity import DefaultAzureCredential\n\nendpoint = os.environ[\"ENDPOINT\"]\ncredential = DefaultAzureCredential()\n\nclient = PurviewSharingClient(endpoint=endpoint,credential=credential)\n\nconsumer_storage_account_resource_id = \"/subscriptions/{subscription-id}/resourceGroups/consumer-storage-rg/providers/Microsoft.Storage/storageAccounts/consumerstorage\"\n\nlist_detached_response = client.received_shares.list_detached(orderby=\"properties/createdAt desc\")\nreceived_share = next(x for x in list_detached_response)\n\nstore_reference = {\n \"referenceName\": consumer_storage_account_resource_id,\n \"type\": \"ArmResourceReference\"\n}\n\nsink = {\n \"properties\": {\n \"containerName\": \"container-test\",\n \"folder\": \"folder-test\",\n \"mountPath\": \"mountPath-test\",\n },\n \"storeKind\": \"AdlsGen2Account\",\n \"storeReference\": store_reference\n}\n\nreceived_share['properties']['sink'] = sink\n\nupdate_request = client.received_shares.begin_create_or_replace(\n received_share['id'],\n content_type=\"application/json\",\n content=json.dumps(received_share))\n\nupdate_response = update_request.result()\nprint(update_response)\n```\n\n### Get Received Share\n\nA data consumer can retrieve an individual received share.\n\n```python Snippet:get_a_received_share\nimport os\n\nfrom azure.purview.sharing import PurviewSharingClient\nfrom azure.identity import DefaultAzureCredential\n\nendpoint = os.environ[\"ENDPOINT\"]\ncredential = DefaultAzureCredential()\n\nclient = PurviewSharingClient(endpoint=endpoint,credential=credential)\n\nlist_detached_response = client.received_shares.list_detached(orderby=\"properties/createdAt desc\")\nlist_detached = json.loads(list_detached_response)\nreceived_share = list_detached[0]\n\nget_share_response = client.received_shares.get(received_share_id=received_share['id'])\nretrieved_share = json.loads(get_share_response)\nprint(retrieved_share)\n```\n\n### List Attached Received Shares\n\nData consumers can also retrieve a list of their attached received shares.\n\n```python Snippet:list_attached_received_shares\nimport os\n\nfrom azure.purview.sharing import PurviewSharingClient\nfrom azure.identity import DefaultAzureCredential\n\nendpoint = os.environ[\"ENDPOINT\"]\ncredential = DefaultAzureCredential()\n\nclient = PurviewSharingClient(endpoint=endpoint,credential=credential)\n\nconsumer_storage_account_resource_id = \"/subscriptions/{subscription-id}/resourceGroups/consumer-storage-rg/providers/Microsoft.Storage/storageAccounts/consumerstorage\"\n\nlist_attached_response = client.received_shares.list_attached(\n reference_name=consumer_storage_account_resource_id,\n orderby=\"properties/createdAt desc\")\nprint(list_attached_response)\n```\n\n### Delete Received Share\n\nA received share can be deleted by the data consumer to terminate their access to shared data.\n\n```python Snippet:delete_a_received_share\nimport os\n\nfrom azure.purview.sharing import PurviewSharingClient\nfrom azure.identity import DefaultAzureCredential\n\nendpoint = os.environ[\"ENDPOINT\"]\ncredential = DefaultAzureCredential()\n\nclient = PurviewSharingClient(endpoint=endpoint,credential=credential)\n\ndelete_received_share_request = client.received_shares.begin_delete(received_share_id=received_share['id'])\ndelete_received_share_response = delete_received_share_request.result()\nprint(delete_received_share_response)\n```\n\n## Share Resource Examples\n\nThe following code examples demonstrate how to use the Microsoft Azure Python SDK for Purview Sharing to view share resources. A share resource is the underlying resource from which a provider shares data or the destination where a consumer attaches data shared with them.\n\n### List Share Resources\n\nA list of share resources can be retrieved to view all resources within an account where sharing activities have taken place.\n\n```python Snippet:list_share_resources\nimport os\n\nfrom azure.purview.sharing import PurviewSharingClient\nfrom azure.identity import DefaultAzureCredential\n\nendpoint = os.environ[\"ENDPOINT\"]\ncredential = DefaultAzureCredential()\n\nclient = PurviewSharingClient(endpoint=endpoint,credential=credential)\n\nlist_request = client.share_resources.list(\n filter=\"properties/storeKind eq 'AdlsGen2Account'\",\n orderby=\"properties/createdAt desc\")\n\nfor list_response in list_request:\n print(list_response)\n```\n\n## Troubleshooting\n\n### General\n\nThe Purview Catalog client will raise exceptions defined in [Azure Core][azure_core] if you call `.raise_for_status()` on your responses.\n\n### Logging\n\nThis library uses the standard\n[logging][python_logging] library for logging.\nBasic information about HTTP sessions (URLs, headers, etc.) is logged at INFO\nlevel.\n\nDetailed DEBUG level logging, including request/response bodies and unredacted\nheaders, can be enabled on a client with the `logging_enable` keyword argument:\n\n```python\nimport sys\nimport logging\nfrom azure.identity import DefaultAzureCredential\nfrom azure.purview.sharing import PurviewSharingClient\n\n# Create a logger for the 'azure' SDK\nlogger = logging.getLogger('azure')\nlogger.setLevel(logging.DEBUG)\n\n# Configure a console output\nhandler = logging.StreamHandler(stream=sys.stdout)\nlogger.addHandler(handler)\n\nendpoint = \"https://<my-account-name>.share.purview.azure.com\"\ncredential = DefaultAzureCredential()\n\n# This client will log detailed information about its HTTP sessions, at DEBUG level\nclient = PurviewSharingClient(endpoint=endpoint, credential=credential, logging_enable=True)\n```\n\nSimilarly, `logging_enable` can enable detailed logging for a single `send_request` call,\neven when it isn't enabled for the client:\n\n```python\nresult = client.types.get_all_type_definitions(logging_enable=True)\n```\n\n## Next steps\n\nFor more generic samples, see our [samples][samples].\n\n## Contributing\n\nThis 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].\n\nWhen 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.\n\nThis 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 [opencode@microsoft.com][coc_contact] with any additional questions or comments.\n\n<!-- LINKS -->\n\n[source_code]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/purview/azure-purview-sharing/azure/purview/sharing\n[client_pypi_package]: https://aka.ms/azsdk/python/purviewsharing/pypi\n[sharing_ref_docs]: https://aka.ms/azsdk/python/purviewcatalog/ref-docs\n[sharing_product_documentation]: https://azure.microsoft.com/services/purview/\n[azure_subscription]: https://azure.microsoft.com/free/\n[purview_resource]: https://docs.microsoft.com/azure/purview\n[pip]: https://pypi.org/project/pip/\n[authenticate_with_token]: https://docs.microsoft.com/azure/cognitive-services/authentication?tabs=powershell#authenticate-with-an-authentication-token\n[azure_identity_credentials]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/identity/azure-identity#credentials\n[azure_identity_pip]: https://pypi.org/project/azure-identity/\n[default_azure_credential]: https://azuresdkdocs.blob.core.windows.net/$web/python/azure-identity/latest/azure.identity.html#azure.identity.DefaultAzureCredential\n[request_builders_and_client]: https://aka.ms/azsdk/python/protocol/quickstart\n[enable_aad]: https://docs.microsoft.com/azure/purview/\n[azure_core]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/core/azure-core/README.md\n[python_logging]: https://docs.python.org/3.5/library/logging.html\n[cla]: https://cla.microsoft.com\n[code_of_conduct]: https://opensource.microsoft.com/codeofconduct/\n[coc_faq]: https://opensource.microsoft.com/codeofconduct/faq/\n[coc_contact]: mailto:opencode@microsoft.com\n[samples]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/purview/azure-purview-sharing/samples\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "Microsoft Azure Purview Sharing Client Library for Python",
"version": "1.0.0b3",
"project_urls": {
"Homepage": "https://github.com/Azure/azure-sdk-for-python/tree/main/sdk"
},
"split_keywords": [
"azure",
"azure sdk"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "97ee50860298c79d2f29843b98d6863fa40e52b5253b75b1521b22d21d258f14",
"md5": "591cdd7284923ed54014dd542b12066f",
"sha256": "bb75efd3db0c2f22e62f8690dcbe0ab8f20f06fed8d53707cd3a0a26d1b6a8cb"
},
"downloads": -1,
"filename": "azure_purview_sharing-1.0.0b3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "591cdd7284923ed54014dd542b12066f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 67333,
"upload_time": "2023-07-18T18:41:55",
"upload_time_iso_8601": "2023-07-18T18:41:55.835933Z",
"url": "https://files.pythonhosted.org/packages/97/ee/50860298c79d2f29843b98d6863fa40e52b5253b75b1521b22d21d258f14/azure_purview_sharing-1.0.0b3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "64e30c235e7c70ff731c471e1b061ef54398f12d0d59a4466530dd17ac4f5edb",
"md5": "f9e2025686171056200e948adacd8049",
"sha256": "e53438d9238fc91ea5fa5cccb64a959f159ad4c73fb2b128e4df6d1c6e551bc1"
},
"downloads": -1,
"filename": "azure-purview-sharing-1.0.0b3.zip",
"has_sig": false,
"md5_digest": "f9e2025686171056200e948adacd8049",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 95519,
"upload_time": "2023-07-18T18:41:53",
"upload_time_iso_8601": "2023-07-18T18:41:53.648240Z",
"url": "https://files.pythonhosted.org/packages/64/e3/0c235e7c70ff731c471e1b061ef54398f12d0d59a4466530dd17ac4f5edb/azure-purview-sharing-1.0.0b3.zip",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-18 18:41:53",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Azure",
"github_project": "azure-sdk-for-python",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "azure-purview-sharing"
}
JSON
