Package: azure-purview-sharing
Azure Purview Sharing client library for PythonMicrosoft Purview Share is a fully managed cloud service.Please rely heavily on theservice's documentationand ourprotocol client docsto use this librarySource code|Package (PyPI)|Product documentationGetting startedInstall the packageInstall the Azure Purview Sharing client library for Python withpip:pipinstallazure-purview-sharingPrerequisitesYou must have anAzure subscriptionand aPurview resourceto use this package.Python 3.6 or later is required to use this package.Authenticate the clientUsing Azure Active DirectoryThis document demonstrates usingDefaultAzureCredentialto authenticate via Azure Active Directory. However, any of the credentials offered by theazure-identity packagewill be accepted.  See theazure-identitydocumentation for more information about other credentials.Once you have chosen and configured your credential, you can create instances of thePurviewSharingClient.fromazure.purview.sharingimportPurviewSharingClientfromazure.identityimportDefaultAzureCredentialcredential=DefaultAzureCredential()client=PurviewSharingClient(endpoint="https://<my-account-name>.purview.azure.com",credential=credential)Key conceptsData 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.ExamplesTable of Contents:Data ProviderData ConsumerShare ResourceData Provider ExamplesThe 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 Clientimportos,uuid,jsonfromazure.purview.sharingimportPurviewSharingClientfromazure.identityimportDefaultAzureCredentialendpoint=os.environ["ENDPOINT"]credential=DefaultAzureCredential()client=PurviewSharingClient(endpoint=endpoint,credential=credential)Create ShareTo begin sharing data, the data provider must first create a sent share that identifies the data they would like to share.importos,uuid,jsonfromazure.purview.sharingimportPurviewSharingClientfromazure.identityimportDefaultAzureCredentialendpoint=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 UserAfter 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.importos,uuidfromazure.purview.sharingimportPurviewSharingClientfromazure.identityimportDefaultAzureCredentialfromdatetimeimportdateendpoint=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 ServiceData 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).importos,uuidfromazure.purview.sharingimportPurviewSharingClientfromazure.identityimportDefaultAzureCredentialendpoint=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 ShareAfter creating a sent share, data providers can retrieve it.importos,uuidfromazure.purview.sharingimportPurviewSharingClientfromazure.identityimportDefaultAzureCredentialendpoint=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 SharesData providers can also retrieve a list of the sent shares they have created.importosfromazure.purview.sharingimportPurviewSharingClientfromazure.identityimportDefaultAzureCredentialendpoint=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")forlist_responseinlist_request:print(list_response)Delete Sent ShareA sent share can be deleted by the data provider to stop sharing their data with all data consumers.importosfromazure.purview.sharingimportPurviewSharingClientfromazure.identityimportDefaultAzureCredentialendpoint=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 InvitationAfter creating a sent share invitation, data providers can retrieve it.importos,uuid,jsonfromazure.purview.sharingimportPurviewSharingClientfromazure.identityimportDefaultAzureCredentialendpoint=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 InvitationsData providers can also retrieve a list of the sent share invitations they have created.importos,uuid,jsonfromazure.purview.sharingimportPurviewSharingClientfromazure.identityimportDefaultAzureCredentialendpoint=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))forlist_responseinlist_request:print(list_response)Delete Sent Share InvitationAn 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.importos,uuid,jsonfromazure.purview.sharingimportPurviewSharingClientfromazure.identityimportDefaultAzureCredentialendpoint=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 ExamplesThe 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 Clientimportosfromazure.purview.sharingimportPurviewSharingClientfromazure.identityimportDefaultAzureCredentialendpoint=os.environ["ENDPOINT"]credential=DefaultAzureCredential()client=PurviewSharingClient(endpoint=endpoint,credential=credential)List Detached Received SharesTo 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.importosfromazure.purview.sharingimportPurviewSharingClientfromazure.identityimportDefaultAzureCredentialendpoint=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 ShareOnce 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.importos,jsonfromazure.purview.sharingimportPurviewSharingClientfromazure.identityimportDefaultAzureCredentialendpoint=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(xforxinlist_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']=sinkupdate_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 ShareA data consumer can retrieve an individual received share.importosfromazure.purview.sharingimportPurviewSharingClientfromazure.identityimportDefaultAzureCredentialendpoint=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 SharesData consumers can also retrieve a list of their attached received shares.importosfromazure.purview.sharingimportPurviewSharingClientfromazure.identityimportDefaultAzureCredentialendpoint=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 ShareA received share can be deleted by the data consumer to terminate their access to shared data.importosfromazure.purview.sharingimportPurviewSharingClientfromazure.identityimportDefaultAzureCredentialendpoint=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 ExamplesThe 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 ResourcesA list of share resources can be retrieved to view all resources within an account where sharing activities have taken place.importosfromazure.purview.sharingimportPurviewSharingClientfromazure.identityimportDefaultAzureCredentialendpoint=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")forlist_responseinlist_request:print(list_response)TroubleshootingGeneralThe Purview Catalog client will raise exceptions defined inAzure Coreif you call.raise_for_status()on your responses.LoggingThis library uses the standardlogginglibrary 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 thelogging_enablekeyword argument:importsysimportloggingfromazure.identityimportDefaultAzureCredentialfromazure.purview.sharingimportPurviewSharingClient# Create a logger for the 'azure' SDKlogger=logging.getLogger('azure')logger.setLevel(logging.DEBUG)# Configure a console outputhandler=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 levelclient=PurviewSharingClient(endpoint=endpoint,credential=credential,logging_enable=True)Similarly,logging_enablecan enable detailed logging for a singlesend_requestcall,
even when it isn't enabled for the client:result=client.types.get_all_type_definitions(logging_enable=True)Next stepsFor more generic samples, see oursamples.ContributingThis 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, visitcla.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 theMicrosoft Open Source Code of Conduct. For more information see theCode of Conduct FAQor contactopencode@microsoft.comwith any additional questions or comments.