Bibliothèque de client Azure File Data Lake pour Java - version 12.17.1

  • Article

Azure Data Lake Storage est la solution de stockage optimisée de Microsoft pour les charges de travail d’analyse du Big Data. Une caractéristique fondamentale de Data Lake Storage Gen2 est l’ajout d’un espace de noms hiérarchique au stockage Blob. L’espace de noms hiérarchique organise les objets/fichiers dans une hiérarchie de répertoires pour offrir un accès efficace aux données.

| Code sourceDocumentation de référence sur les | APIDocumentation | sur l’API REST | Documentation produitÉchantillons

Prise en main

Prérequis

Inclure le package

Inclure le fichier de nomenclature

Incluez le kit azure-sdk-bom à votre projet pour prendre la dépendance sur la version de disponibilité générale de la bibliothèque. Dans l’extrait de code suivant, remplacez l’espace réservé {bom_version_to_target} par le numéro de version. Pour en savoir plus sur la nomenclature, consultez LE FICHIER README DE NOMENCLATURE DU KIT DE DÉVELOPPEMENT LOGICIEL AZURE.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

Incluez ensuite la dépendance directe dans la section des dépendances sans la balise de version.

<dependencies>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-storage-file-datalake</artifactId>
  </dependency>
</dependencies>

Inclure une dépendance directe

Si vous souhaitez prendre la dépendance sur une version particulière de la bibliothèque qui n’est pas présente dans la nomenclature, ajoutez la dépendance directe à votre projet comme suit.

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-storage-file-datalake</artifactId>
    <version>12.17.1</version>
</dependency>

Créer un compte de stockage

Pour créer un compte de stockage, vous pouvez utiliser le portail Azure ou Azure CLI. Remarque : Pour utiliser data lake, l’espace de noms hiérarchique de votre compte doit être activé.

# Install the extension “Storage-Preview”
az extension add --name storage-preview
# Create the storage account
az storage account create -n my-storage-account-name -g my-resource-group --sku Standard_LRS --kind StorageV2 --hierarchical-namespace true

L’URL de votre compte de stockage, identifiée par la suite comme <your-storage-account-url>, sera mise en forme comme suit http(s)://<storage-account-name>.dfs.core.windows.net

Authentifier le client

Pour interagir avec le service de stockage, vous devez créer une instance de la classe Service Client. Pour ce faire, vous aurez besoin de la chaîne SAP du compte (signature d’accès partagé) du compte de stockage. En savoir plus sur Jeton SAS

Récupérer les informations d’identification

Jeton SAP

a. Utilisez l’extrait de code Azure CLI ci-dessous pour obtenir le jeton SAP à partir du compte de stockage.

az storage blob generate-sas \
    --account-name {Storage Account name} \
    --container-name {container name} \
    --name {blob name} \
    --permissions {permissions to grant} \
    --expiry {datetime to expire the SAS token} \
    --services {storage services the SAS allows} \
    --resource-types {resource types the SAS allows}

Exemple :

CONNECTION_STRING=<connection-string>

az storage blob generate-sas \
    --account-name MyStorageAccount \
    --container-name MyContainer \
    --name MyBlob \
    --permissions racdw \
    --expiry 2020-06-15

b. Vous pouvez également obtenir le jeton SAP du compte à partir du portail Azure.

  1. Accédez à votre compte de stockage
  2. Sélectionnez Shared access signature dans le menu de gauche
  3. Cliquez sur Generate SAS and connection string (après l’installation)
Informations d’identification de clé partagée

a. Utilisez Le nom du compte et la clé de compte. Nom du compte est le nom de votre compte de stockage.

  1. Accédez à votre compte de stockage
  2. Sélectionnez Access keys dans le menu de gauche
  3. Sous key1/key2 copier le contenu du Key champ

ou

b. Utilisez le chaîne de connexion.

  1. Accédez à votre compte de stockage
  2. Sélectionnez Access keys dans le menu de gauche
  3. Sous key1/key2 copier le contenu du Connection string champ

Concepts clés

DataLake Storage Gen2 a été conçu pour :

  • Traiter plusieurs pétaoctets d’informations tout en conservant des centaines de gigabits de débit
  • Vous permettre de gérer facilement d’énormes quantités de données

Les principales fonctionnalités de DataLake Storage Gen2 sont les suivantes :

  • Accès compatible Hadoop
  • Sur-ensemble d’autorisations POSIX
  • Rentable en termes de capacité de stockage et de transactions à faible coût
  • Pilote optimisé pour l’analytique Big Data

Une caractéristique fondamentale de Data Lake Storage Gen2 est l’ajout d’un espace de noms hiérarchique au stockage Blob. L’espace de noms hiérarchique organise les objets/fichiers dans une hiérarchie de répertoires pour offrir un accès efficace aux données.

