Azure Data Lake Storage Gen2 で PowerShell を使用して ACL を管理する
この記事では、PowerShell を使用して、ディレクトリとファイルのアクセス制御リストを取得、設定、更新する方法について説明します。
ACL の継承は、親ディレクトリの下に作成された新しい子項目に対して既に利用可能です。 しかし、親ディレクトリの既存の子項目に対して ACL を再帰的に追加、更新、および削除することもできます。それぞれの子項目に対してこれらの変更を個別に行う必要はありません。
参照 | フィードバックの送信
前提条件
Azure サブスクリプション。 詳細については、Azure 無料試用版の取得に関するページを参照してください。
階層型名前空間 (HNS) が有効になっているストレージ アカウント。 作成するには、こちらの手順に従います。
Azure CLI バージョン
2.6.0以上。次のセキュリティのアクセス許可のいずれか。
ターゲット コンテナー、ストレージ アカウント、親リソース グループ、またはサブスクリプションのスコープでストレージ BLOB データ所有者ロールが割り当てられた、プロビジョニングされた Microsoft Entra ID セキュリティ プリンシパル。
ACL 設定を適用する予定のターゲット コンテナーまたはディレクトリの所有ユーザー。 ACL を再帰的に設定する場合、これには、ターゲット コンテナーまたはディレクトリ内のすべての子項目が含まれます。
ストレージ アカウント キー。
PowerShell モジュールをインストールする
次のコマンドを使用して、インストールされている PowerShell のバージョンが
5.1以降であることを確認します。echo $PSVersionTable.PSVersion.ToString()お使いの PowerShell のバージョンをアップグレードするには、「既存の Windows PowerShell をアップグレードする」を参照してください。
Az.Storage モジュールをインストールします。
Install-Module Az.Storage -Repository PSGallery -ForcePowerShell モジュールのインストール方法の詳細については、「Azure PowerShell モジュールのインストール」を参照してください。
アカウントに接続する
コマンドでストレージ アカウントに対する承認を取得する方法を選択します。
オプション 1: Microsoft Entra ID を使用して認可を取得する
Note
Microsoft Entra ID を使用してアクセスを認可している場合は、セキュリティ プリンシパルにストレージ BLOB データ所有者ロールが割り当てられていることを確認します。 ACL アクセス許可の適用方法とその変更による影響の詳細については、「Azure Data Lake Storage Gen2 のアクセス制御モデル」を参照してください。
この方法を使用すると、ご利用のユーザー アカウントに、適切な Azure ロールベースのアクセス制御 (Azure RBAC) の割り当てと ACL のアクセス許可がシステムによって確実に付与されます。
Windows PowerShell コマンド ウィンドウを開き、
Connect-AzAccountコマンドで Azure サブスクリプションにサインインし、画面上の指示に従います。Connect-AzAccount自分の ID が複数のサブスクリプションに関連付けられている場合は、アクティブなサブスクリプションを、ディレクトリを作成して管理するストレージ アカウントのサブスクリプションに設定します。 この例では、
<subscription-id>プレースホルダーの値をサブスクリプションの ID に置き換えます。Select-AzSubscription -SubscriptionId <subscription-id>ストレージ アカウント コンテキストを取得します。
$ctx = New-AzStorageContext -StorageAccountName '<storage-account-name>' -UseConnectedAccount
オプション 2:ストレージ アカウント キーを使用して承認を取得する
この方法を使用する場合、Azure RBAC アクセス許可も、ACL アクセス許可もシステムによってチェックされません。 アカウント キーを使用して、ストレージ アカウント コンテキストを取得します。
$ctx = New-AzStorageContext -StorageAccountName '<storage-account-name>' -StorageAccountKey '<storage-account-key>'
ACL を取得する
Get-AzDataLakeGen2Item コマンドレットを使用して、ディレクトリまたはファイルの ACL を取得します。
この例では、コンテナーのルート ディレクトリの ACL を取得し、その ACL をコンソールに出力します。
$filesystemName = "my-file-system"
$filesystem = Get-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName
$filesystem.ACL
この例では、ディレクトリの ACL を取得し、その ACL をコンソールに出力します。
$filesystemName = "my-file-system"
$dirname = "my-directory/"
$dir = Get-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $dirname
$dir.ACL
この例では、ファイルの ACL を取得し、その ACL をコンソールに出力します。
$filePath = "my-directory/upload.txt"
$file = Get-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $filePath
$file.ACL
次の画像は、ディレクトリの ACL を取得した後の出力を示しています。
この例では、所有ユーザーには読み取り、書き込み、実行のアクセス許可があります。 所有グループには、読み取りと実行のアクセス許可のみがあります。 アクセス制御リストの詳細については、「Azure Data Lake Storage Gen2 のアクセス制御」を参照してください。
ACL を設定する
ACL を "設定する" 場合は、ACL 全体 (そのすべてのエントリを含む) を置換します。 セキュリティ プリンシパルのアクセス許可レベルの変更または ACL への新しいセキュリティ プリンシパルの追加を、他の既存のエントリに影響を与えることなく行いたい場合は、代わりに ACL を "更新" する必要があります。 ACL を置換するのでなく更新するには、この記事の「ACL を更新する」セクションを参照してください。
ACL を "設定" する場合は、所有ユーザーのエントリ、所有グループのエントリ、および他のすべてのユーザーのエントリを追加する必要があります。 所有ユーザー、所有グループ、およびその他のすべてのユーザーの詳細については、「ユーザーと ID」を参照してください。
ここでは、次の操作方法について説明します。
- ACL を設定する
- ACL を再帰的に設定する
ACL を設定する
Set-AzDataLakeGen2ItemAclObject コマンドレットを使用して、所有ユーザー、所有グループ、またはその他のユーザーの ACL を作成します。 その後、Update-AzDataLakeGen2Item コマンドレットを使用して ACL をコミットします。
この例では、所有ユーザー、所有グループ、またはその他のユーザーのコンテナーのルート ディレクトリに ACL を設定し、その ACL をコンソールに出力します。
$filesystemName = "my-file-system"
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -Permission rw-
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType group -Permission rw- -InputObject $acl
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType other -Permission -wx -InputObject $acl
Update-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Acl $acl
$filesystem = Get-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName
$filesystem.ACL
この例では、所有ユーザー、所有グループ、または他のユーザーのディレクトリに ACL を設定し、その ACL をコンソールに出力します。
$filesystemName = "my-file-system"
$dirname = "my-directory/"
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -Permission rw-
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType group -Permission rw- -InputObject $acl
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType other -Permission -wx -InputObject $acl
Update-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $dirname -Acl $acl
$dir = Get-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $dirname
$dir.ACL
Note
既定の ACL エントリを設定する場合は、Set-AzDataLakeGen2ItemAclObject コマンドを実行するときに -DefaultScope パラメーターを使用します。 (例: $acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -Permission rwx -DefaultScope)。
この例では、所有ユーザー、所有グループ、または他のユーザーのファイルに ACL を設定し、その ACL をコンソールに出力します。
$filesystemName = "my-file-system"
$filePath = "my-directory/upload.txt"
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -Permission rw-
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType group -Permission rw- -InputObject $acl
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType other -Permission "-wx" -InputObject $acl
Update-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $filePath -Acl $acl
$file = Get-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $filePath
$file.ACL
Note
特定のグループまたはユーザー、サービス プリンシパル、マネージド ID の ACL を設定するには、それぞれのオブジェクト ID を使用します。 たとえば、グループの ACL を設定するには、group:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx を使用します。 ユーザーの ACL を設定するには、user:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx を使用します。
次の画像は、ファイルの ACL を設定した後の出力を示しています。
この例では、所有ユーザーと所有グループには、読み取りと書き込みのアクセス許可のみがあります。 他のすべてのユーザーには、書き込みと実行のアクセス許可があります。 アクセス制御リストの詳細については、「Azure Data Lake Storage Gen2 のアクセス制御」を参照してください。
ACL を再帰的に設定する
Set-AzDataLakeGen2AclRecursive コマンドレットを使用して、ACL を再帰的に設定します。
この例では、my-parent-directory という名前のディレクトリの ACL を設定します。 これらのエントリでは、所有ユーザーには読み取り、書き込み、実行のアクセス許可を付与し、所有グループには読み取りと実行のアクセス許可のみを付与し、他のすべてのユーザーにはアクセスを許可しません。 この例の最後の ACL エントリでは、"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" というオブジェクト ID を持つ特定のユーザーに、読み取りと実行のアクセス許可を付与しています。
$filesystemName = "my-container"
$dirname = "my-parent-directory/"
$userID = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -Permission rwx
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType group -Permission r-x -InputObject $acl
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType other -Permission "---" -InputObject $acl
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -EntityId $userID -Permission r-x -InputObject $acl
Set-AzDataLakeGen2AclRecursive -Context $ctx -FileSystem $filesystemName -Path $dirname -Acl $acl
Note
既定の ACL エントリを設定する場合は、Set-AzDataLakeGen2ItemAclObject コマンドを実行するときに -DefaultScope パラメーターを使用します。 (例: $acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -Permission rwx -DefaultScope)。
バッチ サイズを指定してバッチ内の ACL を再帰的に設定する例については、Set-AzDataLakeGen2AclRecursive のリファレンス記事をご覧ください。
ACL を更新する
ACL を "更新する" 場合は、ACL を置換するのでなく ACL を変更します。 たとえば、ACL にリストされている他のセキュリティ プリンシパルに影響を与えることなく、新しいセキュリティ プリンシパルを ACL に追加することができます。 ACL を更新するのでなく、置換する場合は、この記事の「ACL を設定する」セクションを参照してください。
ここでは、次の操作方法について説明します。
- ACL を更新する
- ACL を再帰的に更新する
ACL を更新する
まず、ACL を取得します。 次に、Set-AzDataLakeGen2ItemAclObject コマンドレットを使用して、ACL エントリを追加または更新します。 Update-AzDataLakeGen2Item コマンドレットを使用して ACL をコミットします。
この例では、ユーザーのディレクトリで ACL を作成または更新します。
$filesystemName = "my-file-system"
$dirname = "my-directory/"
$acl = (Get-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $dirname).ACL
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -EntityID xxxxxxxx-xxxx-xxxxxxxxxxx -Permission r-x -InputObject $acl
Update-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $dirname -Acl $acl
Note
既定の ACL エントリを更新する場合は、Set-AzDataLakeGen2ItemAclObject コマンドを実行するときに -DefaultScope パラメーターを使用します。 (例: $acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -EntityID xxxxxxxx-xxxx-xxxxxxxxxxx -Permission r-x -DefaultScope)。
ACL を再帰的に更新する
Update-AzDataLakeGen2AclRecursive コマンドレットを使用して、ACL を再帰的に更新します。
この例では、書き込みアクセス許可を持つ ACL エントリを更新します。
$filesystemName = "my-container"
$dirname = "my-parent-directory/"
$userID = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -EntityId $userID -Permission rwx
Update-AzDataLakeGen2AclRecursive -Context $ctx -FileSystem $filesystemName -Path $dirname -Acl $acl
Note
特定のグループまたはユーザー、サービス プリンシパル、マネージド ID の ACL を設定するには、それぞれのオブジェクト ID を使用します。 たとえば、グループの ACL を設定するには、group:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx を使用します。 ユーザーの ACL を設定するには、user:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx を使用します。
バッチ サイズを指定してバッチ内の ACL を再帰的に更新する例については、Update-AzDataLakeGen2AclRecursive のリファレンス記事をご覧ください。
ACL エントリを削除する
ここでは、次の操作方法について説明します。
- ACL エントリを削除する
- ACL エントリを再帰的に削除する
ACL エントリを削除する
この例では、既存の ACL からエントリを削除します。
$id = "xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
# Create the new ACL object.
[Collections.Generic.List[System.Object]]$aclnew =$acl
foreach ($a in $aclnew)
{
if ($a.AccessControlType -eq "User" -and $a.DefaultScope -eq $false -and $a.EntityId -eq $id)
{
$aclnew.Remove($a);
break;
}
}
Update-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $dirname -Acl $aclnew
ACL エントリを再帰的に削除する
1 つ以上の ACL エントリを再帰的に削除できます。 ACL エントリを削除するには、削除する ACL エントリ用に新しい ACL オブジェクトを作成してから、そのオブジェクトを ACL の削除操作で使用します。 既存の ACL は取得せずに、削除する ACL エントリを指定するだけです。
Remove-AzDataLakeGen2AclRecursive コマンドレットを使用して、ACL エントリを再帰的に削除します。
この例では、コンテナーのルート ディレクトリから ACL エントリを削除します。
$filesystemName = "my-container"
$userID = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -EntityId $userID -Permission "---"
Remove-AzDataLakeGen2AclRecursive -Context $ctx -FileSystem $filesystemName -Acl $acl
Note
既定の ACL エントリを削除する場合は、Set-AzDataLakeGen2ItemAclObject コマンドを実行するときに -DefaultScope パラメーターを使用します。 (例: $acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -EntityId $userID -Permission "---" -DefaultScope)。
バッチ サイズを指定してバッチ内の ACL を再帰的に削除する例については、Remove-AzDataLakeGen2AclRecursive のリファレンス記事をご覧ください。
エラーからの復旧
ACL を再帰的に変更するときに、実行時またはアクセス許可のエラーが発生する場合があります。
実行時エラーが発生した場合は、プロセスを最初から再開します。 アクセス許可エラーは、セキュリティ プリンシパルに、変更対象のディレクトリ階層内にあるディレクトリまたはファイルの ACL を変更するための十分なアクセス許可がない場合に発生する可能性があります。 アクセス許可の問題を解決してから、継続トークンを使用してエラーの発生時点からプロセスを再開するか、最初からプロセスを再開するかを選択します。 最初から再開する場合は、継続トークンを使用する必要はありません。 ACL エントリは、悪影響を及ぼすことなく再適用できます。
この例では、結果を変数に返し、失敗したエントリを書式設定されたテーブルにパイプします。
$result = Set-AzDataLakeGen2AclRecursive -Context $ctx -FileSystem $filesystemName -Path $dirname -Acl $acl
$result
$result.FailedEntries | ft
テーブルの出力に基づいて、アクセス許可のエラーを修正し、継続トークンを使用して実行を再開できます。
$result = Set-AzDataLakeGen2AclRecursive -Context $ctx -FileSystem $filesystemName -Path $dirname -Acl $acl -ContinuationToken $result.ContinuationToken
$result
バッチ サイズを指定してバッチ内の ACL を再帰的に設定する例については、Set-AzDataLakeGen2AclRecursive のリファレンス記事をご覧ください。
アクセス許可エラーによって中断されずにプロセスを完了したい場合は、それを指定できます。
この例では、ContinueOnFailure パラメーターを使用して、操作中にアクセス許可エラーが検出された場合でも実行が継続されるようにします。
$result = Set-AzDataLakeGen2AclRecursive -Context $ctx -FileSystem $filesystemName -Path $dirname -Acl $acl -ContinueOnFailure
echo "[Result Summary]"
echo "TotalDirectoriesSuccessfulCount: `t$($result.TotalFilesSuccessfulCount)"
echo "TotalFilesSuccessfulCount: `t`t`t$($result.TotalDirectoriesSuccessfulCount)"
echo "TotalFailureCount: `t`t`t`t`t$($result.TotalFailureCount)"
echo "FailedEntries:"$($result.FailedEntries | ft)
バッチ サイズを指定してバッチ内の ACL を再帰的に設定する例については、Set-AzDataLakeGen2AclRecursive のリファレンス記事をご覧ください。
ベスト プラクティス
このセクションでは、ACL を再帰的に設定するためのベスト プラクティス ガイドラインについて説明します。
実行時エラーの処理
実行時エラーは、さまざまな理由で発生する可能性があります (たとえば、停電やクライアント接続の問題など)。 実行時エラーが発生した場合は、再帰的な ACL プロセスを再開します。 ACL は、悪影響を及ぼすことなく項目に再適用できます。
アクセス許可エラー (403) の処理
再帰的な ACL プロセスの実行中にアクセス制御の例外が発生した場合、AD のセキュリティ プリンシパルに、ディレクトリ階層内にある 1 つ以上の子項目に ACL を適用するための十分なアクセス許可がない可能性があります。 アクセス許可エラーが発生すると、プロセスが停止し、継続トークンが提供されます。 アクセス許可の問題を修正してから、継続トークンを使用して残りのデータセットを処理します。 既に正常に処理済みのディレクトリとファイルをもう一度処理する必要はありません。 再帰的な ACL プロセスを再開することも選択できます。 ACL は、悪影響を及ぼすことなく項目に再適用できます。
資格情報
ターゲット ストレージ アカウントまたはコンテナーのスコープでストレージ BLOB データ所有者ロールが割り当てられている、Microsoft Entra セキュリティ プリンシパルをプロビジョニングすることをお勧めします。
パフォーマンス
待機時間を短縮するには、ストレージ アカウントと同じリージョンにある Azure 仮想マシン (VM) で再帰的な ACL プロセスを実行することをお勧めします。
ACL の制限
ディレクトリまたはファイルに適用できる ACL の最大数は、アクセス ACL が 32 個と既定 ACL が 32 個です。 詳細については、Azure Data Lake Storage Gen2 でのアクセス制御に関するページを参照してください。