Purview Share C# SDK V3 - Add new API List Share Resources (Azure#36981)

* WIP: Add new share sdk version

* Get all existing tests ran

* Add share resources client test

* Sample tests passing in playback

* All client test passing in playback

* Fix share resource tests

* Client tests information fixed

* Fix samples information

* Fix sample tests

* Update readme

* Fix generated code

* Fix share resource client test errors

* Update readme and changelog

* Fix merge errors

* Run script

* Update snippets because of errors

* Add missing references

* Fix pipeline error

* Fix small error

* Add user invitation creation and tests and also update README

* Update changelog

* Fix snippet error

* Remove unnecessary session records

Author: rlandaeta

sdk/purview/Azure.Analytics.Purview.Sharing/CHANGELOG.md

@@ -1,14 +1,15 @@
 # Release History
 
-## 1.0.0-beta.3 (Unreleased)
+## 1.0.0-beta.3 (2023-06-30)
 
 ### Features Added
 
-### Breaking Changes
+- Added the new share resource capability that allows listing resources associated with sent and received shares.
 
-### Bugs Fixed
+### Breaking Changes
 
-### Other Changes
+- Removed skipToken as a parameter from all client list calls
+- Constructor for clients now takes in Uri object as oppose to a string parameter
 
 ## 1.0.0-beta.2 (2023-03-13)
 

sdk/purview/Azure.Analytics.Purview.Sharing/README.md

@@ -1,8 +1,21 @@
 # Azure Purview Share client library for .NET
 
-Microsoft Purview Share is a fully managed cloud service.
+Microsoft Purview Data Sharing allows data to be shared in-place from Azure Data Lake Storage Gen2 and Azure Storage accounts, both within and across organizations.
 
