Megosztás a következőn keresztül:

A .NET használata könyvtárak és fájlok kezeléséhez az Azure Data Lake Storage Gen2-ben

  • Cikk

Ez a cikk bemutatja, hogyan hozhat létre és kezelhet címtárakat és fájlokat a .NET használatával hierarchikus névtérrel rendelkező tárfiókokban.

A könyvtárak és fájlok hozzáférés-vezérlési listáinak (ACL) beszerzéséről, beállításáról és frissítéséről a .NET használata az Azure Data Lake Storage Gen2 ACL-einek kezeléséhez című témakörben olvashat.

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

Előfeltételek

A projekt beállítása

Első lépésként telepítse az Azure.Storage.Files.DataLake NuGet csomagot.

További információ a NuGet-csomagok telepítéséről: Csomagok telepítése és kezelése a Visual Studióban a NuGet-Csomagkezelő használatával.

Ezután adja hozzá ezeket az utasításokat a kódfájl tetejére.

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

Feljegyzés

A Data Lake Storage többprotokollos hozzáférése lehetővé teszi az alkalmazások számára, hogy a Blob API-kat és a Data Lake Storage Gen2 API-kat is használják a hierarchikus névtérrel (HNS) rendelkező tárfiókokban lévő adatok kezeléséhez. A Data Lake Storage Gen2-ben egyedülálló képességek, például a címtárműveletek és az ACL-ek használatakor használja a Data Lake Storage Gen2 API-kat, ahogyan az ebben a cikkben látható.

Az adott forgatókönyvben használni kívánt API-k kiválasztásakor vegye figyelembe az alkalmazás számítási feladatait és igényeit, valamint a HNS ismert problémáit és a számítási feladatokra és alkalmazásokra gyakorolt hatását.

Hozzáférés engedélyezése és csatlakozás az adaterőforrásokhoz

A cikkben szereplő példakódok használatához létre kell hoznia egy hitelesített DataLakeServiceClient-példányt , amely a tárfiókot jelöli. Az objektumokat DataLakeServiceClient a Microsoft Entra-azonosító, a fiókhozzáférés kulcsa vagy a közös hozzáférésű jogosultságkód (SAS) használatával engedélyezheti.

A .NET-hez készült Azure Identity-ügyfélkódtár használatával hitelesítheti az alkalmazást a Microsoft Entra-azonosítóval.

Hozzon létre egy DataLakeServiceClient-példányt , és adja át a DefaultAzureCredential osztály új példányát.

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

Ha többet szeretne tudni az adatokhoz való hozzáférés engedélyezésérőlDefaultAzureCredential, olvassa el a .NET-alkalmazások Azure-szolgáltatásokkal való hitelesítését ismertető témakört.

Tároló létrehozása

A tároló fájlrendszerként működik a fájlokhoz. Tárolót a következő módszerrel hozhat létre:

Az alábbi példakód létrehoz egy tárolót, és egy DataLakeFileSystemClient objektumot ad vissza későbbi használatra:

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

Címtár létrehozása

A tárolóban a következő módszerrel hozhat létre címtárhivatkozást:

Az alábbi példakód egy könyvtárat ad hozzá egy tárolóhoz, majd hozzáad egy alkönyvtárat, és visszaad egy DataLakeDirectoryClient objektumot későbbi használatra:

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

    return await directoryClient.CreateSubDirectoryAsync(subdirectoryName);
}

Címtár átnevezése vagy áthelyezése

A címtárak átnevezhetők vagy áthelyezhetők a következő módszerrel:

Adja meg a kívánt könyvtár elérési útját paraméterként. Az alábbi példakód bemutatja, hogyan nevezhet át alkönyvtárat:

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

Az alábbi példakód bemutatja, hogyan helyezhet át egy alkönyvtárat egy könyvtárból egy másik könyvtárba:

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

Fájl feltöltése könyvtárba

A következő módszerrel tölthet fel tartalmat egy új vagy meglévő fájlba:

Az alábbi példakód bemutatja, hogyan tölthet fel helyi fájlt egy könyvtárba a UploadAsync metódus használatával:

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

