你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

适用于 Java 的 Azure Purview 共享客户端库 - 版本 1.0.0-beta.2

Microsoft Purview 数据共享允许从组织内部和跨组织之间的Azure Data Lake Storage Gen2和 Azure 存储帐户就地共享数据。

数据提供程序可以使用Microsoft Purview 数据共享直接与其他用户和合作伙伴共享其数据， (称为数据使用者) ，而不会重复数据，同时在 Microsoft Purview 中集中管理其共享活动。

对于数据使用者，Microsoft Purview 数据共享提供对提供程序与其共享的数据的准实时访问。

Microsoft Purview 数据共享提供的主要功能包括：

• 在组织内部共享数据，或者与组织外部的合作伙伴和客户（在同一 Azure 租户中或跨不同 Azure 租户）共享数据。
• 就地共享 ADLS Gen2 或 Blob 存储中的数据，而无需复制数据。
• 与多个接收方共享数据。
• 准实时访问共享的数据。
• 管理共享关系，并跟踪每个 ADLSGen2 或 Blob 存储帐户与谁共享/从谁共享数据。
• 随时终止共享访问。
• 通过 Microsoft Purview 治理门户或 REST API 使用灵活的体验。

请访问以下资源，了解有关此产品的详细信息。

源代码 | 包 (Maven) | API 参考文档 | 产品文档 | 样品

入门

先决条件

• Java 开发工具包 (版本 8 或更高版本的 JDK)
• Azure 订阅
• 一个现有的 Microsoft Purview 帐户。

有关创建 Microsoft Purview 帐户的详细信息，请参阅 此处。

文档

提供了各种文档来帮助你入门

• API 参考文档
• 产品文档

将包添加到产品

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-analytics-purview-sharing</artifactId>
    <version>1.0.0-beta.2</version>
</dependency>

身份验证

Azure 标识 包提供用于对客户端进行身份验证的默认实现。

关键概念

数据提供程序： 数据提供程序是通过选择数据源、选择要共享的文件和文件夹以及与其共享的人员来创建共享的个人。 然后，Microsoft Purview 向每个数据使用者发送邀请。

数据使用者： 数据使用者是通过在其自己的 Azure 订阅中指定用于访问共享数据的目标存储帐户来接受邀请的个人。

示例

数据提供程序示例

以下代码示例演示了数据提供程序如何使用 Microsoft Azure Java SDK for Purview Sharing 来管理其共享活动。

创建已发送的共享客户端

SentSharesClient sentSharesClient =
        new SentSharesClientBuilder()
                .credential(new DefaultAzureCredentialBuilder().build())
                .endpoint("https://<my-account-name>.purview.azure.com/share")
                .buildClient();

创建已发送共享

若要开始共享数据，数据提供程序必须首先创建一个已发送的共享，用于标识要共享的数据。

SentSharesClient sentSharesClient =
        new SentSharesClientBuilder()
                .credential(new DefaultAzureCredentialBuilder().build())
                .endpoint("https://<my-account-name>.purview.azure.com/share")
                .buildClient();

String sentShareId = UUID.randomUUID().toString();
InPlaceSentShare sentShare = new InPlaceSentShare()
        .setDisplayName("sample-share")
        .setDescription("A sample share");

StoreReference storeReference = new StoreReference()
        .setReferenceName("/subscriptions/de06c3a0-4610-4ca0-8cbb-bbdac204bd65/resourceGroups/provider-storage-rg/providers/Microsoft.Storage/storageAccounts/providerstorage")
        .setType(ReferenceNameType.ARM_RESOURCE_REFERENCE);

StorageAccountPath storageAccountPath = new StorageAccountPath()
        .setContainerName("container-name")
        .setReceiverPath("shared-file-name.txt")
        .setSenderPath("original/file-name.txt");

List<StorageAccountPath> paths = new ArrayList<>();
paths.add(storageAccountPath);

BlobStorageArtifact artifact = new BlobStorageArtifact()
        .setStoreReference(storeReference)
        .setPaths(paths);

sentShare.setArtifact(artifact);

