Använda .NET för att hantera kataloger och filer i Azure Data Lake Storage Gen2

  • Artikel

Den här artikeln visar hur du använder .NET för att skapa och hantera kataloger och filer i lagringskonton som har ett hierarkiskt namnområde.

Mer information om hur du hämtar, anger och uppdaterar åtkomstkontrollistor (ACL) med kataloger och filer finns i Använda .NET för att hantera ACL:er i Azure Data Lake Storage Gen2.

Paket (NuGet)Exempel-API-referens | | | Gen1 till Gen2-mappning | Ge feedback

Förutsättningar

Konfigurera projektet

Kom igång genom att installera NuGet-paketet Azure.Storage.Files.DataLake .

Mer information om hur du installerar NuGet-paket finns i Installera och hantera paket i Visual Studio med Hjälp av NuGet Package Manager.

Lägg sedan till dessa med hjälp av -instruktioner överst i kodfilen.

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

Kommentar

Med åtkomst med flera protokoll i Data Lake Storage kan program använda både Blob-API:er och Data Lake Storage Gen2-API:er för att arbeta med data i lagringskonton med hierarkisk namnrymd (HNS) aktiverad. När du arbetar med funktioner som är unika för Data Lake Storage Gen2, till exempel katalogåtgärder och ACL:er, använder du API:erna för Data Lake Storage Gen2, som du ser i den här artikeln.

När du väljer vilka API:er som ska användas i ett visst scenario bör du överväga arbetsbelastningen och programmets behov, tillsammans med de kända problemen och effekten av HNS på arbetsbelastningar och program.

Auktorisera åtkomst och ansluta till dataresurser

Om du vill arbeta med kodexemplen i den här artikeln måste du skapa en auktoriserad DataLakeServiceClient-instans som representerar lagringskontot. Du kan auktorisera ett DataLakeServiceClient objekt med hjälp av Microsoft Entra-ID, en kontoåtkomstnyckel eller en signatur för delad åtkomst (SAS).

Du kan använda Azure Identity-klientbiblioteket för .NET för att autentisera ditt program med Microsoft Entra-ID.

Skapa en DataLakeServiceClient-instans och skicka in en ny instans av klassen DefaultAzureCredential .

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;
}

Mer information om hur du använder DefaultAzureCredential för att auktorisera åtkomst till data finns i Autentisera .NET-program med Azure-tjänster.

Skapa en container

En container fungerar som ett filsystem för dina filer. Du kan skapa en container med hjälp av följande metod:

I följande kodexempel skapas en container och ett DataLakeFileSystemClient-objekt returneras för senare användning:

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

Skapa en katalog

Du kan skapa en katalogreferens i containern med hjälp av följande metod:

Följande kodexempel lägger till en katalog i en container, lägger sedan till en underkatalog och returnerar ett DataLakeDirectoryClient-objekt för senare användning:

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

    return await directoryClient.CreateSubDirectoryAsync(subdirectoryName);
}

Byta namn på eller flytta en katalog

Du kan byta namn på eller flytta en katalog med hjälp av följande metod:

Skicka sökvägen till den önskade katalogen som en parameter. I följande kodexempel visas hur du byter namn på en underkatalog:

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));
}

I följande kodexempel visas hur du flyttar en underkatalog från en katalog till en annan katalog:

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));
}

Ladda upp en fil till en katalog

Du kan ladda upp innehåll till en ny eller befintlig fil med hjälp av följande metod:

Följande kodexempel visar hur du laddar upp en lokal fil till en katalog med hjälp av UploadAsync metoden:

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);
}

Du kan använda den här metoden för att skapa och ladda upp innehåll till en ny fil, eller så kan du ange parametern overwrite till true för att skriva över en befintlig fil.

Lägga till data i en fil

Du kan ladda upp data som ska läggas till i en fil med hjälp av följande metod:

Följande kodexempel visar hur du lägger till data i slutet av en fil med hjälp av följande steg:

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);
}

Ladda ned från en katalog

Följande kodexempel visar hur du laddar ned en fil från en katalog till en lokal fil med hjälp av följande steg:

I det här exemplet används en BinaryReader och en FileStream för att spara byte i en fil.

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();
}

Lista kataloginnehåll

Du kan visa kataloginnehåll med hjälp av följande metod och räkna upp resultatet:

Om du räknar upp sökvägarna i resultatet kan du göra flera begäranden till tjänsten när du hämtar värdena.

I följande kodexempel skrivs namnen på varje fil som finns i en katalog ut:

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;
    }

}

Ta bort en katalog

Du kan ta bort en katalog med hjälp av följande metod:

Följande kodexempel visar hur du tar bort en katalog:

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

    await directoryClient.DeleteAsync();
}

Återställa en mjukt borttagen katalog

Du kan använda Azure Storage-klientbiblioteken för att återställa en katalog med mjuk borttagning. Använd följande metod för att lista borttagna sökvägar för en DataLakeFileSystemClient-instans :

Använd följande metod för att återställa en mjukt borttagen katalog:

I följande kodexempel visas hur du listar borttagna sökvägar och återställer en katalog med mjuk borttagning:

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);
}

Om du byter namn på katalogen som innehåller de mjukt borttagna objekten kopplas dessa objekt från från katalogen. Om du vill återställa dessa objekt måste du återställa namnet på katalogen till dess ursprungliga namn eller skapa en separat katalog som använder det ursprungliga katalognamnet. Annars får du ett felmeddelande när du försöker återställa de mjukt borttagna objekten.

Skapa en SAS för användardelegering för en katalog

Om du vill arbeta med kodexemplen i det här avsnittet lägger du till följande using direktiv:

using Azure.Storage.Sas;

I följande kodexempel visas hur du genererar en SAS för användardelegering för en katalog när ett hierarkiskt namnområde är aktiverat för lagringskontot:

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;
    }
}

I följande exempel testas sas för användardelegering som skapades i föregående exempel från ett simulerat klientprogram. Om SAS är giltigt kan klientprogrammet lista filsökvägar för den här katalogen. Om SAS är ogiltigt (till exempel sas har upphört att gälla) returnerar Lagringstjänsten felkoden 403 (förbjuden).

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;
        }
    }
}

Mer information om hur du skapar en SAS för användardelegering finns i Skapa en SAS för användardelegering med .NET.

Skapa en tjänst-SAS för en katalog

I ett lagringskonto med ett hierarkiskt namnområde aktiverat kan du skapa en tjänst-SAS för en katalog. Om du vill skapa tjänstens SAS kontrollerar du att du har installerat version 12.5.0 eller senare av paketet Azure.Storage.Files.DataLake .

I följande exempel visas hur du skapar en tjänst-SAS för en katalog:

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;
    }
}

Mer information om hur du skapar en tjänst-SAS finns i Skapa en tjänst-SAS med .NET.

Se även