使用 Azure CLI 管理 Azure Data Lake Storage Gen2 中的 ACL
此文章說明如何使用 Azure CLI 來取得、設定及更新目錄和檔案的存取控制清單。
在上層目錄底下新建的下層項目已可使用 ACL 繼承。 但是您也可以在父目錄的現有子項目上以遞迴方式新增、更新和移除 ACL，而不需要針對每個子項目個別進行這些變更。
必要條件
Azure 訂用帳戶。 如需詳細資訊，請參閱取得 Azure 免費試用。
已啟用階層命名空間的儲存體帳戶。 遵循下列指示以建立帳戶。
Azure CLI
2.14.0版或更高版本。下列其中一個安全性權限：
在目標容器、儲存體帳戶、父資源群組或訂用帳戶的範圍中，已獲指派儲存體 Blob 資料擁有者角色的已佈建 Microsoft Entra ID 安全性主體。
您計劃套用 ACL 設定的目標容器或目錄的擁有使用者。 若要以遞迴方式設定 ACL，這包括目標容器或目錄中的所有子項目。
儲存體帳戶金鑰。
請確保您已安裝正確版本的 Azure CLI
開啟 Azure Cloud Shell，或如果您已在本機安裝 Azure CLI，請開啟命令主控台應用程式，例如 Windows PowerShell。
使用下列命令，確認已安裝的 Azure CLI 版本為
2.14.0或更高版本。az --version如果您的 Azure CLI 版本低於
2.14.0，請安裝較新的版本。 如需詳細資訊，請參閱 安裝 Azure CLI。
連線到帳戶
如果您在本機使用 Azure CLI，請執行登入命令。
az login如果此 CLI 可以開啟您的預設瀏覽器，它會開啟瀏覽器並載入 Azure 登入頁面。
否則，請在 https://aka.ms/devicelogin 中開啟瀏覽器頁面，並輸入顯示在您的終端機中的授權碼。 然後，請在瀏覽器中使用您的帳戶認證登入。
若要深入了解不同的驗證方法，請參閱使用 Azure CLI 授與 Blob 或佇列資料的存取權。
如果您的身分識別與多個訂閱相關聯，請將您的使用中訂閱設為將代管靜態網站的儲存體帳戶的訂閱。
az account set --subscription <subscription-id>使用訂閱識別碼取代
<subscription-id>預留位置值。
注意
本文中所述的範例會顯示 Microsoft Entra 授權。 若要深入了解授權方法，請參閱使用 Azure CLI 授與 Blob 或佇列資料的存取權。
取得 ACL
使用 az storage fs access show 命令取得目錄的 ACL。
此範例會取得目錄的 ACL，然後將 ACL 列印到主控台。
az storage fs access show -p my-directory -f my-file-system --account-name mystorageaccount --auth-mode login
使用 az storage fs access show 命令取得檔案的存取權限。
此範例取得檔案的 ACL，然後將 ACL 列印到主控台。
az storage fs access show -p my-directory/upload.txt -f my-file-system --account-name mystorageaccount --auth-mode login
下圖顯示取得目錄的 ACL 之後的輸出。
在此範例中，擁有使用者具有讀取、寫入和執行權限。 擁有群組只有讀取和執行權限。 如需存取控制清單的詳細資訊，請參閱 Azure Data Lake Storage Gen2 中的存取控制。
設定 ACL
當您設定 ACL 時，將會取代整個 ACL，包括其所有項目。 如果您想要變更安全性主體的權限層級，或將新的安全性主體新增至 ACL，而不會影響其他現有的項目，您應該改為更新 ACL。 若要更新 ACL 而非取代，請參閱本文的更新 ACL 一節。
如果您選擇設定 ACL，則必須新增擁有使用者的項目、擁有群組的項目，以及所有其他使用者的項目。 若要深入了解擁有使用者、擁有群組和所有其他使用者，請參閱使用者和身分識別。
本節說明如何：
- 設定 ACL
- 以遞迴方式設定 ACL
設定 ACL
使用 az storage fs access set 命令設定目錄的 ACL。
此範例會針對擁有使用者、擁有群組，或其他使用者，在目錄上設定 ACL，然後將 ACL 列印到主控台。
az storage fs access set --acl "user::rw-,group::rw-,other::-wx" -p my-directory -f my-file-system --account-name mystorageaccount --auth-mode login
此範例會針對擁有使用者、擁有群組，或其他使用者，在目錄上設定預設 ACL，然後將 ACL 列印到主控台。
az storage fs access set --acl "default:user::rw-,group::rw-,other::-wx" -p my-directory -f my-file-system --account-name mystorageaccount --auth-mode login
使用 az storage fs access set 命令設定檔案的 ACL。
此範例會針對擁有使用者、擁有群組，或其他使用者，在檔案上設定 ACL，然後將 ACL 列印到主控台。
az storage fs access set --acl "user::rw-,group::rw-,other::-wx" -p my-directory/upload.txt -f my-file-system --account-name mystorageaccount --auth-mode login
注意
若要設定特定群組或使用者的 ACL，請使用其各自的物件識別碼。 例如，若要設定群組的 ACL，請使用 group:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx。 若要設定使用者的 ACL，請使用 user:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx。
下圖顯示設定檔案的 ACL 之後的輸出。
在此範例中，擁有使用者和擁有群組只有讀取和寫入權限。 所有其他使用者具備寫入和執行權限。 如需存取控制清單的詳細資訊，請參閱 Azure Data Lake Storage Gen2 中的存取控制。
以遞迴方式設定 ACL
使用 az storage fs access set-recursive 命令以遞迴方式設定 ACL。
此範例會設定名為 my-parent-directory 目錄的 ACL。 這些項目會為擁有使用者提供讀取、寫入及執行權限，僅為擁有群組提供讀取和執行權限，對所有其他人員不提供任何權限。 此範例的最後一個 ACL 項目會提供物件識別碼 "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" 讀取和執行權限給特定使用者。
az storage fs access set-recursive --acl "user::rwx,group::r-x,other::---,user:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx:r-x" -p my-parent-directory/ -f my-container --account-name mystorageaccount --auth-mode login
注意
如果您想要設定預設 ACL 項目，請將前置詞 default: 新增至每個項目。 例如，default:user::rwx 或 default:user:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx:r-x。
更新 ACL
當您更新 ACL 時，您會修改 ACL 而不是取代 ACL。 例如，您可以將新的安全性主體新增至 ACL，而不會影響 ACL 中列出的其他安全性主體。 若要取代 ACL 而不是更新，請參閱這篇文章的設定 ACL 一節。
若要更新 ACL，請使用您想要更新的 ACL 項目來建立新的 ACL 物件，然後在更新 ACL 作業中使用該物件。 請勿取得現有的 ACL，只需提供要更新的 ACL 項目。
本節說明如何：
- 更新 ACL
- 以遞迴方式更新 ACL
更新 ACL
使用 az storage fs access update-recursive 命令更新檔案的 ACL。
此範例會使用寫入權限更新 ACL 項目。
az storage fs access update-recursive --acl "user:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx:rwx" -p my-parent-directory/myfile.txt -f my-container --account-name mystorageaccount --auth-mode login
若要更新特定群組或使用者的 ACL，請使用其各自的物件識別碼。 例如，group:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx 或 user:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx。
注意
Azure CLI 不支援僅更新單一目錄的 ACL 而不更新子項目的 ACL。 若要支援目錄的 ACL 而不修改所有子項目的 ACL，請使用其他支援的任意工具或 SDK。 請參閱如何設定 ACL。
以遞迴方式更新 ACL
使用 az storage fs access update-recursive 命令以遞迴方式更新 ACL。
此範例會使用寫入權限更新 ACL 項目。
az storage fs access update-recursive --acl "user:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx:rwx" -p my-parent-directory/ -f my-container --account-name mystorageaccount --auth-mode login
注意
如果您想要更新預設 ACL 項目，請將前置詞 default: 新增至每個項目。 例如： default:user:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx:r-x 。
以遞迴方式移除 ACL 項目
您能以遞迴方式移除一或多個 ACL 項目。 若要移除 ACL 項目，請為要移除的 ACL 項目建立新 ACL 物件，然後在移除 ACL 作業中使用該物件。 請勿取得現有的 ACL，只需提供要移除的 ACL 項目。
使用 az storage fs access remove-recursive 命令移除 ACL 項目。
此範例會從容器的根目錄移除 ACL 項目。
az storage fs access remove-recursive --acl "user:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -p my-parent-directory/ -f my-container --account-name mystorageaccount --auth-mode login
注意
如果您想要移除預設 ACL 項目，請將前置詞 default: 新增至每個項目。 例如： default:user:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx 。
從失敗中復原
以遞迴方式修改 ACL 時，您可能會遇到執行階段或權限錯誤。 如果是執行階段錯誤，請從頭開始重新啟動程序。 如果安全性主體沒有足夠的權限可修改要修改的目錄階層中目錄或檔案的 ACL，則可能會發生權限錯誤。 解決權限問題，然後選擇使用接續權杖從失敗點繼續處理程序，或從頭開始重新啟動程序。 如果您想要從頭開始重新啟動，就不需要使用接續權杖。 您可以重新套用 ACL 項目，而不會產生負面影響。
發生失敗時，您可以藉由將 --continue-on-failure 參數設定為 false 來傳回接續 Token。 解決錯誤之後，為了從失敗點繼續該程序，您可再次執行命令，並將 --continuation 參數設定為接續 Token。
az storage fs access set-recursive --acl "user::rw-,group::r-x,other::---" --continue-on-failure false --continuation xxxxxxx -p my-parent-directory/ -f my-container --account-name mystorageaccount --auth-mode login
如果您想要讓程序完成而不受權限錯誤干擾，您可以指定。
若要確保該程序不中斷地完成，請將 --continue-on-failure 參數設定為 true。
az storage fs access set-recursive --acl "user::rw-,group::r-x,other::---" --continue-on-failure true --continuation xxxxxxx -p my-parent-directory/ -f my-container --account-name mystorageaccount --auth-mode login
最佳作法
本節提供您以遞迴方式設定 ACL 的一些最佳做法指導方針。
處理執行階段錯誤
有許多原因可能會發生執行階段錯誤 (例如：中斷或用戶端連線問題)。 如果您遇到執行階段錯誤，請重新啟動遞迴 ACL 程序。 ACL 可以重新套用至項目，而不會造成負面影響。
處理權限錯誤 (403)
如果您在執行遞迴 ACL 程序時遇到存取控制例外狀況，則您的 AD 安全性主體可能沒有足夠權限可將 ACL 套用至目錄階層中的一或多個子項目。 發生權限錯誤時，程序會停止，並提供接續權杖。 修正權限問題，然後使用接續權杖來處理剩餘的資料集。 已成功處理的目錄和檔案不需要重新處理。 您也可以選擇重新啟動遞迴 ACL 程序。 ACL 可以重新套用至項目，而不會造成負面影響。
認證
建議您在目標儲存體帳戶或容器的範圍中，佈建已獲指派儲存體 Blob 資料擁有者角色的 Microsoft Entra 安全性主體。
效能
若要減少延遲，建議您在位於與儲存體帳戶相同區域中的 Azure 虛擬機器 (VM) 中執行遞迴 ACL 程序。
ACL 限制
您可以套用至目錄或檔案的 ACL 數目上限是 32 個存取 ACL 和 32 個預設 ACL。 如需詳細資訊，請參閱 Azure Data Lake Storage Gen2 中的存取控制。