SyncPoller<BinaryData, BinaryData> response =
        sentSharesClient.beginCreateOrReplaceSentShare(
                sentShareId,
                BinaryData.fromObject(sentShare),
                new RequestOptions());

向用户发送共享邀请

创建已发送的共享后，数据提供程序可以将邀请扩展到随后可以查看共享数据的使用者。 在此示例中，通过指定个人的电子邮件地址将邀请扩展到个人。

SentSharesClient sentSharesClient =
        new SentSharesClientBuilder()
                .credential(new DefaultAzureCredentialBuilder().build())
                .endpoint("https://<my-account-name>.purview.azure.com/share")
                .buildClient();

String sentShareId = "<sent-share-id>";
String sentShareInvitationId = UUID.randomUUID().toString();

UserInvitation sentShareInvitation = new UserInvitation()
        .setTargetEmail("receiver@microsoft.com")
        .setNotify(true)
        .setExpirationDate(OffsetDateTime.now().plusDays(60));

Response<BinaryData> response =
        sentSharesClient.createSentShareInvitationWithResponse(
                sentShareId,
                sentShareInvitationId,
                BinaryData.fromObject(sentShareInvitation),
                new RequestOptions());

向服务发送共享邀请

数据提供程序还可以通过指定服务的租户 ID 和对象 ID，将邀请扩展到服务或应用程序。 用于向服务发送邀请的对象 ID 必须是与企业应用程序关联的对象 ID， (而不是应用程序注册) 。

SentSharesClient sentSharesClient =
        new SentSharesClientBuilder()
                .credential(new DefaultAzureCredentialBuilder().build())
                .endpoint("https://<my-account-name>.purview.azure.com/share")
                .buildClient();

String sentShareId = "<sent-share-id>";
String sentShareInvitationId = UUID.randomUUID().toString();

ServiceInvitation sentShareInvitation = new ServiceInvitation()
        .setTargetActiveDirectoryId(UUID.fromString("<tenant-id>"))
        .setTargetObjectId(UUID.fromString("<object-id>"))
        .setExpirationDate(OffsetDateTime.now().plusDays(60));

Response<BinaryData> response =
        sentSharesClient.createSentShareInvitationWithResponse(
                sentShareId,
                sentShareInvitationId,
                BinaryData.fromObject(sentShareInvitation),
                new RequestOptions());

获取已发送的共享

创建发送的共享后，数据提供程序可以检索它。

SentSharesClient sentSharesClient =
        new SentSharesClientBuilder()
                .credential(new DefaultAzureCredentialBuilder().build())
                .endpoint("https://<my-account-name>.purview.azure.com/share")
                .buildClient();

SentShare retrievedSentShare = sentSharesClient
        .getSentShareWithResponse("<sent-share-id>", new RequestOptions())
        .getValue()
        .toObject(SentShare.class);

列出已发送的共享

数据提供程序还可以检索他们已创建的已发送共享的列表。

SentSharesClient sentSharesClient =
        new SentSharesClientBuilder()
                .credential(new DefaultAzureCredentialBuilder().build())
                .endpoint("https://<my-account-name>.purview.azure.com/share")
                .buildClient();

PagedIterable<BinaryData> sentShareResults = sentSharesClient.listSentShares(
                "/subscriptions/de06c3a0-4610-4ca0-8cbb-bbdac204bd65/resourceGroups/provider-storage-rg/providers/Microsoft.Storage/storageAccounts/providerstorage",
                new RequestOptions());

List<SentShare> sentShares = sentShareResults.stream()
    .map(binaryData -> binaryData.toObject(SentShare.class))
    .collect(Collectors.toList());

删除已发送的共享

数据提供程序可以删除已发送的共享，以停止与所有数据使用者共享其数据。

SentSharesClient sentSharesClient =
        new SentSharesClientBuilder()
                .credential(new DefaultAzureCredentialBuilder().build())
                .endpoint("https://<my-account-name>.purview.azure.com/share")
                .buildClient();

sentSharesClient.beginDeleteSentShare("<sent-share-id", new RequestOptions());

获取已发送的共享邀请

创建发送的共享邀请后，数据提供程序可以检索它。