Dans le passé, l’analytique cloud devait trouver le meilleur compromis entre les performances, la gestion et la sécurité. Data Lake Storage Gen2 traite chacun de ces aspects de plusieurs manières :

  • Les performances sont optimisées, car vous n’avez pas besoin de copier ou transformer les données avant l’analyse. L’espace de noms hiérarchique améliore considérablement les performances des opérations de gestion de répertoires, et donc les performances générale du travail.
  • La gestion est plus facile, car vous pouvez organiser et manipuler les fichiers dans des répertoires et des sous-répertoires.
  • La sécurité est applicable, car vous pouvez définir des autorisations POSIX sur des répertoires ou des fichiers spécifiques.
  • La rentabilité est réelle, car Data Lake Storage Gen2 repose sur le Stockage Blob Azure dont le coût est faible. Les fonctionnalités supplémentaires réduisent encore le coût total de possession de l’analytique du Big Data sur Azure.

Data Lake Storage Gen2 propose deux types de ressources :

  • utilisé _filesystem via « DataLakeFileSystemClient »
  • _path utilisé via « DataLakeFileClient » ou « DataLakeDirectoryClient »
ADLS Gen2 Objet blob
FileSystem Conteneur
Chemin d’accès (fichier ou répertoire) Objet blob

Remarque : Cette bibliothèque cliente ne prend pas en charge les comptes de stockage HNS (espace de noms hiérarchiques) désactivés.

Format d’URL

Les chemins d’accès sont adressables au format d’URL suivant : L’URL suivante adresse un fichier :

https://${myaccount}.dfs.core.windows.net/${myfilesystem}/${myfile}

Syntaxe d'URI de ressource

Pour le compte de stockage, l’URI de base pour les opérations datalake inclut uniquement le nom du compte :

https://${myaccount}.dfs.core.windows.net

Pour un système de fichiers, l’URI de base inclut le nom du compte et le nom du système de fichiers :

https://${myaccount}.dfs.core.windows.net/${myfilesystem}

Pour un fichier/répertoire, l’URI de base inclut le nom du compte, le nom du système de fichiers et le nom du chemin d’accès :

https://${myaccount}.dfs.core.windows.net/${myfilesystem}/${mypath}

Notez que les URI ci-dessus peuvent ne pas tenir pour les scénarios plus avancés tels que les noms de domaine personnalisés.

Exemples

Les sections suivantes fournissent plusieurs extraits de code couvrant certaines des tâches les plus courantes de Stockage Blob Azure, notamment :

Créez une classe DataLakeServiceClient

Créez un en DataLakeServiceClient utilisant le sasToken généré ci-dessus.

DataLakeServiceClient dataLakeServiceClient = new DataLakeServiceClientBuilder()
    .endpoint("<your-storage-account-url>")
    .sasToken("<your-sasToken>")
    .buildClient();

ou

// Only one "?" is needed here. If the sastoken starts with "?", please removing one "?".
DataLakeServiceClient dataLakeServiceClient = new DataLakeServiceClientBuilder()
    .endpoint("<your-storage-account-url>" + "?" + "<your-sasToken>")
    .buildClient();

Créez une classe DataLakeFileSystemClient

Créez un à DataLakeFileSystemClient l’aide d’un DataLakeServiceClient.

DataLakeFileSystemClient dataLakeFileSystemClient = dataLakeServiceClient.getFileSystemClient("myfilesystem");

ou

Créez un DataLakeFileSystemClient à partir du générateur sasToken généré ci-dessus.

DataLakeFileSystemClient dataLakeFileSystemClient = new DataLakeFileSystemClientBuilder()
    .endpoint("<your-storage-account-url>")
    .sasToken("<your-sasToken>")
    .fileSystemName("myfilesystem")
    .buildClient();

ou

// Only one "?" is needed here. If the sastoken starts with "?", please removing one "?".
DataLakeFileSystemClient dataLakeFileSystemClient = new DataLakeFileSystemClientBuilder()
    .endpoint("<your-storage-account-url>" + "/" + "myfilesystem" + "?" + "<your-sasToken>")
    .buildClient();

Créez une classe DataLakeFileClient

Créez un à DataLakeFileClient l’aide d’un DataLakeFileSystemClient.

DataLakeFileClient fileClient = dataLakeFileSystemClient.getFileClient("myfile");

ou

Créez un FileClient à partir du générateur sasToken généré ci-dessus.

DataLakeFileClient fileClient = new DataLakePathClientBuilder()
    .endpoint("<your-storage-account-url>")
    .sasToken("<your-sasToken>")
    .fileSystemName("myfilesystem")
    .pathName("myfile")
    .buildFileClient();

ou

// Only one "?" is needed here. If the sastoken starts with "?", please removing one "?".
DataLakeFileClient fileClient = new DataLakePathClientBuilder()
    .endpoint("<your-storage-account-url>" + "/" + "myfilesystem" + "/" + "myfile" + "?" + "<your-sasToken>")
    .buildFileClient();

Créez une classe DataLakeDirectoryClient

Obtenez un à DataLakeDirectoryClient l’aide d’un DataLakeFileSystemClient.

DataLakeDirectoryClient directoryClient = dataLakeFileSystemClient.getDirectoryClient("mydir");

ou

Créez un DirectoryClient à partir du générateur sasToken généré ci-dessus.

