azure-purview-sharing 1.0.0b3

Description:

azurepurviewsharing 1.0.0b3

Azure Purview Sharing client library for Python
Microsoft Purview Share is a fully managed cloud service.
Please rely heavily on the service's documentation and our protocol client docs to use this library
Source code | Package (PyPI) | Product documentation
Getting started
Install the package
Install the Azure Purview Sharing client library for Python with pip:
pip install azure-purview-sharing

Prerequisites

You must have an Azure subscription and a 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 to authenticate via Azure Active Directory. However, any of the credentials offered by the azure-identity package will be accepted. See the azure-identity documentation for more information about other credentials.
Once you have chosen and configured your credential, you can create instances of the PurviewSharingClient.
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 Consumer
Share Resource

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
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.
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.
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 = "[email protected]"
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).
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.
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.
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.
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.
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.
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.
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
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.
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.
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.
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.
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.
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.
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 if you call .raise_for_status() on your responses.
Logging
This library uses the standard
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:
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:
result = client.types.get_all_type_definitions(logging_enable=True)

Next steps
For more generic samples, see our 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.
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. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.