SentSharesClient sentSharesClient =
        new SentSharesClientBuilder()
                .credential(new DefaultAzureCredentialBuilder().build())
                .endpoint("https://<my-account-name>.purview.azure.com/share")
                .buildClient();

String sentShareId = "<sent-share-id>";
String sentShareInvitationId = "<sent-share-invitation-id>";

Response<BinaryData> sentShareInvitation =
        sentSharesClient.getSentShareInvitationWithResponse(sentShareId, sentShareInvitationId, new RequestOptions());

列出已发送的共享邀请

数据提供程序还可以检索其创建的已发送共享邀请的列表。

SentSharesClient sentSharesClient =
        new SentSharesClientBuilder()
                .credential(new DefaultAzureCredentialBuilder().build())
                .endpoint("https://<my-account-name>.purview.azure.com/share")
                .buildClient();

String sentShareId = "<sent-share-id>";

RequestOptions requestOptions = new RequestOptions().addQueryParam("$orderBy", "properties/sentAt desc");
PagedIterable<BinaryData> response =
        sentSharesClient.listSentShareInvitations(sentShareId, requestOptions);

删除已发送的共享邀请

数据提供程序可以删除个人发送的共享邀请，以停止与发出邀请的特定数据使用者共享其数据。

SentSharesClient sentSharesClient =
        new SentSharesClientBuilder()
                .credential(new DefaultAzureCredentialBuilder().build())
                .endpoint("https://<my-account-name>.purview.azure.com/share")
                .buildClient();

String sentShareId = "<sent-share-id>";
String sentShareInvitationId = "<sent-share-invitation-id>";

sentSharesClient.beginDeleteSentShareInvitation(sentShareId, sentShareInvitationId, new RequestOptions());

数据使用者示例

以下代码示例演示数据使用者如何使用 Microsoft Azure Java SDK for Purview Sharing 来管理其共享活动。

创建接收的共享客户端

ReceivedSharesClient receivedSharesClient =
        new ReceivedSharesClientBuilder()
                .credential(new DefaultAzureCredentialBuilder().build())
                .endpoint("https://<my-account-name>.purview.azure.com/share")
                .buildClient();

列出已分离的已接收共享

若要开始查看与其共享的数据，数据使用者必须首先检索已分离的已接收共享的列表。 在此列表中，他们可以标识要附加的已分离的已接收共享。

ReceivedSharesClient receivedSharesClient =
        new ReceivedSharesClientBuilder()
                .credential(new DefaultAzureCredentialBuilder().build())
                .endpoint("https://<my-account-name>.purview.azure.com/share")
                .buildClient();

RequestOptions requestOptions = new RequestOptions().addQueryParam("$orderBy", "properties/createdAt desc");
PagedIterable<BinaryData> response = receivedSharesClient.listDetachedReceivedShares(requestOptions);

附加接收共享

数据使用者标识接收的共享后，可以将收到的共享附加到可以访问共享数据的位置。 如果已附加接收的共享，则将在指定的新位置访问共享数据。

ReceivedSharesClient receivedSharesClient =
        new ReceivedSharesClientBuilder()
                .credential(new DefaultAzureCredentialBuilder().build())
                .endpoint("https://<my-account-name>.purview.azure.com/share")
                .buildClient();

RequestOptions listRequestOptions = new RequestOptions().addQueryParam("$orderBy", "properties/createdAt desc");
PagedIterable<BinaryData> listResponse = receivedSharesClient.listDetachedReceivedShares(listRequestOptions);

Optional<BinaryData> detachedReceivedShare = listResponse.stream().findFirst();

if (!detachedReceivedShare.isPresent()) {
    return;
}

String receivedShareId = new ObjectMapper()
        .readValue(detachedReceivedShare.get().toString(), ObjectNode.class)
        .get("id")
        .textValue();
 
InPlaceReceivedShare receivedShare = new InPlaceReceivedShare()
        .setDisplayName("my-received-share");

