Použití .NET ke správě adresářů a souborů v Azure Data Lake Storage Gen2

V tomto článku se dozvíte, jak pomocí .NET vytvářet a spravovat adresáře a soubory v účtech úložiště, které mají hierarchický obor názvů.

Informace o tom, jak získat, nastavit a aktualizovat seznamy řízení přístupu (ACL) adresářů a souborů, najdete v tématu Použití .NET ke správě seznamů ACL v Azure Data Lake Storage Gen2.

Referenční informace k rozhraní API pro balíčky (NuGet) | s referenčními informacemi | | k mapování | Gen1 na Gen2

Požadavky

• Předplatné Azure. Viz Získání bezplatné zkušební verze Azure.

• Účet úložiště s povoleným hierarchickým oborem názvů. Postupujte podle těchto pokynů a vytvořte ho.

Nastavení projektu

Začněte instalací balíčku NuGet Azure.Storage.Files.DataLake .

Další informace o instalaci balíčků NuGet naleznete v tématu Instalace a správa balíčků v sadě Visual Studio pomocí Správce balíčků NuGet.

Pak tyto příkazy using přidejte na začátek souboru kódu.

using Azure;
using Azure.Storage.Files.DataLake;
using Azure.Storage.Files.DataLake.Models;
using Azure.Storage;
using System.IO;

Autorizace přístupu a připojení k datovým prostředkům

Pokud chcete pracovat s příklady kódu v tomto článku, musíte vytvořit autorizovanou instanci DataLakeServiceClient , která představuje účet úložiště. Objekt můžete autorizovat DataLakeServiceClient pomocí MICROSOFT Entra ID, přístupového klíče účtu nebo sdíleného přístupového podpisu (SAS).

public static DataLakeServiceClient GetDataLakeServiceClient(string accountName)
{
    string dfsUri = $"https://{accountName}.dfs.core.windows.net";

    DataLakeServiceClient dataLakeServiceClient = new DataLakeServiceClient(
        new Uri(dfsUri),
        new DefaultAzureCredential());

    return dataLakeServiceClient;
}

public static DataLakeServiceClient GetDataLakeServiceClientSAS(string accountName, string sasToken)
{
    string dfsUri = $"https://{accountName}.dfs.core.windows.net";

    DataLakeServiceClient dataLakeServiceClient = new DataLakeServiceClient(
        new Uri(dfsUri),
        new AzureSasCredential(sasToken));

    return dataLakeServiceClient;
}

public static DataLakeServiceClient GetDataLakeServiceClient(string accountName, string accountKey)
{
    StorageSharedKeyCredential sharedKeyCredential =
        new StorageSharedKeyCredential(accountName, accountKey);

    string dfsUri = $"https://{accountName}.dfs.core.windows.net";

    DataLakeServiceClient dataLakeServiceClient = new DataLakeServiceClient(
        new Uri(dfsUri),
        sharedKeyCredential);

    return dataLakeServiceClient;
}

Vytvoření kontejneru

Kontejner funguje jako systém souborů. Kontejner můžete vytvořit pomocí následující metody:

• DataLakeServiceClient.CreateFileSystem

Následující příklad kódu vytvoří kontejner a vrátí objekt DataLakeFileSystemClient pro pozdější použití:

public async Task<DataLakeFileSystemClient> CreateFileSystem(
    DataLakeServiceClient serviceClient,
    string fileSystemName)
{
    return await serviceClient.CreateFileSystemAsync(fileSystemName);
}

Vytvoření adresáře

Odkaz na adresář v kontejneru můžete vytvořit pomocí následující metody:

• DataLakeFileSystemClient.CreateDirectoryAsync

Následující příklad kódu přidá adresář do kontejneru a pak přidá podadresář a vrátí objekt DataLakeDirectoryClient pro pozdější použití:

public async Task<DataLakeDirectoryClient> CreateDirectory(
    DataLakeFileSystemClient fileSystemClient,
    string directoryName,
    string subdirectoryName)
{
    DataLakeDirectoryClient directoryClient =
        await fileSystemClient.CreateDirectoryAsync(directoryName);

    return await directoryClient.CreateSubDirectoryAsync(subdirectoryName);
}

Přejmenování nebo přesunutí adresáře

Adresář můžete přejmenovat nebo přesunout pomocí následující metody:

• DataLakeDirectoryClient.RenameAsync

Jako parametr předejte cestu požadovaného adresáře. Následující příklad kódu ukazuje, jak přejmenovat podadresář:

public async Task<DataLakeDirectoryClient> RenameDirectory(
    DataLakeFileSystemClient fileSystemClient,
    string directoryPath,
    string subdirectoryName,
    string subdirectoryNameNew)
{
    DataLakeDirectoryClient directoryClient =
        fileSystemClient.GetDirectoryClient(string.Join('/', directoryPath, subdirectoryName));

    return await directoryClient.RenameAsync(string.Join('/', directoryPath, subdirectoryNameNew));
}

Následující příklad kódu ukazuje, jak přesunout podadresář z jednoho adresáře do jiného adresáře:

public async Task<DataLakeDirectoryClient> MoveDirectory(
    DataLakeFileSystemClient fileSystemClient,
    string directoryPathFrom,
    string directoryPathTo,
    string subdirectoryName)
{
    DataLakeDirectoryClient directoryClient =
         fileSystemClient.GetDirectoryClient(string.Join('/', directoryPathFrom, subdirectoryName));

    return await directoryClient.RenameAsync(string.Join('/', directoryPathTo, subdirectoryName));
}

Nahrání souboru do adresáře

Obsah můžete nahrát do nového nebo existujícího souboru pomocí následující metody:

• DataLakeFileClient.UploadAsync

Následující příklad kódu ukazuje, jak pomocí metody nahrát místní soubor do adresáře UploadAsync :

public async Task UploadFile(
    DataLakeDirectoryClient directoryClient,
    string fileName,
    string localPath)
{
    DataLakeFileClient fileClient = 
        directoryClient.GetFileClient(fileName);

    FileStream fileStream = File.OpenRead(localPath);

    await fileClient.UploadAsync(content: fileStream, overwrite: true);
}

Tuto metodu můžete použít k vytvoření a nahrání obsahu do nového souboru nebo můžete parametr nastavit overwrite tak, aby true přepsal existující soubor.

Připojení dat k souboru

Data, která se mají připojit k souboru, můžete nahrát pomocí následující metody:

• DataLakeFileClient.AppendAsync

Následující příklad kódu ukazuje, jak připojit data na konec souboru pomocí následujícího postupu:

• Vytvořte objekt DataLakeFileClient , který představuje prostředek souboru, se kterým pracujete.
• Nahrajte data do souboru pomocí metody DataLakeFileClient.AppendAsync .
• Dokončete nahrávání voláním metody DataLakeFileClient.FlushAsync pro zápis dříve nahraných dat do souboru.

public async Task AppendDataToFile(
    DataLakeDirectoryClient directoryClient,
    string fileName,
    Stream stream)
{
    DataLakeFileClient fileClient = 
        directoryClient.GetFileClient(fileName);

    long fileSize = fileClient.GetProperties().Value.ContentLength;

    await fileClient.AppendAsync(stream, offset: fileSize);

    await fileClient.FlushAsync(position: fileSize + stream.Length);
}

Stažení z adresáře

Následující příklad kódu ukazuje, jak pomocí následujícího postupu stáhnout soubor z adresáře do místního souboru:

• Vytvořte instanci DataLakeFileClient, která představuje soubor, který chcete stáhnout.
• Použijte metodu DataLakeFileClient.ReadAsync a pak parsujte návratovou hodnotu pro získání objektu Stream . K uložení bajtů ze streamu do souboru použijte libovolné rozhraní API pro zpracování souborů .NET.

Tento příklad používá BinaryReader a FileStream k uložení bajtů do souboru.

public async Task DownloadFile(
    DataLakeDirectoryClient directoryClient,
    string fileName,
    string localPath)
{
    DataLakeFileClient fileClient =
        directoryClient.GetFileClient(fileName);

    Response<FileDownloadInfo> downloadResponse = await fileClient.ReadAsync();

    BinaryReader reader = new BinaryReader(downloadResponse.Value.Content);

    FileStream fileStream = File.OpenWrite(localPath);

    int bufferSize = 4096;

    byte[] buffer = new byte[bufferSize];

    int count;

    while ((count = reader.Read(buffer, 0, buffer.Length)) != 0)
    {
        fileStream.Write(buffer, 0, count);
    }

    await fileStream.FlushAsync();

    fileStream.Close();
}

Výpis obsahu adresáře

Obsah adresáře můžete zobrazit pomocí následující metody a vytvořit výčet výsledku:

• FileSystemClient.GetPathsAsync

Vytvoření výčtu cest ve výsledku může službě při načítání hodnot vyhovět více požadavků.

Následující příklad kódu vytiskne názvy každého souboru, který se nachází v adresáři:

public async Task ListFilesInDirectory(
    DataLakeFileSystemClient fileSystemClient,
    string directoryName)
{
    IAsyncEnumerator<PathItem> enumerator =
        fileSystemClient.GetPathsAsync(directoryName).GetAsyncEnumerator();

    await enumerator.MoveNextAsync();

    PathItem item = enumerator.Current;

    while (item != null)
    {
        Console.WriteLine(item.Name);

        if (!await enumerator.MoveNextAsync())
        {
            break;
        }

        item = enumerator.Current;
    }

}

Odstranění adresáře

Adresář můžete odstranit pomocí následující metody:

• DataLakeDirectoryClient.Delete

Následující příklad kódu ukazuje, jak odstranit adresář:

public async Task DeleteDirectory(
    DataLakeFileSystemClient fileSystemClient,
    string directoryName)
{
    DataLakeDirectoryClient directoryClient =
        fileSystemClient.GetDirectoryClient(directoryName);

    await directoryClient.DeleteAsync();
}

Obnovení obnovitelného odstraněného adresáře

Klientské knihovny Azure Storage můžete použít k obnovení obnovitelného odstraněného adresáře. K výpisu odstraněných cest pro instanci DataLakeFileSystemClient použijte následující metodu:

• GetDeletedPathsAsync

K obnovení obnovitelného odstraněného adresáře použijte následující metodu:

• UndeletePathAsync

Následující příklad kódu ukazuje, jak vypsat odstraněné cesty a obnovit obnovit obnovitelně odstraněný adresář:

public async Task RestoreDirectory(
    DataLakeFileSystemClient fileSystemClient,
    string directoryName)
{
    DataLakeDirectoryClient directoryClient =
        fileSystemClient.GetDirectoryClient(directoryName);

    // List deleted paths
    List<PathDeletedItem> deletedItems = new List<PathDeletedItem>();
    await foreach (PathDeletedItem deletedItem in fileSystemClient.GetDeletedPathsAsync(directoryName))
    {
        deletedItems.Add(deletedItem);
    }

    // Restore deleted directory
    Response<DataLakePathClient> restoreResponse = await fileSystemClient.UndeletePathAsync(
        deletedItems[0].Path,
        deletedItems[0].DeletionId);
}

Pokud přejmenujete adresář obsahující obnovitelné odstraněné položky, tyto položky se od adresáře odpojí. Pokud chcete tyto položky obnovit, musíte vrátit název adresáře zpět k původnímu názvu nebo vytvořit samostatný adresář, který používá původní název adresáře. V opačném případě se při pokusu o obnovení těchto obnovitelně odstraněných položek zobrazí chyba.

Vytvoření SAS delegování uživatele pro adresář

Pokud chcete pracovat s příklady kódu v této části, přidejte následující using direktivu:

using Azure.Storage.Sas;

Následující příklad kódu ukazuje, jak vygenerovat SAS delegování uživatele pro adresář, když je pro účet úložiště povolený hierarchický obor názvů:

async static Task<Uri> GetUserDelegationSasDirectory(DataLakeDirectoryClient directoryClient)
{
    try
    {
        // Get service endpoint from the directory URI.
        DataLakeUriBuilder dataLakeServiceUri = new DataLakeUriBuilder(directoryClient.Uri)
        {
            FileSystemName = null,
            DirectoryOrFilePath = null
        };

        // Get service client.
        DataLakeServiceClient dataLakeServiceClient =
            new DataLakeServiceClient(dataLakeServiceUri.ToUri(),
                                      new DefaultAzureCredential());

        // Get a user delegation key that's valid for seven days.
        // You can use the key to generate any number of shared access signatures 
        // over the lifetime of the key.
        Azure.Storage.Files.DataLake.Models.UserDelegationKey userDelegationKey =
            await dataLakeServiceClient.GetUserDelegationKeyAsync(DateTimeOffset.UtcNow,
                                                                  DateTimeOffset.UtcNow.AddDays(7));

        // Create a SAS token that's valid for seven days.
        DataLakeSasBuilder sasBuilder = new DataLakeSasBuilder()
        {
            // Specify the file system name and path, and indicate that
            // the client object points to a directory.
            FileSystemName = directoryClient.FileSystemName,
            Resource = "d",
            IsDirectory = true,
            Path = directoryClient.Path,
            ExpiresOn = DateTimeOffset.UtcNow.AddDays(7)
        };

        // Specify racwl permissions for the SAS.
        sasBuilder.SetPermissions(
            DataLakeSasPermissions.Read |
            DataLakeSasPermissions.Add |
            DataLakeSasPermissions.Create |
            DataLakeSasPermissions.Write |
            DataLakeSasPermissions.List
            );

        // Construct the full URI, including the SAS token.
        DataLakeUriBuilder fullUri = new DataLakeUriBuilder(directoryClient.Uri)
        {
            Sas = sasBuilder.ToSasQueryParameters(userDelegationKey,
                                                  dataLakeServiceClient.AccountName)
        };

        Console.WriteLine("Directory user delegation SAS URI: {0}", fullUri);
        Console.WriteLine();
        return fullUri.ToUri();
    }
    catch (Exception e)
    {
        Console.WriteLine(e.Message);
        throw;
    }
}