DataLakeDirectoryClient directoryClient = new DataLakePathClientBuilder()
    .endpoint("<your-storage-account-url>")
    .sasToken("<your-sasToken>")
    .fileSystemName("myfilesystem")
    .pathName("mydir")
    .buildDirectoryClient();

ou

// Only one "?" is needed here. If the sastoken starts with "?", please removing one "?".
DataLakeDirectoryClient directoryClient = new DataLakePathClientBuilder()
    .endpoint("<your-storage-account-url>" + "/" + "myfilesystem" + "/" + "mydir" + "?" + "<your-sasToken>")
    .buildDirectoryClient();

Créer un système de fichiers

Créez un système de fichiers à l’aide d’un DataLakeServiceClient.

dataLakeServiceClient.createFileSystem("myfilesystem");

ou

Créez un système de fichiers à l’aide d’un DataLakeFileSystemClient.

dataLakeFileSystemClient.create();

Énumérer les chemins d’accès

Énumération de tous les chemins à l’aide d’un DataLakeFileSystemClient.

for (PathItem pathItem : dataLakeFileSystemClient.listPaths()) {
    System.out.println("This is the path name: " + pathItem.getName());
}

Renommer un fichier

Renommez un fichier à l’aide d’un DataLakeFileClient.

//Need to authenticate with azure identity and add role assignment "Storage Blob Data Contributor" to do the following operation.
DataLakeFileClient fileClient = dataLakeFileSystemClient.getFileClient("myfile");
fileClient.create();
fileClient.rename("new-file-system-name", "new-file-name");

Renommer un répertoire

Renommez un répertoire à l’aide d’un DataLakeDirectoryClient.

//Need to authenticate with azure identity and add role assignment "Storage Blob Data Contributor" to do the following operation.
DataLakeDirectoryClient directoryClient = dataLakeFileSystemClient.getDirectoryClient("mydir");
directoryClient.create();
directoryClient.rename("new-file-system-name", "new-directory-name");

Obtenir les propriétés du fichier

Obtenez les propriétés d’un fichier à l’aide d’un DataLakeFileClient.

DataLakeFileClient fileClient = dataLakeFileSystemClient.getFileClient("myfile");
fileClient.create();
PathProperties properties = fileClient.getProperties();

Obtenir les propriétés du répertoire

Obtenez des propriétés à partir d’un répertoire à l’aide d’un DataLakeDirectoryClient.

DataLakeDirectoryClient directoryClient = dataLakeFileSystemClient.getDirectoryClient("mydir");
directoryClient.create();
PathProperties properties = directoryClient.getProperties();

S’authentifier avec l’identité Azure

La bibliothèque d’identités Azure prend en charge Azure Active Directory pour l’authentification auprès du Stockage Azure.

DataLakeServiceClient storageClient = new DataLakeServiceClientBuilder()
    .endpoint("<your-storage-account-url>")
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildClient();

Dépannage

Lors de l’interaction avec data lake à l’aide de cette bibliothèque cliente Java, les erreurs retournées par le service correspondent aux mêmes codes de status HTTP retournés pour les requêtes d’API REST. Par exemple, si vous essayez de récupérer un système de fichiers ou un chemin d’accès qui n’existe pas dans votre compte de stockage, une 404 erreur est retournée, indiquant Not Found.

Client HTTP par défaut

Toutes les bibliothèques de client utilisent par défaut le client HTTP Netty. L’ajout de la dépendance ci-dessus configure automatiquement la bibliothèque de client pour utiliser le client HTTP Netty. La configuration ou la modification du client HTTP sont détaillées dans le wiki pour clients HTTP.

Bibliothèque SSL par défaut

Toutes les bibliothèques de client utilisent par défaut la bibliothèque BoringSSL Tomcat native pour permettre des performances de niveau natif pour les opérations SSL. La bibliothèque BoringSSL est un fichier uber jar contenant des bibliothèques natives pour Linux/macOS/Windows. Elle offre de meilleures performances que l’implémentation SSL par défaut au sein du JDK. Pour plus d’informations, notamment sur la réduction de la taille des dépendances, consultez la section du wiki consacrée à l’optimisation des performances.

Étapes suivantes

Plusieurs exemples de Kit de développement logiciel (SDK) Java storage datalake sont disponibles dans le référentiel GitHub du SDK.

Contribution

Ce projet accepte les contributions et les suggestions. La plupart des contributions vous demandent d’accepter un contrat de licence de contribution (CLA) spécifiant que vous avez le droit de nous accorder les droits d’utiliser votre contribution, et que vous nous les accordez.

Quand vous envoyez une demande de tirage (pull request), un bot CLA détermine automatiquement si vous devez fournir un contrat CLA et agrémenter la demande de tirage de façon appropriée (par exemple, avec une étiquette ou un commentaire). Suivez simplement les instructions fournies par le bot. Vous ne devez effectuer cette opération qu’une seule fois sur tous les dépôts utilisant notre contrat CLA.

Ce projet a adopté le Code de conduite Open Source de Microsoft. Pour plus d’informations, consultez les Questions fréquentes (FAQ) sur le code de conduite ou envoyez vos questions ou vos commentaires à opencode@microsoft.com.

Impressions