StoreReference storeReference = new StoreReference()
        .setReferenceName("/subscriptions/de06c3a0-4610-4ca0-8cbb-bbdac204bd65/resourceGroups/consumer-storage-rg/providers/Microsoft.Storage/storageAccounts/consumerstorage")
        .setType(ReferenceNameType.ARM_RESOURCE_REFERENCE); 

BlobAccountSink sink = new BlobAccountSink()
        .setStoreReference(storeReference)
        .setContainerName("container-name")
        .setFolder("folderName")
        .setMountPath("optionalMountPath");

receivedShare.setSink(sink);

SyncPoller<BinaryData, BinaryData> createResponse =
        receivedSharesClient.beginCreateOrReplaceReceivedShare(receivedShareId, BinaryData.fromObject(receivedShare), new RequestOptions());

获取接收的共享

数据使用者可以检索单个接收的共享。

ReceivedSharesClient receivedSharesClient =
        new ReceivedSharesClientBuilder()
                .credential(new DefaultAzureCredentialBuilder().build())
                .endpoint("https://<my-account-name>.purview.azure.com/share")
                .buildClient();

Response<BinaryData> receivedShare =
        receivedSharesClient.getReceivedShareWithResponse("<received-share-id>", new RequestOptions());

列出附加的已接收共享

数据使用者还可以检索其附加的已接收共享的列表。

ReceivedSharesClient receivedSharesClient =
        new ReceivedSharesClientBuilder()
                .credential(new DefaultAzureCredentialBuilder().build())
                .endpoint("https://<my-account-name>.purview.azure.com/share")
                .buildClient();

RequestOptions requestOptions = new RequestOptions().addQueryParam("$orderBy", "properties/createdAt desc");
PagedIterable<BinaryData> response =
        receivedSharesClient.listAttachedReceivedShares(
                "/subscriptions/de06c3a0-4610-4ca0-8cbb-bbdac204bd65/resourceGroups/consumer-storage-rg/providers/Microsoft.Storage/storageAccounts/consumerstorage",
                requestOptions);

Optional<BinaryData> receivedShare = response.stream().findFirst();

if (!receivedShare.isPresent()) {
    return;
}

ReceivedShare receivedShareResponse = receivedShare.get().toObject(InPlaceReceivedShare.class);

删除收到的共享

数据使用者可以删除收到的共享，以终止其对共享数据的访问权限。

ReceivedSharesClient receivedSharesClient =
        new ReceivedSharesClientBuilder()
                .credential(new DefaultAzureCredentialBuilder().build())
                .endpoint("https://<my-account-name>.purview.azure.com/share")
                .buildClient();

receivedSharesClient.beginDeleteReceivedShare("<received-share-id>", new RequestOptions()); 

共享资源示例

以下代码示例演示如何使用用于 Purview 共享的 Microsoft Azure Java SDK 查看共享资源。 共享资源是提供程序共享数据的基础资源，或者使用者在其中附加与其共享的数据的目标。

列出共享资源

可以检索共享资源列表，以查看发生共享活动的帐户中的所有资源。

ShareResourcesClient shareResourcesClient =
        new ShareResourcesClientBuilder()
                .credential(new DefaultAzureCredentialBuilder().build())
                .endpoint("https://<my-account-name>.purview.azure.com/share")
                .buildClient();

PagedIterable<BinaryData> shareResourceResults = shareResourcesClient.listShareResources(new RequestOptions());
 
List<ShareResource> shareResources = shareResourceResults.stream()
    .map(binaryData -> binaryData.toObject(ShareResource.class))
    .collect(Collectors.toList());

疑难解答

启用日志记录

适用于 Java 的 Azure SDK 提供一致的日志记录案例，可帮助排查应用程序错误并加快解决。 生成的日志会在到达终端状态之前捕获应用程序的流，以帮助查找根本问题。 查看 日志记录 Wiki，获取有关启用日志记录的指南。

后续步骤

供稿

有关参与此存储库的详细信息，请参阅 参与指南。

1. 分支
2. 创建功能分支 (git checkout -b my-new-feature)
3. () git commit -am 'Add some feature' 提交更改
4. 推送到分支 (git push origin my-new-feature)
5. 创建新的拉取请求