Následující příklad testuje SAS delegování uživatele vytvořeného v předchozím příkladu ze simulované klientské aplikace. Pokud je SAS platný, klientská aplikace může vypsat cesty k souborům pro tento adresář. Pokud je SAS neplatný (například platnost sdíleného přístupového podpisu vypršela), služba Storage vrátí kód chyby 403 (Zakázáno).

private static async Task ListFilesPathsWithDirectorySasAsync(Uri sasUri)
{
    // Try performing an operation using the directory SAS provided.

    // Create a directory client object for listing operations.
    DataLakeDirectoryClient dataLakeDirectoryClient = new DataLakeDirectoryClient(sasUri);

    // List file paths in the directory.
    try
    {
        // Call the listing operation and return pages of the specified size.
        var resultSegment = dataLakeDirectoryClient.GetPathsAsync(false, false).AsPages();

        // Enumerate the file paths returned with each page.
        await foreach (Page<PathItem> pathPage in resultSegment)
        {
            foreach (PathItem pathItem in pathPage.Values)
            {
                Console.WriteLine("File name: {0}", pathItem.Name);
            }
            Console.WriteLine();
        }

        Console.WriteLine();
        Console.WriteLine("Directory listing operation succeeded for SAS {0}", sasUri);
    }
    catch (RequestFailedException e)
    {
        // Check for a 403 (Forbidden) error. If the SAS is invalid, 
        // Azure Storage returns this error.
        if (e.Status == 403)
        {
            Console.WriteLine("Directory listing operation failed for SAS {0}", sasUri);
            Console.WriteLine("Additional error information: " + e.Message);
            Console.WriteLine();
        }
        else
        {
            Console.WriteLine(e.Message);
            Console.ReadLine();
            throw;
        }
    }
}

Další informace o vytváření SAS delegování uživatele najdete v tématu Vytvoření SAS delegování uživatele pomocí .NET.

Vytvoření sdíleného přístupového podpisu služby pro adresář

V účtu úložiště s povoleným hierarchickým oborem názvů můžete vytvořit SAS služby pro adresář. Pokud chcete vytvořit SAS služby, ujistěte se, že máte nainstalovanou verzi 12.5.0 nebo novější balíčku Azure.Storage.Files.DataLake .

Následující příklad ukazuje, jak vytvořit SAS služby pro adresář:

private static Uri GetServiceSasUriForDirectory(DataLakeDirectoryClient directoryClient,
                                          string storedPolicyName = null)
{
    if (directoryClient.CanGenerateSasUri)
    {
        // Create a SAS token that's valid for one hour.
        DataLakeSasBuilder sasBuilder = new DataLakeSasBuilder()
        {
            // Specify the file system name, the path, and indicate that
            // the client object points to a directory.
            FileSystemName = directoryClient.FileSystemName,
            Resource = "d",
            IsDirectory = true,
            Path = directoryClient.Path,
        };

        // If no stored access policy is specified, create the policy
        // by specifying expiry and permissions.
        if (storedPolicyName == null)
        {
            sasBuilder.ExpiresOn = DateTimeOffset.UtcNow.AddHours(1);
            sasBuilder.SetPermissions(DataLakeSasPermissions.Read |
                DataLakeSasPermissions.Write |
                DataLakeSasPermissions.List);
        }
        else
        {
            sasBuilder.Identifier = storedPolicyName;
        }

        // Get the SAS URI for the specified directory.
        Uri sasUri = directoryClient.GenerateSasUri(sasBuilder);
        Console.WriteLine("SAS URI for ADLS directory is: {0}", sasUri);
        Console.WriteLine();

        return sasUri;
    }
    else
    {
        Console.WriteLine(@"DataLakeDirectoryClient must be authorized with Shared Key 
                          credentials to create a service SAS.");
        return null;
    }
}

Další informace o vytváření SAS služby najdete v tématu Vytvoření SAS služby pomocí .NET.

Viz také

• Referenční dokumentace k rozhraní API
• Balíček (NuGet)
• Ukázky
• Mapování Gen1 na Gen2
• Známé problémy
• Váš názor