Ezzel a módszerrel tartalmakat hozhat létre és tölthet fel egy új fájlba, vagy beállíthatja, hogy true a overwrite paraméter felülírjon egy meglévő fájlt.

Adatok hozzáfűzése fájlhoz

A fájlhoz fűzendő adatokat az alábbi módszerrel töltheti fel:

Az alábbi példakód bemutatja, hogyan fűzhet adatokat egy fájl végéhez az alábbi lépésekkel:

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

Letöltés könyvtárból

Az alábbi példakód bemutatja, hogyan tölthet le egy fájlt egy könyvtárból egy helyi fájlba az alábbi lépésekkel:

Ez a példa egy BinaryReader és egy FileStream használatával ment bájtokat egy fájlba.

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

Könyvtár tartalmának listázása

A címtár tartalmát az alábbi módszerrel és az eredmény számbavételével listázhatja:

Az eredményben szereplő elérési utak számbavétele több kérést is eredményezhet a szolgáltatáshoz az értékek beolvasása közben.

Az alábbi példakód a könyvtárban található egyes fájlok nevét nyomtatja ki:

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

}

Könyvtár törlése

A következő módszerrel törölheti a címtárat:

Az alábbi példakód bemutatja, hogyan törölhet egy könyvtárat:

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

    await directoryClient.DeleteAsync();
}

Helyreállíthatóan törölt címtár visszaállítása

Az Azure Storage-ügyfélkódtárak használatával helyreállíthatja a helyreállíthatóan törölt címtárakat. A DataLakeFileSystemClient-példány törölt elérési útjai a következő módszerrel listázhatóak:

A helyreállíthatóan törölt címtárak visszaállításához használja az alábbi módszert:

Az alábbi példakód bemutatja, hogyan listázhatja a törölt elérési utakat, és visszaállíthat egy helyreállíthatóan törölt könyvtárat:

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

Ha átnevezi a helyreállíthatóan törölt elemeket tartalmazó könyvtárat, ezek az elemek le lesznek választva a címtárról. Ha vissza szeretné állítani ezeket az elemeket, vissza kell állítania a könyvtár nevét az eredeti nevére, vagy létre kell hoznia egy külön könyvtárat, amely az eredeti könyvtárnevet használja. Ellenkező esetben hibaüzenet jelenik meg, amikor megpróbálja visszaállítani a helyreállíthatóan törölt elemeket.

Felhasználói delegálási SAS létrehozása címtárhoz

Az ebben a szakaszban szereplő példakódok használatához adja hozzá a következő using irányelvet:

using Azure.Storage.Sas;

Az alábbi példakód bemutatja, hogyan hozhat létre felhasználói delegálási SAS-t egy címtárhoz, ha engedélyezve van egy hierarchikus névtér a tárfiókhoz:

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

Az alábbi példa egy szimulált ügyfélalkalmazásból teszteli az előző példában létrehozott felhasználói delegálási SAS-t. Ha az SAS érvényes, az ügyfélalkalmazás képes listázni a könyvtár fájlelérési útvonalait. Ha az SAS érvénytelen (például az SAS lejárt), a Storage szolgáltatás a 403-es hibakódot adja vissza (Tiltott).

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

A felhasználói delegálási SAS létrehozásával kapcsolatos további információkért lásd : Felhasználói delegálási SAS létrehozása a .NET-tel.

Szolgáltatás SAS létrehozása címtárhoz

A hierarchikus névtérrel rendelkező tárfiókokban létrehozhat egy szolgáltatás SAS-t egy címtárhoz. A szolgáltatás SAS létrehozásához győződjön meg arról, hogy telepítette az Azure.Storage.Files.DataLake csomag 12.5.0-s vagy újabb verzióját.

Az alábbi példa bemutatja, hogyan hozhat létre szolgáltatás SAS-t egy címtárhoz:

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

A szolgáltatás SAS létrehozásával kapcsolatos további információkért lásd : Szolgáltatás SAS létrehozása a .NET-tel.

Lásd még