Delen via

.NET gebruiken om mappen en bestanden te beheren in Azure Data Lake Storage Gen2

  • Artikel

In dit artikel leest u hoe u .NET gebruikt om mappen en bestanden te maken en beheren in opslagaccounts met een hiërarchische naamruimte.

Zie .NET gebruiken voor het beheren van ACL's in Azure Data Lake Storage Gen2 voor meer informatie over het ophalen, instellen en bijwerken van de toegangsbeheerlijsten (ACL's).

Package (NuGet) | Samples | API reference | Gen1 to Gen2 mapping | Give Feedback

Vereisten

Uw project instellen

Installeer het NuGet-pakket Azure.Storage.Files.DataLake om aan de slag te gaan.

Zie Pakketten installeren en beheren in Visual Studio met behulp van de NuGet-Pakketbeheer voor meer informatie over het installeren van NuGet-pakketten.

Voeg deze vervolgens toe met behulp van instructies boven aan het codebestand.

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

Notitie

Met toegang tot meerdere protocollen in Data Lake Storage kunnen toepassingen zowel Blob-API's als Data Lake Storage Gen2-API's gebruiken om te werken met gegevens in opslagaccounts waarvoor HNS (hiërarchische naamruimte) is ingeschakeld. Wanneer u werkt met mogelijkheden die uniek zijn voor Data Lake Storage Gen2, zoals adreslijstbewerkingen en ACL's, gebruikt u de Data Lake Storage Gen2-API's, zoals wordt weergegeven in dit artikel.

Wanneer u kiest welke API's in een bepaald scenario moeten worden gebruikt, moet u rekening houden met de workload en de behoeften van uw toepassing, samen met de bekende problemen en impact van HNS op workloads en toepassingen.

Toegang autoriseren en verbinding maken met gegevensbronnen

Als u wilt werken met de codevoorbeelden in dit artikel, moet u een geautoriseerd DataLakeServiceClient-exemplaar maken dat het opslagaccount vertegenwoordigt. U kunt een DataLakeServiceClient object autoriseren met behulp van Microsoft Entra ID, een toegangssleutel voor een account of een Shared Access Signature (SAS).

U kunt de Azure Identity-clientbibliotheek voor .NET gebruiken om uw toepassing te verifiëren met Microsoft Entra-id.

Maak een DataLakeServiceClient-exemplaar en geef een nieuw exemplaar van de klasse DefaultAzureCredential door .

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

Zie .NET-toepassingen verifiëren met Azure-services voor meer informatie over het DefaultAzureCredential autoriseren van toegang tot gegevens.

Een container maken

Een container fungeert als een bestandssysteem voor uw bestanden. U kunt een container maken met behulp van de volgende methode:

In het volgende codevoorbeeld wordt een container gemaakt en wordt een DataLakeFileSystemClient-object geretourneerd voor later gebruik:

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

Een map maken

U kunt een mapreferentie in de container maken met behulp van de volgende methode:

In het volgende codevoorbeeld wordt een map aan een container toegevoegd en vervolgens een submap toegevoegd en wordt een DataLakeDirectoryClient-object geretourneerd voor later gebruik:

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

    return await directoryClient.CreateSubDirectoryAsync(subdirectoryName);
}

De naam van een map wijzigen of verplaatsen

U kunt de naam van een map wijzigen of verplaatsen met behulp van de volgende methode:

Geef het pad van de gewenste map door als een parameter. In het volgende codevoorbeeld ziet u hoe u de naam van een submap wijzigt:

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

In het volgende codevoorbeeld ziet u hoe u een submap van de ene map naar een andere map verplaatst:

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

Een bestand uploaden naar een map

U kunt inhoud uploaden naar een nieuw of bestaand bestand met behulp van de volgende methode:

In het volgende codevoorbeeld ziet u hoe u een lokaal bestand uploadt naar een map met behulp van de UploadAsync methode:

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

U kunt deze methode gebruiken om inhoud te maken en te uploaden naar een nieuw bestand, of u kunt de overwrite parameter instellen om true een bestaand bestand te overschrijven.

Gegevens toevoegen aan een bestand

U kunt gegevens uploaden die aan een bestand moeten worden toegevoegd met behulp van de volgende methode:

In het volgende codevoorbeeld ziet u hoe u gegevens toevoegt aan het einde van een bestand met behulp van deze stappen:

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

Downloaden uit een map

In het volgende codevoorbeeld ziet u hoe u een bestand downloadt van een map naar een lokaal bestand met behulp van deze stappen:

In dit voorbeeld wordt een BinaryReader en een FileStream gebruikt om bytes op te slaan in een bestand.

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

Mapinhoud weergeven

U kunt de inhoud van de map weergeven met behulp van de volgende methode en het resultaat opsommen:

Als u de paden in het resultaat opsommen, kunnen er meerdere aanvragen naar de service worden verzonden tijdens het ophalen van de waarden.

In het volgende codevoorbeeld worden de namen afgedrukt van elk bestand dat zich in een map bevindt:

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

}

Een directory verwijderen

U kunt een map verwijderen met behulp van de volgende methode:

In het volgende codevoorbeeld ziet u hoe u een map verwijdert:

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

    await directoryClient.DeleteAsync();
}

Een voorlopig verwijderde map herstellen

U kunt de Azure Storage-clientbibliotheken gebruiken om een voorlopig verwijderde map te herstellen. Gebruik de volgende methode om verwijderde paden voor een DataLakeFileSystemClient-exemplaar weer te geven:

Gebruik de volgende methode om een voorlopig verwijderde map te herstellen:

In het volgende codevoorbeeld ziet u hoe u verwijderde paden weergeeft en een voorlopig verwijderde map herstelt:

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

Als u de naam van de map met de voorlopig verwijderde items wijzigt, worden deze items losgekoppeld van de map. Als u deze items wilt herstellen, moet u de naam van de map terugzetten naar de oorspronkelijke naam of een afzonderlijke map maken die gebruikmaakt van de oorspronkelijke mapnaam. Anders krijgt u een foutmelding wanneer u probeert deze voorlopig verwijderde items te herstellen.

Een SAS voor gebruikersdelegering maken voor een directory

Als u wilt werken met de codevoorbeelden in deze sectie, voegt u de volgende using instructie toe:

using Azure.Storage.Sas;

In het volgende codevoorbeeld ziet u hoe u een SAS voor gebruikersdelegatie genereert voor een map wanneer een hiërarchische naamruimte is ingeschakeld voor het opslagaccount:

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

In het volgende voorbeeld wordt de SAS voor gebruikersdelegatie getest die in het vorige voorbeeld is gemaakt vanuit een gesimuleerde clienttoepassing. Als de SAS geldig is, kan de clienttoepassing bestandspaden voor deze map vermelden. Als de SAS ongeldig is (bijvoorbeeld de SAS is verlopen), retourneert de Storage-service foutcode 403 (Verboden).

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

Zie Een SAS voor gebruikersdelegatie maken met .NET voor meer informatie over het maken van een SAS voor gebruikersdelegatie.

Een service-SAS voor een directory maken

In een opslagaccount waarvoor een hiërarchische naamruimte is ingeschakeld, kunt u een service-SAS voor een map maken. Als u de service-SAS wilt maken, moet u versie 12.5.0 of hoger van het Pakket Azure.Storage.Files.DataLake hebben geïnstalleerd.

In het volgende voorbeeld ziet u hoe u een service-SAS voor een directory maakt:

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

Zie Een service-SAS maken met .NET voor meer informatie over het maken van een service-SAS.

Zie ook