Azure Data Lake Storage で PowerShell を使用して ACL を管理する

この記事では、PowerShellを使ってディレクトリやファイルのアクセス制御リスト(ACL)を取得し、設定し、更新する方法を紹介します。

親ディレクトリの下に新たに作成した子項目は自動的にACLを継承します。 しかし、親ディレクトリの既存の子項目に対して、個別に変更を加えることなく再帰的にACLを追加・更新・削除することも可能です。

参照 | フィードバックの送信

前提条件

• Azure サブスクリプション。 詳細については、Azure 無料試用版の取得に関するページを参照してください。

• 階層型名前空間 (HNS) が有効になっているストレージ アカウント。 作成するには、こちらの手順に従います。

• 以下のセキュリティ アクセス許可のいずれか:

  • プロビジョニング済みの Microsoft Entra ID のセキュリティ プリンシパルで、ターゲット コンテナー、ストレージ アカウント、親リソース グループ、またはサブスクリプションをスコープとしてStorage Blob Data Ownerロールが割り当てられているもの。

  • ACL 設定を適用する予定のターゲット コンテナーまたはディレクトリの所有ユーザー。 ACLを再帰的に設定するには、このユーザーはターゲットコンテナやディレクトリ内のすべての子項目を含みます。

PowerShell モジュールをインストールする

1. インストールしたPowerShellのバージョンが 5.1 以上であるか、以下のコマンドを使って確認してください。

   echo $PSVersionTable.PSVersion.ToString()
   

   PowerShellのバージョンをアップグレードするには、「既存のWindows PowerShellのアップグレード」をご覧ください。

2. Az.Storage モジュールをインストールします。

   Install-Module Az.Storage -Repository PSGallery -Force  
   

   PowerShellモジュールのインストール方法については、「Azure PowerShellモジュールのインストール」をご覧ください。

アカウントに接続する

1. Windows PowerShell コマンド ウィンドウを開き、Connect-AzAccount コマンドで Azure サブスクリプションにサインインし、画面上の指示に従います。

   Connect-AzAccount
   

2. もしあなたのアイデンティティが複数のサブスクリプションに紐づいていて、サブスクリプションを選択するよう促さない場合は、アクティブなサブスクリプションを使いたいストレージアカウントのサブスクリプションに設定してください。 この例では、<subscription-id> プレースホルダーの値をサブスクリプションの ID に置き換えます。

   Select-AzSubscription -SubscriptionId <subscription-id>
   

3. ストレージ アカウント コンテキストを取得します。

   $ctx = New-AzStorageContext -StorageAccountName '<storage-account-name>' -UseConnectedAccount
   

ACL を取得する

Get-AzDataLakeGen2Item コマンドレットを使用して、ディレクトリまたはファイルの ACL を取得します。

Azure Data Lake Storageでは、コンテナはファイルシステムとも呼ばれます。 以下の例で使われる -FileSystem パラメータは、あなたのコンテナの名前を名乗っています。

以下の例では 、コンテナ のルートディレクトリの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を取得し、それをコンソールにプリントします。

$filePath = "my-directory/upload.txt"
$file = Get-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $filePath
$file.ACL

次の画像は、ディレクトリの ACL を取得した後の出力を示しています。

この例では、所有ユーザーには読み取り、書き込み、実行のアクセス許可があります。 所有グループには、読み取りと実行のアクセス許可のみがあります。 アクセス制御リストの詳細については、「Azure Data Lake Storage のアクセス制御」を参照してください。

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

この例では、所有ユーザー、所有グループ、または他のユーザーのファイルに 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

次の画像は、ファイルの ACL を設定した後の出力を示しています。

この例では、所有ユーザーと所有グループには、読み取りと書き込みのアクセス許可のみがあります。 他のすべてのユーザーには、書き込みと実行のアクセス許可があります。 アクセス制御リストの詳細については、「Azure Data Lake Storage のアクセス制御」を参照してください。

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

バッチ サイズを指定してバッチ内の 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 aaaaaaaa-bbbb-cccc-1111-222222222222 -Permission r-x -InputObject $acl
Update-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $dirname -Acl $acl

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

バッチ サイズを指定してバッチ内の ACL を再帰的に更新する例については、Update-AzDataLakeGen2AclRecursive のリファレンス記事をご覧ください。

ACL エントリを削除する

ここでは、次の操作方法について説明します。

• ACL エントリを削除する
• ACL エントリを再帰的に削除する

ACL エントリを削除する

この例では、既存の ACL からエントリを削除します。 $ctxストレージアカウントのコンテキストや、この記事の前述で確立した$acl、$filesystemName、$dirname変数を再利用しています。

$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オブジェクトを作成し、そのオブジェクトをremove 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

バッチ サイズを指定してバッチ内の ACL を再帰的に削除する例については、Remove-AzDataLakeGen2AclRecursive のリファレンス記事をご覧ください。

エラーからの復旧

ACL を再帰的に変更するときに、実行時またはアクセス許可のエラーが発生する場合があります。 この節の例は、 $ctx ストレージアカウントのコンテキストと、この記事の前述で確立された $filesystemName、 $dirname、 $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.TotalDirectoriesSuccessfulCount)"
echo "TotalFilesSuccessfulCount: `t`t`t$($result.TotalFilesSuccessfulCount)"
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 でのアクセス制御に関するページを参照してください。

関連項目

• 既知の問題
• Storage PowerShell コマンドレット
• Azure Data Lake Storage のアクセス制御モデル
• Azure Data Lake Storage のアクセス制御リスト (ACL)