Использование PowerShell для управления списками ACL в Azure Data Lake Storage 2-го поколения

В этой статье показано, как использовать PowerShell для получения, настройки и обновления списков управления доступом к каталогам и файлам.

Наследование ACL уже доступно для новых дочерних элементов, созданных в родительском каталоге. Но можно также добавлять, обновлять и удалять списки управления доступом для существующих дочерних элементов родительского каталога без необходимости вносить эти изменения отдельно для каждого дочернего элемента.

Справочные материалы | Отправить отзыв

Необходимые компоненты

• Подписка Azure. См. дополнительные сведения о бесплатной пробной версии Azure.

• В учетной записи хранения включено иерархическое пространство имен. Выполните эти инструкции, чтобы создать учетную запись.

• Azure CLI версии2.6.0 или выше.

• Одно из следующих разрешений безопасности:

  • Подготовленный субъект безопасности Идентификатора Microsoft Entra, которому назначена роль владельца данных большого двоичного объекта служба хранилища, область в целевой контейнер, учетную запись хранения, родительскую группу ресурсов или подписку.

  • Пользователь-владелец целевого контейнера или каталога, к которому планируется применять параметры 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. Получение авторизации с помощью идентификатора Microsoft Entra

При таком подходе система гарантирует, что ваша учетная запись пользователя имеет соответствующие разрешения доступа на основе ролей Azure (Azure RBAC) и ACL.

1. Откройте окно управления Windows PowerShell, затем войдите в свою подписку Azure с помощью команды Connect-AzAccount и следуйте инструкциям на экране.

   Connect-AzAccount
   

2. Если удостоверение связано с несколькими подписками, установите в качестве активной подписку учетной записи хранения, в которой нужно создавать папки и управлять ими. В этом примере замените значение заполнителя <subscription-id> идентификатором своей подписки.

   Select-AzSubscription -SubscriptionId <subscription-id>
   

3. Получите объект контекста учетной записи хранения.

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

Вариант 2. Авторизация с помощью ключа учетной записи хранения

При таком подходе система не проверяет разрешения Azure RBAC или ACL. Получите контекст учетной записи хранения с помощью ключа учетной записи.

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

Получение ACL

Получите ACL для каталога или файла с помощью командлета Get-AzDataLakeGen2Item.

В этом примере ACL сначала извлекается для корневого каталога контейнера, а затем выводится на консоль.

$filesystemName = "my-file-system"
$filesystem = Get-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName
$filesystem.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 2-го поколения см. на этой странице.

Настройка списков ACL

Настраивая список ACL, вы заменяете его целиком, включая все его записи. Если вы хотите изменить уровень разрешений субъекта безопасности или добавить новый субъект безопасности в список управления доступом, не затрагивая другие существующие записи, следует обновить ACL. Сведения о том, как обновить список управления доступом вместо его замены, см. в разделе Обновление списков ACL этой статьи.

Если вы решили настроить ACL, необходимо добавить запись для пользователя-владельца, запись для группы-владельца и запись для всех других пользователей. Дополнительные сведения о пользователе-владельце, группе-владельце и других пользователях см. в разделе Пользователи и удостоверения.

В этом разделе показано, как выполнять следующие действия.

• Настройка списка ACL
• Рекурсивная настройка ACL

Настройка списка ACL

Используйте командлет Set-AzDataLakeGen2ItemAclObject, чтобы создать список ACL для пользователя-владельца, группы-владельца или других пользователей. Затем используйте командлет Update-AzDataLakeGen2Item для фиксации 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 задается для каталога пользователя-владельца, группы-владельца или других пользователей, а затем выводится на консоль.

$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 задается для файла пользователя-владельца, группы-владельца или других пользователей, а затем выводится на консоль.

$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 2-го поколения см. на этой странице.

Рекурсивная настройка ACL

Настраивайте списки управления доступом рекурсивно с помощью командлета Set-AzDataLakeGen2AclRecursive.

В этом примере список ACL задается для каталога my-parent-directory. Эти записи предоставляют пользователю-владельцу права на чтение, запись и выполнение, группе-владельцу предоставляются разрешения только на чтение и выполнение, а всем остальным доступ не предоставляется. Последняя запись ACL в этом примере предоставляет отдельному пользователю с идентификатором xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx разрешения на чтение и выполнение.

$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. Затем с помощью командлета 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

Рекурсивное обновление ACL

Обновляйте списки управления доступом рекурсивно с помощью командлета Update-AzDataLakeGen2AclRecursive.

В этом примере обновляется запись 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.

$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

Можно рекурсивно удалить одну или несколько записей ACL. Чтобы удалить запись ACL, создайте новый объект ACL для удаляемой записи ACL, а затем используйте этот объект в операции удаления ACL. Не изменяйте существующий список ACL, просто предоставьте записи ACL, которые необходимо удалить.

Удалите записи ACL с помощью командлета Remove-AzDataLakeGen2AclRecursive.

В этом примере удаляется запись 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 могут возникать ошибки времени выполнения или разрешений.

При ошибках времени выполнения перезапустите процесс с самого начала. Ошибки разрешений могут возникать, если субъект безопасности не имеет достаточных разрешений для изменения 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. Списки управления доступом можно повторно применить к элементам без негативного воздействия.

Обработка ошибок разрешений (403)

Если при выполнении процесса рекурсивной настройки ACL возникает исключение управления доступом, возможно, что субъект безопасности Active Directory не имеет достаточных разрешений для применения ACL к одному или нескольким дочерним элементам в иерархии каталогов. При возникновении ошибки, связанной с разрешением, процесс останавливается и предоставляется маркер продолжения. Устраните проблему с разрешениями, а затем используйте маркер продолжения для обработки оставшегося набора данных. Каталоги и файлы, которые уже были успешно обработаны, не должны обрабатываться повторно. Можно также перезапустить процесс рекурсивной настройки ACL. Списки управления доступом можно повторно применить к элементам без негативного воздействия.

Учетные данные

Рекомендуется подготовить субъект безопасности Microsoft Entra, которому назначена роль владельца данных большого двоичного объекта служба хранилища в область целевой учетной записи хранения или контейнера.

Производительность

Чтобы сократить задержку, рекомендуется запустить процесс рекурсивной настройки ACL на виртуальной машине Azure, расположенной в том же регионе, что и учетная запись хранения.

Ограничения для списков управления доступом

Максимальное число списков управления доступом, которое можно применить к каталогу или файлу, составляет 32 списка для доступа и 32 списка по умолчанию. Дополнительные сведения см. в статье Контроль доступа в Azure Data Lake Storage 2-го поколения.

См. также

• Известные проблемы
• Командлеты PowerShell для службы хранилища
• Модель управления доступом в Azure Data Lake Storage 2-го поколения
• Списки управления доступом (ACL) в Azure Data Lake Storage 2-го поколения