-**Please rely heavily on the [service's documentation][share_product_documentation] and our [protocol client docs][protocol_client_quickstart] to use this library**
+Data providers may use Microsoft Purview Data Sharing to share their data directly with other users and partners (known as data consumers) without data duplication, while centrally managing their sharing activities from within Microsoft Purview.
+
+For data consumers, Microsoft Purview Data Sharing provides near real-time access to data shared with them by a provider.
+
+Key capabilities delivered by Microsoft Purview Data Sharing include:
+- Share data within the organization or with partners and customers outside of the organization (within the same Azure tenant or across different Azure tenants).
+- Share data from ADLS Gen2 or Blob storage in-place without data duplication.
+- Share data with multiple recipients.
+- Access shared data in near real time.
+- Manage sharing relationships and keep track of who the data is shared with/from, for each ADLSGen2 or Blob Storage account.
+- Terminate share access at any time.
+- Flexible experience through Microsoft Purview governance portal or via REST APIs.
+
+**Please visit the following resources to learn more about this product.**
 
 [Source code][source_code] | [Package (NuGet)][client_nuget_package] | [Product documentation][share_product_documentation]
 
@@ -28,19 +41,11 @@ This example demonstrates using [DefaultAzureCredential][default_cred_ref] to au
 
 Once you have chosen and configured your credential, you can create instances of the `SentSharesClient`.
 
-```C# Snippet:SentSharesClientSample_CreateSentSharesClient
-var credential = new DefaultAzureCredential();
-var endPoint = "https://my-account-name.purview.azure.com/share";
-var sentShareClient = new SentSharesClient(endPoint, credential);
-```
+## Key concepts
 
-```C# Snippet:ReceivedSharesClientSample_CreateReceivedSharesClient
-var credential = new DefaultAzureCredential();
-var endPoint = "https://my-account-name.purview.azure.com/share";
-var receivedSharesClient = new ReceivedSharesClient(endPoint, credential);
-```
+__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.
 
-## Key concepts
+__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.
 
 ### Protocol Methods
 
@@ -62,15 +67,24 @@ We guarantee that all client instance methods are thread-safe and independent of
 [Client lifetime](https://devblogs.microsoft.com/azure-sdk/lifetime-management-and-thread-safety-guarantees-of-azure-sdk-net-clients/)
 <!-- CLIENT COMMON BAR -->
 
-## Examples
+##Examples
+
+### Data Provider Examples
+
+The following code examples demonstrate how data providers can use the Microsoft Azure Java SDK for Purview Sharing to manage their sharing activity.
 
-The following section shows you how to initialize and authenticate your client and share data.
+#### Create a Sent Share Client
+```C# Snippet:SentSharesClientSample_CreateSentSharesClient
+var credential = new DefaultAzureCredential();
+var endPoint = new Uri("https://my-account-name.purview.azure.com/share");
+var sentShareClient = new SentSharesClient(endPoint, credential);
+```
 
-### Create a sent share
+#### Create a Sent Share
 
 ```C# Snippet:SentSharesClientSample_CreateSentShare
 var credential = new DefaultAzureCredential();
-var endPoint = "https://my-account-name.purview.azure.com/share";
+var endPoint = new Uri("https://my-account-name.purview.azure.com/share");
 var sentShareClient = new SentSharesClient(endPoint, credential);
 
 var data = new
@@ -107,31 +121,59 @@ var data = new
 Operation<BinaryData> createResponse = await sentShareClient.CreateOrReplaceSentShareAsync(WaitUntil.Completed, "sentShareId", RequestContent.Create(data));
 ```
 
-### Get a sent share
+#### Get a Sent Share
+
+After creating a sent share, data providers can retrieve it.
 
 ```C# Snippet:SentSharesClientSample_GetSentShare
 var credential = new DefaultAzureCredential();
-var endPoint = "https://my-account-name.purview.azure.com/share";
+var endPoint = new Uri("https://my-account-name.purview.azure.com/share");
 var sentShareClient = new SentSharesClient(endPoint, credential);
 
 Response response = await sentShareClient.GetSentShareAsync("sentShareId");
 ```
 
-### List sent shares
+#### List Sent Shares
+
+Data providers can also retrieve a list of the sent shares they have created.
 
 ```C# Snippet:SentSharesClientSample_ListSentShares
 var credential = new DefaultAzureCredential();
-var endPoint = "https://my-account-name.purview.azure.com/share";
+var endPoint = new Uri("https://my-account-name.purview.azure.com/share");
 var sentShareClient = new SentSharesClient(endPoint, credential);
 
 List<BinaryData> response = await sentShareClient.GetAllSentSharesAsync("referenceName").ToEnumerableAsync();
 ```
 
-### Create a sent share invitation
+#### Create a 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.
+
+```C# Snippet:SentSharesClientSample_CreateSentShareUserInvitation
+var credential = new DefaultAzureCredential();
+var endPoint = new Uri("https://my-account-name.purview.azure.com/share");
+var sentShareClient = new SentSharesClient(endPoint, credential);
+
+var data = new
+{
+    invitationKind = "User",
+    properties = new
+    {
+        TargetEmail = "[email protected]",
+        Notify = true,
+    }
+};
+
+Response response = await sentShareClient.CreateSentShareInvitationAsync("sentShareId", "sentShareInvitationId", RequestContent.Create(data));
+```
+
+#### Create a 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)*.
 
 ```C# Snippet:SentSharesClientSample_CreateSentShareInvitation
 var credential = new DefaultAzureCredential();
-var endPoint = "https://my-account-name.purview.azure.com/share";
+var endPoint = new Uri("https://my-account-name.purview.azure.com/share");
 var sentShareClient = new SentSharesClient(endPoint, credential);
 
 var data = new
@@ -147,41 +189,84 @@ var data = new
 Response response = await sentShareClient.CreateSentShareInvitationAsync("sentShareId", "sentShareInvitationId", RequestContent.Create(data));
 ```
 
-### Get a sent share invitation
+#### Get a sent share invitation
+
+After creating a sent share invitation, data providers can retrieve it.
 
 ```C# Snippet:SentSharesClientSample_GetSentShareInvitation
 var credential = new DefaultAzureCredential();
-var endPoint = "https://my-account-name.purview.azure.com/share";
+var endPoint = new Uri("https://my-account-name.purview.azure.com/share");
 var sentShareClient = new SentSharesClient(endPoint, credential);
 
 Response response = await sentShareClient.GetSentShareInvitationAsync("sentShareId", "sentShareInvitationId");
 ```
 
-### List sent share invitations
+#### List sent share invitations
+
+Data providers can also retrieve a list of the sent share invitations they have created.
 
 ```C# Snippet:SentSharesClientSample_ListSentShareInvitations
 var credential = new DefaultAzureCredential();
-var endPoint = "https://my-account-name.purview.azure.com/share";
+var endPoint = new Uri("https://my-account-name.purview.azure.com/share");
 var sentShareClient = new SentSharesClient(endPoint, credential);
 
 List<BinaryData> sentShareInvitations = await sentShareClient.GetAllSentShareInvitationsAsync("sentShareId").ToEnumerableAsync();
 ```
 
-### List detached received shares
+#### Delete a sent share invitation
+
+Data providers can also retrieve a list of the sent share invitations they have created.
+
+```C# Snippet:SentSharesClientSample_DeleteSentShareInvitation
+var credential = new DefaultAzureCredential();
+var endPoint = new Uri("https://my-account-name.purview.azure.com/share");
+var sentShareClient = new SentSharesClient(endPoint, credential);
+
+Operation operation = await sentShareClient.DeleteSentShareInvitationAsync(WaitUntil.Completed, "sentShareId", "sentShareInvitationId");
+```
+
+#### Delete a sent share
+
+A sent share can be deleted by the data provider to stop sharing their data with all data consumers.
+
+```C# Snippet:SentSharesClientSample_DeleteSentShare
+var credential = new DefaultAzureCredential();
+var endPoint = new Uri("https://my-account-name.purview.azure.com/share");
+var sentShareClient = new SentSharesClient(endPoint, credential);
+
+Operation operation = await sentShareClient.DeleteSentShareAsync(WaitUntil.Completed, "sentShareId");
+```
+
+### Data Consumer Examples
+
+The following code examples demonstrate how data consumers can use the Microsoft Azure Java SDK for Purview Sharing to manage their sharing activity.
+
+#### Create a Receive Share Client
+```C# Snippet:ReceivedSharesClientSample_CreateReceivedSharesClient
+var credential = new DefaultAzureCredential();
+var endPoint = new Uri("https://my-account-name.purview.azure.com/share");
+var receivedSharesClient = new ReceivedSharesClient(endPoint, 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.
 
 ```C# Snippet:ReceivedSharesClientSample_ListDetachedReceivedShares
 var credential = new DefaultAzureCredential();
-var endPoint = "https://my-account-name.purview.azure.com/share";
+var endPoint = new Uri("https://my-account-name.purview.azure.com/share");
 var receivedSharesClient = new ReceivedSharesClient(endPoint, credential);
 
 List<BinaryData> createResponse = await receivedSharesClient.GetAllDetachedReceivedSharesAsync().ToEnumerableAsync();
 ```
 
-### Create a received share
+#### 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.
 
 ```C# Snippet:ReceivedSharesClientSample_CreateReceivedShare
 var credential = new DefaultAzureCredential();
-var endPoint = "https://my-account-name.purview.azure.com/share";
+var endPoint = new Uri("https://my-account-name.purview.azure.com/share");
 var receivedSharesClient = new ReceivedSharesClient(endPoint, credential);
 
 var data = new
@@ -212,56 +297,59 @@ var data = new
 Operation<BinaryData> createResponse = await receivedSharesClient.CreateOrReplaceReceivedShareAsync(WaitUntil.Completed, "receivedShareId", RequestContent.Create(data));
 ```
 
-### Get a received share
+#### Get a received share
+
+A data consumer can retrieve an individual received share.
 
 ```C# Snippet:ReceivedSharesClientSample_GetReceivedShare
 var credential = new DefaultAzureCredential();
-var endPoint = "https://my-account-name.purview.azure.com/share";
+var endPoint = new Uri("https://my-account-name.purview.azure.com/share");
 var receivedSharesClient = new ReceivedSharesClient(endPoint, credential);
 
 Response operation = await receivedSharesClient.GetReceivedShareAsync("receivedShareId");
 ```
 
-### List attached received shares
+#### List attached received shares
+
+Data consumers can also retrieve a list of their attached received shares.
 
 ```C# Snippet:ReceivedSharesClientSample_ListAttachedReceivedShares
 var credential = new DefaultAzureCredential();
-var endPoint = "https://my-account-name.purview.azure.com/share";
+var endPoint = new Uri("https://my-account-name.purview.azure.com/share");
 var receivedSharesClient = new ReceivedSharesClient(endPoint, credential);
 
 List<BinaryData> createResponse = await receivedSharesClient.GetAllAttachedReceivedSharesAsync("referenceName").ToEnumerableAsync();
 ```
 
-### Delete a received share
+#### Delete a received share
+
+Data consumers can also retrieve a list of their attached received shares.
 
 ```C# Snippet:ReceivedSharesClientSample_DeleteReceivedShare
 var credential = new DefaultAzureCredential();
-var endPoint = "https://my-account-name.purview.azure.com/share";
+var endPoint = new Uri("https://my-account-name.purview.azure.com/share");
 var receivedSharesClient = new ReceivedSharesClient(endPoint, credential);
 
 Operation operation = await receivedSharesClient.DeleteReceivedShareAsync(WaitUntil.Completed, "receivedShareId");
 ```
 
-### Delete a sent share invitation
+### Share Resouce Examples
 
-```C# Snippet:SentSharesClientSample_DeleteSentShareInvitation
-var credential = new DefaultAzureCredential();
-var endPoint = "https://my-account-name.purview.azure.com/share";
-var sentShareClient = new SentSharesClient(endPoint, credential);
+The following code examples demonstrate how to use the Microsoft Azure Java 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.
 
-Operation operation = await sentShareClient.DeleteSentShareInvitationAsync(WaitUntil.Completed, "sentShareId", "sentShareInvitationId");
-```
+#### List share resources
 
-### Delete a sent share
+A list of share resources can be retrieved to view all resources within an account where sharing activities have taken place.
 
-```C# Snippet:SentSharesClientSample_DeleteSentShare
+```C# Snippet:ShareResourcesClientExample_ListShareResources
 var credential = new DefaultAzureCredential();
-var endPoint = "https://my-account-name.purview.azure.com/share";
-var sentShareClient = new SentSharesClient(endPoint, credential);
+var endPoint = new Uri("https://my-account-name.purview.azure.com/share");
+var shareResourcesClient = new ShareResourcesClient(endPoint, credential);
 
-Operation operation = await sentShareClient.DeleteSentShareAsync(WaitUntil.Completed, "sentShareId");
+List<BinaryData> createResponse = await shareResourcesClient.GetAllShareResourcesAsync().ToEnumerableAsync();
 ```
 
+
 ## Troubleshooting
 
 ### Setting up console logging