Skip to content

Commit 830b216

Browse files
v-dirichardsv-dirichards
authored
Merge pull request #286320 from pauljewellmsft/adls-acl-dev
Freshness pass for ACL dev articles
2 parents eda3914 + cbc7908 commit 830b216

File tree

4 files changed

+170
-116
lines changed

4 files changed

+170
-116
lines changed

‎articles/storage/blobs/data-lake-storage-acl-dotnet.md

Lines changed: 35 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ description: Use .NET to manage access control lists (ACL) in storage accounts t
55
author: pauljewellmsft
66

77
ms.service: azure-data-lake-storage
8-
ms.date: 02/07/2023
8+
ms.date: 09/06/2024
99
ms.author: pauljewell
1010
ms.topic: how-to
1111
ms.reviewer: prishet
@@ -23,84 +23,75 @@ ACL inheritance is already available for new child items that are created under
2323

2424
## Prerequisites
2525

26-
- An Azure subscription. See [Get Azure free trial](https://azure.microsoft.com/pricing/free-trial/).
27-
28-
- A storage account that has hierarchical namespace (HNS) enabled. Follow [these](create-data-lake-storage-account.md) instructions to create one.
29-
26+
- Azure subscription - [create one for free](https://azure.microsoft.com/free/).
27+
- Azure storage account that has hierarchical namespace (HNS) enabled. Follow [these instructions](create-data-lake-storage-account.md) to create one.
3028
- Azure CLI version `2.6.0` or higher.
31-
3229
- One of the following security permissions:
33-
3430
- A provisioned Microsoft Entra ID [security principal](../../role-based-access-control/overview.md#security-principal) that has been assigned the [Storage Blob Data Owner](../../role-based-access-control/built-in-roles.md#storage-blob-data-owner) role, scoped to the target container, storage account, parent resource group, or subscription.
35-
3631
- Owning user of the target container or directory to which you plan to apply ACL settings. To set ACLs recursively, this includes all child items in the target container or directory.
37-
3832
- Storage account key.
3933

4034
## Set up your project
4135

42-
To get started, install the [Azure.Storage.Files.DataLake](https://www.nuget.org/packages/Azure.Storage.Files.DataLake/) NuGet package.
36+
This section shows you how to set up a project to work with the Azure Storage Data Lake client library.
37+
38+
### Install packages
4339

44-
1. Open a command window (For example: Windows PowerShell).
40+
From your project directory, install packages for the Azure Storage Data Lake and Azure Identity client libraries using the `dotnet add package` command. The Azure.Identity package is needed for passwordless connections to Azure services.
4541

46-
2. From your project directory, install the Azure.Storage.Files.DataLake preview package by using the `dotnet add package` command.
42+
```dotnetcli
43+
dotnet add package Azure.Storage.Files.DataLake
44+
dotnet add package Azure.Identity
45+
```
4746

48-
```console
49-
dotnet add package Azure.Storage.Files.DataLake -v 12.6.0 -s https://pkgs.dev.azure.com/azure-sdk/public/_packaging/azure-sdk-for-net/nuget/v3/index.json
50-
```
47+
### Add `using` directives
5148

52-
Then, add these using statements to the top of your code file.
49+
Add these `using` directives to the top of your code file:
5350

54-
```csharp
55-
using Azure;
56-
using Azure.Core;
57-
using Azure.Storage;
58-
using Azure.Storage.Files.DataLake;
59-
using Azure.Storage.Files.DataLake.Models;
60-
using System.Collections.Generic;
61-
using System.Threading.Tasks;
62-
```
51+
```csharp
52+
using Azure;
53+
using Azure.Core;
54+
using Azure.Storage;
55+
using Azure.Storage.Files.DataLake;
56+
using Azure.Storage.Files.DataLake.Models;
57+
using System.Collections.Generic;
58+
using System.Threading.Tasks;
59+
```
6360

6461
## Connect to the account
6562

66-
To use the snippets in this article, you'll need to create a [DataLakeServiceClient](/dotnet/api/azure.storage.files.datalake.datalakeserviceclient) instance that represents the storage account.
63+
To run the code examples in this article, you need to create a [DataLakeServiceClient](/dotnet/api/azure.storage.files.datalake.datalakeserviceclient) instance that represents the storage account. You can authorize the client object with Microsoft Entra ID credentials or with an account key.
6764

68-
<a name='connect-by-using-azure-active-directory-ad'></a>
65+
### [Microsoft Entra ID (recommended)](#tab/entra-id)
6966

70-
### Connect by using Microsoft Entra ID
67+
You can use the [Azure identity client library for .NET](/dotnet/api/overview/azure/identity-readme) to authenticate your application with Microsoft Entra ID.
7168

7269
> [!NOTE]
7370
> If you're using Microsoft Entra ID to authorize access, then make sure that your security principal has been assigned the [Storage Blob Data Owner role](../../role-based-access-control/built-in-roles.md#storage-blob-data-owner). To learn more about how ACL permissions are applied and the effects of changing them, see [Access control model in Azure Data Lake Storage](./data-lake-storage-access-control-model.md).
7471
75-
You can use the [Azure identity client library for .NET](/dotnet/api/overview/azure/identity-readme) to authenticate your application with Microsoft Entra ID.
76-
77-
After you install the package, add this using statement to the top of your code file.
72+
First, assign one of the following [Azure role-based access control (Azure RBAC)](../../role-based-access-control/overview.md) roles to your security principal:
7873

79-
```csharp
80-
using Azure.Identity;
81-
```
82-
83-
First, you'll have to assign one of the following [Azure role-based access control (Azure RBAC)](../../role-based-access-control/overview.md) roles to your security principal:
84-
85-
|Role|ACL setting capability|
86-
|--|--|
87-
|[Storage Blob Data Owner](../../role-based-access-control/built-in-roles.md#storage-blob-data-owner)|All directories and files in the account.|
88-
|[Storage Blob Data Contributor](../../role-based-access-control/built-in-roles.md#storage-blob-data-contributor)|Only directories and files owned by the security principal.|
74+
| Role | ACL setting capability |
75+
| --- | --- |
76+
| [Storage Blob Data Owner](../../role-based-access-control/built-in-roles.md#storage-blob-data-owner) | All directories and files in the account. |
77+
| [Storage Blob Data Contributor](../../role-based-access-control/built-in-roles.md#storage-blob-data-contributor) | Only directories and files owned by the security principal. |
8978

9079
Next, create a [DataLakeServiceClient](/dotnet/api/azure.storage.files.datalake.datalakeserviceclient) instance and pass in a new instance of the [DefaultAzureCredential](/dotnet/api/azure.identity.defaultazurecredential) class.
9180

9281
:::code language="csharp" source="~/azure-storage-snippets/blobs/howto/dotnet/dotnet-v12/Authorize_DataLake.cs" id="Snippet_AuthorizeWithAAD":::
9382

9483
To learn more about using **DefaultAzureCredential** to authorize access to data, see [How to authenticate .NET applications with Azure services](/dotnet/azure/sdk/authentication#defaultazurecredential).
9584

96-
### Connect by using an account key
85+
### [Account key](#tab/account-key)
9786

9887
You can authorize access to data using your account access keys (Shared Key). This example creates a [DataLakeServiceClient](/dotnet/api/azure.storage.files.datalake.datalakeserviceclient) instance that is authorized with the account key.
9988

10089
:::code language="csharp" source="~/azure-storage-snippets/blobs/howto/dotnet/dotnet-v12/Authorize_DataLake.cs" id="Snippet_AuthorizeWithKey":::
10190

10291
[!INCLUDE [storage-shared-key-caution](../../../includes/storage-shared-key-caution.md)]
10392

93+
---
94+
10495
## Set ACLs
10596

10697
When you *set* an ACL, you **replace** the entire ACL including all of its entries. If you want to change the permission level of a security principal or add a new security principal to the ACL without affecting other existing entries, you should *update* the ACL instead. To update an ACL instead of replace it, see the [Update ACLs](#update-acls) section of this article.
@@ -160,7 +151,7 @@ This example updates the root ACL of a container by replacing the ACL entry for
160151

161152
### Update ACLs recursively
162153

163-
To update an ACL recursively, create a new ACL object with the ACL entry that you want to update, and then use that object in update ACL operation. Do not get the existing ACL, just provide ACL entries to be updated.
154+
To update an ACL recursively, create a new ACL object with the ACL entry that you want to update, and then use that object in update ACL operation. Don't get the existing ACL, just provide ACL entries to be updated.
164155

165156
Update an ACL recursively by calling the **DataLakeDirectoryClient.UpdateAccessControlRecursiveAsync** method. Pass this method a [List](/dotnet/api/system.collections.generic.list-1) of [PathAccessControlItem](/dotnet/api/azure.storage.files.datalake.models.pathaccesscontrolitem). Each [PathAccessControlItem](/dotnet/api/azure.storage.files.datalake.models.pathaccesscontrolitem) defines an ACL entry.
166157

@@ -187,7 +178,7 @@ This example updates the root ACL of a container by replacing the ACL entry for
187178

188179
### Remove ACL entries recursively
189180

190-
To remove ACL entries recursively, create a new ACL object for ACL entry to be removed, and then use that object in remove ACL operation. Do not get the existing ACL, just provide the ACL entries to be removed.
181+
To remove ACL entries recursively, create a new ACL object for ACL entry to be removed, and then use that object in remove ACL operation. Don't get the existing ACL, just provide the ACL entries to be removed.
191182

192183
Remove ACL entries by calling the **DataLakeDirectoryClient.RemoveAccessControlRecursiveAsync** method. Pass this method a [List](/dotnet/api/system.collections.generic.list-1) of [PathAccessControlItem](/dotnet/api/azure.storage.files.datalake.models.pathaccesscontrolitem). Each [PathAccessControlItem](/dotnet/api/azure.storage.files.datalake.models.pathaccesscontrolitem) defines an ACL entry.
193184

‎articles/storage/blobs/data-lake-storage-acl-java.md

Lines changed: 82 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ author: pauljewellmsft
66

77
ms.author: pauljewell
88
ms.service: azure-data-lake-storage
9-
ms.date: 02/07/2023
9+
ms.date: 09/06/2024
1010
ms.devlang: java
1111
ms.topic: how-to
1212
ms.reviewer: prishet
@@ -23,27 +23,87 @@ ACL inheritance is already available for new child items that are created under
2323

2424
## Prerequisites
2525

26-
- An Azure subscription. See [Get Azure free trial](https://azure.microsoft.com/pricing/free-trial/).
26+
- Azure subscription - [create one for free](https://azure.microsoft.com/free/).
27+
- Azure storage account that has hierarchical namespace (HNS) enabled. Follow [these instructions](create-data-lake-storage-account.md) to create one.
28+
- [Java Development Kit (JDK)](/java/azure/jdk/) version 8 or above.
29+
- [Apache Maven](https://maven.apache.org/download.cgi) is used for project management in this example.
30+
- Azure CLI version `2.6.0` or higher.
31+
- One of the following security permissions:
32+
- A provisioned Microsoft Entra ID [security principal](../../role-based-access-control/overview.md#security-principal) that has been assigned the [Storage Blob Data Owner](../../role-based-access-control/built-in-roles.md#storage-blob-data-owner) role, scoped to the target container, storage account, parent resource group, or subscription.
33+
- Owning user of the target container or directory to which you plan to apply ACL settings. To set ACLs recursively, this includes all child items in the target container or directory.
34+
- Storage account key.
2735

28-
- A storage account that has hierarchical namespace (HNS) enabled. Follow [these](create-data-lake-storage-account.md) instructions to create one.
36+
## Set up your project
2937

30-
- Azure CLI version `2.6.0` or higher.
38+
> [!NOTE]
39+
> This article uses the Maven build tool to build and run the sample code. Other build tools, such as Gradle, also work with the Azure SDK for Java.
3140
32-
- One of the following security permissions:
41+
Use Maven to create a new console app, or open an existing project. Follow these steps to install packages and add the necessary `import` directives.
3342

34-
- A provisioned Microsoft Entra ID [security principal](../../role-based-access-control/overview.md#security-principal) that has been assigned the [Storage Blob Data Owner](../../role-based-access-control/built-in-roles.md#storage-blob-data-owner) role, scoped to the target container, storage account, parent resource group, or subscription..
43+
### Install packages
3544

36-
- Owning user of the target container or directory to which you plan to apply ACL settings. To set ACLs recursively, this includes all child items in the target container or directory.
45+
Open the `pom.xml` file in your text editor. Install the packages by [including the BOM file](#include-the-bom-file), or [including a direct dependency](#include-a-direct-dependency).
3746

38-
- Storage account key.
47+
#### Include the BOM file
48+
49+
Add **azure-sdk-bom** to take a dependency on the latest version of the library. In the following snippet, replace the `{bom_version_to_target}` placeholder with the version number. Using **azure-sdk-bom** keeps you from having to specify the version of each individual dependency. To learn more about the BOM, see the [Azure SDK BOM README](https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/boms/azure-sdk-bom/README.md).
3950

40-
## Set up your project
51+
```xml
52+
<dependencyManagement>
53+
<dependencies>
54+
<dependency>
55+
<groupId>com.azure</groupId>
56+
<artifactId>azure-sdk-bom</artifactId>
57+
<version>{bom_version_to_target}</version>
58+
<type>pom</type>
59+
<scope>import</scope>
60+
</dependency>
61+
</dependencies>
62+
</dependencyManagement>
63+
```
64+
65+
Add the following dependency elements to the group of dependencies. The **azure-identity** dependency is needed for passwordless connections to Azure services.
66+
67+
```xml
68+
<dependency>
69+
<groupId>com.azure</groupId>
70+
<artifactId>azure-storage-file-datalake</artifactId>
71+
</dependency>
72+
<dependency>
73+
<groupId>com.azure</groupId>
74+
<artifactId>azure-storage-common</artifactId>
75+
</dependency>
76+
<dependency>
77+
<groupId>com.azure</groupId>
78+
<artifactId>azure-identity</artifactId>
79+
</dependency>
80+
```
4181

42-
To get started, open [this page](https://search.maven.org/artifact/com.azure/azure-storage-file-datalake) and find the latest version of the Java library. Then, open the *pom.xml* file in your text editor. Add a dependency element that references that version.
82+
#### Include a direct dependency
83+
84+
To take dependency on a particular version of the library, add the direct dependency to your project:
85+
86+
```xml
87+
<dependency>
88+
<groupId>com.azure</groupId>
89+
<artifactId>azure-storage-file-datalake</artifactId>
90+
<version>{package_version_to_target}</version>
91+
</dependency>
92+
<dependency>
93+
<groupId>com.azure</groupId>
94+
<artifactId>azure-storage-common</artifactId>
95+
<version>{package_version_to_target}</version>
96+
</dependency>
97+
<dependency>
98+
<groupId>com.azure</groupId>
99+
<artifactId>azure-identity</artifactId>
100+
<version>{package_version_to_target}</version>
101+
</dependency>
102+
```
43103

44-
If you plan to authenticate your client application by using Microsoft Entra ID, then add a dependency to the Azure Secret Client Library. See [Adding the Secret Client Library package to your project](https://github.com/Azure/azure-sdk-for-java/tree/master/sdk/identity/azure-identity#adding-the-package-to-your-project).
104+
### Include import directives
45105

46-
Next, add these imports statements to your code file.
106+
Add the necessary `import` directives. In this example, we add the following directives in the *App.java* file:
47107

48108
```java
49109
import com.azure.storage.common.StorageSharedKeyCredential;
@@ -67,35 +127,35 @@ import com.azure.storage.file.datalake.options.PathSetAccessControlRecursiveOpti
67127

68128
## Connect to the account
69129

70-
To use the snippets in this article, you'll need to create a **DataLakeServiceClient** instance that represents the storage account.
71-
72-
<a name='connect-by-using-azure-active-directory-azure-ad'></a>
130+
To run the code examples in this article, you need to create a [DataLakeServiceClient](/java/api/com.azure.storage.file.datalake.datalakeserviceclient) instance that represents the storage account. You can authorize the client object with Microsoft Entra ID credentials or with an account key.
73131

74-
### Connect by using Microsoft Entra ID
132+
### [Microsoft Entra ID (recommended)](#tab/entra-id)
75133

76134
You can use the [Azure identity client library for Java](https://github.com/Azure/azure-sdk-for-java/tree/master/sdk/identity/azure-identity) to authenticate your application with Microsoft Entra ID.
77135

78136
First, you'll have to assign one of the following [Azure role-based access control (Azure RBAC)](../../role-based-access-control/overview.md) roles to your security principal:
79137

80-
|Role|ACL setting capability|
81-
|--|--|
82-
|[Storage Blob Data Owner](../../role-based-access-control/built-in-roles.md#storage-blob-data-owner)|All directories and files in the account.|
83-
|[Storage Blob Data Contributor](../../role-based-access-control/built-in-roles.md#storage-blob-data-contributor)|Only directories and files owned by the security principal.|
138+
| Role | ACL setting capability |
139+
| --- | --- |
140+
| [Storage Blob Data Owner](../../role-based-access-control/built-in-roles.md#storage-blob-data-owner) | All directories and files in the account. |
141+
| [Storage Blob Data Contributor](../../role-based-access-control/built-in-roles.md#storage-blob-data-contributor) | Only directories and files owned by the security principal. |
84142

85143
Next, create a [DataLakeServiceClient](/java/api/com.azure.storage.file.datalake.datalakeserviceclient) instance and pass in a new instance of the [DefaultAzureCredential](/java/api/com.azure.identity.defaultazurecredential) class.
86144

87145
:::code language="java" source="~/azure-storage-snippets/blobs/howto/Java/Java-v12/src/main/java/com/datalake/manage/Authorize_DataLake.java" id="Snippet_AuthorizeWithAzureAD":::
88146

89-
To learn more about using **DefaultAzureCredential** to authorize access to data, see [Azure Identity client library for Java](/java/api/overview/azure/identity-readme).
147+
To learn more about using `DefaultAzureCredential` to authorize access to data, see [Azure Identity client library for Java](/java/api/overview/azure/identity-readme).
90148

91-
### Connect by using an account key
149+
### [Account key](#tab/account-key)
92150

93151
You can authorize access to data using your account access keys (Shared Key). This example creates a [DataLakeServiceClient](/dotnet/api/azure.storage.files.datalake.datalakeserviceclient) instance that is authorized with the account key.
94152

95153
:::code language="java" source="~/azure-storage-snippets/blobs/howto/Java/Java-v12/src/main/java/com/datalake/manage/Authorize_DataLake.java" id="Snippet_AuthorizeWithKey":::
96154

97155
[!INCLUDE [storage-shared-key-caution](../../../includes/storage-shared-key-caution.md)]
98156

157+
---
158+
99159
## Set ACLs
100160

101161
When you *set* an ACL, you **replace** the entire ACL including all of its entries. If you want to change the permission level of a security principal or add a new security principal to the ACL without affecting other existing entries, you should *update* the ACL instead. To update an ACL instead of replace it, see the [Update ACLs](#update-acls) section of this article.

0 commit comments

Comments
 (0)