Bibliothèque de client Azure File Share pour Java - version 12.20.1

  • Article

Le protocole SMB (Server Message Block) est le protocole de partage de fichiers préféré utilisé localement aujourd’hui. Le service De partage de fichiers Microsoft Azure permet aux clients de tirer parti de la disponibilité et de la scalabilité du SMB IaaS (Cloud Infrastructure as a Service) d’Azure sans avoir à réécrire les applications clientes SMB.

Les fichiers stockés dans les partages de service Azure File Share sont accessibles via le protocole SMB, ainsi que via les API REST. Le service De partage de fichiers offre les quatre ressources suivantes : le compte de stockage, les partages, les répertoires et les fichiers. Les partages offrent un moyen d'organiser des ensembles de fichiers. Ils peuvent également être montés en tant que partage de fichiers SMB hébergé dans le cloud.

| 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-share</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-share</artifactId>
  <version>12.20.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.

az storage account create \
    --resource-group <resource-group-name> \
    --name <storage-account-name> \
    --location <location>

Authentifier le client

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

Obtenir des informations d’identification

  • Jeton SAS

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

      az storage file generate-sas
    --name {account name}
    --expiry {date/time to expire SAS token}
    --permission {permission to grant}
    --connection-string {connection string of the storage account}

      CONNECTION_STRING=<connection-string>

az storage file generate-sas
    --name javasdksas
    --expiry 2019-06-05
    --permission rpau
    --connection-string $CONNECTION_STRING

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

      1. Accédez à votre compte de stockage.
      2. Cliquez sur « Signature d’accès partagé ».
      3. Cliquez sur « Générer sas et chaîne de connexion ».

  • Informations d’identification de clé partagée

    • Il existe deux façons de créer des informations d’identification de clé partagée : la première consiste à utiliser le nom du compte de stockage et la clé de compte. La deuxième utilise le chaîne de connexion de stockage.
      1. Utilisez le nom du compte et la clé de compte.
        1. Le nom du compte est le nom de votre compte de stockage.
        2. Accédez à votre compte de stockage.
        3. Sélectionnez l’onglet « Clés d’accès ».
        4. Copiez la valeur « Key » pour la clé 1 ou la clé 2.
      2. Utiliser le chaîne de connexion
        1. Accédez à votre compte de stockage.
        2. Sélectionnez l’onglet « Clés d’accès ».
        3. Copiez la valeur « Chaîne de connexion » pour la clé 1 ou la clé 2.

Concepts clés

Format d’URL

Les partages de fichiers peuvent être adressés au format d’URL suivant :

https://<storage account>.file.core.windows.net/<share>

L'URL suivante désigne une file d'attente du schéma :

https://myaccount.file.core.windows.net/images-to-download

Syntaxe d'URI de ressource

Pour le compte de stockage, l'URI de base pour les opérations de file d'attente comprend uniquement le nom du compte :

https://myaccount.file.core.windows.net

Pour le fichier, l’URI de base inclut le nom du compte et le nom du répertoire/fichier :

https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile

Gestion des exceptions

Utilise la shareServiceClient section générée à partir de shareServiceClient ci-dessous.

try {
    shareServiceClient.createShare("myShare");
} catch (ShareStorageException e) {
    logger.error("Failed to create a share with error code: " + e.getErrorCode());
}

Noms de ressource

L'URI qui référence un partage, un répertoire ou un fichier doit être unique. Dans un compte de stockage donné, chaque partage doit avoir un nom unique. Chaque fichier dans un partage ou un répertoire donné doit également avoir un nom unique au sein de ce partage ou de ce répertoire.

Si vous essayez de créer un partage, un répertoire ou un fichier avec un nom non conforme aux règles d'affectation des noms, la demande échoue avec le code d'état 400 (Requête incorrecte).

Noms des partages

Les règles pour les noms de service de partage de fichiers sont plus restrictives que ce qui est prescrit par le protocole SMB pour les noms de partage SMB, de sorte que les services Blob et File peuvent partager des conventions de nommage similaires pour les conteneurs et les partages. Les restrictions d'affectation des noms pour les partages sont les suivantes :

  1. Un nom de partage doit être un nom DNS valide.
  2. Les noms de partage doivent commencer par une lettre ou par un chiffre, et ne peuvent contenir que des lettres, des chiffres et le tiret (-).
  3. Chaque tiret (-) doit être immédiatement précédé et suivi d'une lettre ou d'un chiffre. Les tirets consécutifs ne sont pas autorisés dans les noms de partage.
  4. Toutes les lettres d'un nom de partage doivent être en minuscules.
  5. Un nom de partage doit comprendre entre 3 et 63 caractères.

Noms des répertoires et des fichiers

Les règles de nommage du service De partage de fichiers Azure pour les noms de répertoires et de fichiers sont les suivantes :

  1. Les noms de répertoires de partage et de fichiers respectent la casse et ne respectent pas la casse.
  2. Les noms de répertoire de partage et de composants de fichiers ne doivent pas contenir plus de 255 caractères.
  3. Les noms de répertoires de partage ne peuvent pas se terminer par le caractère de barre oblique (/). Si renseignée, elle sera automatiquement supprimée.
  4. Les noms de fichiers de partage ne doivent pas se terminer par le caractère de barre oblique (/).
  5. Les caractères d’URL réservées doivent être correctement placés dans une séquence d’échappement.
  6. Les caractères suivants ne sont pas autorisés : " \ / : | < > * ?
  7. Les caractères de chemin d'accès d'URL non autorisés sont interdits. Les points de code comme \uE000, bien que valides dans les noms de fichiers NTFS, ne sont pas des caractères Unicode valides. En outre, certains caractères ASCII ou Unicode, comme les caractères de contrôle (0x00 à 0x1F, \u0081, etc.), ne sont pas autorisés. Pour connaître les règles régissant les chaînes Unicode dans HTTP/1.1 , consultez RFC 2616, Section 2.2 : Règles de base et RFC 3987.
  8. Les noms de fichiers suivants ne sont pas autorisés : LPT1, LPT2, LPT3, LPT4, LPT5, LPT6, LPT7, LPT8, LPT9, COM1, COM2, COM3, COM4, COM5, COM6, COM7, COM8, COM9, PRN, AUX, NUL, CON, CLOCK$, caractère point (.) et deux points (..).

Noms de métadonnées

Les métadonnées d'une ressource de partage ou de fichier sont stockées en tant que paires nom-valeur associées à la ressource. Les répertoires n'ont pas de métadonnées. Les noms de métadonnées doivent respecter les règles de nommage des identificateurs C#.

Notez que les noms de métadonnées conservent la casse avec laquelle ils ont été créés, mais ne la respecte plus quand ils sont définis ou lus. Si deux en-têtes de métadonnées ou plus de même nom sont envoyés pour une ressource, le service de fichiers Azure renvoie le code d'état 400 (Requête incorrecte).

Share Services

L’API REST du service de partage de fichiers fournit des opérations sur les comptes et gère les propriétés du service de fichiers. Il permet d’effectuer des opérations de liste et de suppression de partages, d’obtention et de définition des propriétés du service de fichiers. Une fois que vous avez saSToken, vous pouvez construire le shareServiceClient avec ${accountName}, ${sasToken}

String shareServiceURL = String.format("https://%s.file.core.windows.net", ACCOUNT_NAME);
ShareServiceClient shareServiceClient = new ShareServiceClientBuilder().endpoint(shareServiceURL)
    .sasToken(SAS_TOKEN).buildClient();

Partager

La ressource de partage inclut des métadonnées et propriétés pour ce partage. Il permet les opérations de création, de création d’instantané, de suppression de partages, d’obtention de propriétés de partage, de définition de métadonnées, d’obtention et de définition d’ACL (stratégie d’accès). L’obtention et la définition de la liste de contrôle d’accès (stratégie d’accès) ne peuvent être utilisées que par ShareClient avec ConnectionString.

Partager avec SASToken

Une fois que vous avez saSToken, vous pouvez construire le client de partage avec ${accountName}, ${shareName}, ${sasToken}

String shareURL = String.format("https://%s.file.core.windows.net", ACCOUNT_NAME);
ShareClient shareClient = new ShareClientBuilder().endpoint(shareURL)
    .sasToken(SAS_TOKEN).shareName(shareName).buildClient();

Partager avec ConnectionString

Une fois que vous avez connectionString, vous pouvez construire le client de partage avec ${accountName}, ${shareName}, ${connectionString}

String shareURL = String.format("https://%s.file.core.windows.net", ACCOUNT_NAME);
ShareClient shareClient = new ShareClientBuilder().endpoint(shareURL)
    .connectionString(CONNECTION_STRING).shareName(shareName).buildClient();

Partager avec TokenCredential

Une fois que vous disposez de TokenCredential, vous pouvez construire le client de partage avec ${accountName}, ${shareName} et ShareTokenIntent. ShareTokenIntent.BACKUP spécifie les demandes destinées aux opérations de type de sauvegarde/administrateur, ce qui signifie que toutes les ACL de fichiers/répertoires sont ignorées et que des autorisations complètes sont accordées. L’utilisateur doit disposer de l’autorisation RBAC requise pour pouvoir utiliser ShareTokenIntent.BACKUP.

String shareURL = String.format("https://%s.file.core.windows.net", ACCOUNT_NAME);

ShareClient serviceClient = new ShareClientBuilder()
    .endpoint(shareURL)
    .credential(tokenCredential)
    .shareTokenIntent(ShareTokenIntent.BACKUP)
    .shareName(shareName)
    .buildClient();

Répertoire

La ressource du répertoire comprend les propriétés de ce répertoire. Il permet de créer, répertorier, supprimer des répertoires ou des sous-répertoires ou fichiers, obtenir des propriétés, définir des métadonnées, répertorier et forcer la fermeture des handles. Une fois que vous avez sasToken, vous pouvez construire le client de service de fichiers avec ${accountName}, ${shareName}, ${directoryPath}, ${sasToken}

String directoryURL = String.format("https://%s.file.core.windows.net", ACCOUNT_NAME);
ShareDirectoryClient directoryClient = new ShareFileClientBuilder().endpoint(directoryURL)
    .sasToken(SAS_TOKEN).shareName(shareName).resourcePath(directoryPath).buildDirectoryClient();

Fichier

La ressource de fichier inclut les propriétés de ce fichier. Il permet de créer, charger, copier, télécharger, supprimer des fichiers ou une plage de fichiers, obtenir des propriétés, définir des métadonnées, répertorier et forcer la fermeture des handles. Une fois que vous avez le SASToken, vous pouvez construire le client de service de fichiers avec ${accountName}, ${shareName}, ${directoryPath}, ${fileName}, ${sasToken}

String fileURL = String.format("https://%s.file.core.windows.net", ACCOUNT_NAME);
ShareFileClient fileClient = new ShareFileClientBuilder().connectionString(CONNECTION_STRING)
    .endpoint(fileURL).shareName(shareName).resourcePath(directoryPath + "/" + fileName).buildFileClient();

Exemples

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

Créer un partage

Créez un partage dans le compte de stockage. Lève StorageException Si le partage ne parvient pas à être créé. Prise d’un ShareServiceClient dans KeyConcept, ${shareServiceClient}.

String shareName = "testshare";
shareServiceClient.createShare(shareName);

Créer un instantané sur le partage

Prise d’un ShareServiceClient dans KeyConcept, ${shareServiceClient}.

String shareName = "testshare";
ShareClient shareClient = shareServiceClient.getShareClient(shareName);
shareClient.createSnapshot();

Créer un répertoire

En prenant le shareClient initialisé ci-dessus, ${shareClient}.

String dirName = "testdir";
shareClient.createDirectory(dirName);

Créer un sous-répertoire

En prenant directoryClient dans KeyConcept, ${directoryClient}.

String subDirName = "testsubdir";
directoryClient.createSubdirectory(subDirName);

créer un fichier

En prenant directoryClient dans KeyConcept, ${directoryClient} .

String fileName = "testfile";
long maxSize = 1024;
directoryClient.createFile(fileName, maxSize);

Répertorier tous les partages

En prenant shareServiceClient dans KeyConcept, ${shareServiceClient}

shareServiceClient.listShares();

Répertorier tous les sous-répertoires et fichiers

En prenant directoryClient dans KeyConcept, ${directoryClient}

directoryClient.listFilesAndDirectories();

Répertorier toutes les plages dans le fichier

En prenant fileClient dans KeyConcept, ${fileClient}

fileClient.listRanges();

Supprimer un partage

En prenant shareClient dans KeyConcept, ${shareClient}

shareClient.delete();

Supprimer un répertoire

Prenant shareClient dans KeyConcept, ${shareClient} .

String dirName = "testdir";
shareClient.deleteDirectory(dirName);

Supprimer un sous-répertoire

En prenant directoryClient dans KeyConcept, ${directoryClient} .

String subDirName = "testsubdir";
directoryClient.deleteSubdirectory(subDirName);

Supprimer un fichier

En prenant directoryClient dans KeyConcept, ${directoryClient} .

String fileName = "testfile";
directoryClient.deleteFile(fileName);

Copier un fichier

En utilisant fileClient dans KeyConcept, ${fileClient} avec la chaîne de l’URL source.

String sourceURL = "https://myaccount.file.core.windows.net/myshare/myfile";
Duration pollInterval = Duration.ofSeconds(2);
SyncPoller<ShareFileCopyInfo, Void> poller = fileClient.beginCopy(sourceURL, (Map<String, String>) null, pollInterval);

Abandonner la copie d’un fichier

En prenant fileClient dans KeyConcept, ${fileClient} avec la réponse d’informations de copie retournée ci-dessus ${copyId}=[copyInfoResponse](#copy-a-file).

fileClient.abortCopy("copyId");

Charger des données dans le stockage

En prenant fileClient dans KeyConcept, ${fileClient} avec les données de « default » .

String uploadText = "default";
InputStream data = new ByteArrayInputStream(uploadText.getBytes(StandardCharsets.UTF_8));
fileClient.upload(data, uploadText.length());

Charger des données d’une taille supérieure à 4 Mo dans le stockage

En prenant fileClient dans KeyConcept, ${fileClient} avec les données de « default » .

byte[] data = "Hello, data sample!".getBytes(StandardCharsets.UTF_8);

long chunkSize = 4 * 1024 * 1024L;
if (data.length > chunkSize) {
    for (int offset = 0; offset < data.length; offset += chunkSize) {
        try {
            // the last chunk size is smaller than the others
            chunkSize = Math.min(data.length - offset, chunkSize);

            // select the chunk in the byte array
            byte[] subArray = Arrays.copyOfRange(data, offset, (int) (offset + chunkSize));

            // upload the chunk
            fileClient.uploadWithResponse(new ByteArrayInputStream(subArray), chunkSize, (long) offset, null, Context.NONE);
        } catch (RuntimeException e) {
            logger.error("Failed to upload the file", e);
            if (Boolean.TRUE.equals(fileClient.exists())) {
                fileClient.delete();
            }
            throw e;
        }
    }
} else {
    fileClient.upload(new ByteArrayInputStream(data), data.length);
}

Charger un fichier dans le stockage

En prenant fileClient dans KeyConcept, ${fileClient} .

String filePath = "${myLocalFilePath}";
fileClient.uploadFromFile(filePath);

Télécharger des données à partir d’une plage de fichiers

En prenant fileClient dans KeyConcept, ${fileClient} avec la plage comprise entre 1024 et 2048.

ShareFileRange fileRange = new ShareFileRange(0L, 2048L);
OutputStream stream = new ByteArrayOutputStream();
fileClient.downloadWithResponse(stream, fileRange, false, null, Context.NONE);

Télécharger un fichier à partir du stockage

En prenant le fileClient dans KeyConcept, ${fileClient} puis téléchargez-le dans le fichier filePath.

String filePath = "${myLocalFilePath}";
fileClient.downloadToFile(filePath);

Obtenir les propriétés d’un service de partage

Prise d’un ShareServiceClient dans KeyConcept, ${shareServiceClient} .

shareServiceClient.getProperties();

Définir les propriétés d’un service de partage

Prise d’un ShareServiceClient dans KeyConcept, ${shareServiceClient} .

ShareServiceProperties properties = shareServiceClient.getProperties();

properties.getMinuteMetrics().setEnabled(true).setIncludeApis(true);
properties.getHourMetrics().setEnabled(true).setIncludeApis(true);

shareServiceClient.setProperties(properties);

Définir des métadonnées de partage

Prenant shareClient dans KeyConcept, ${shareClient} .

Map<String, String> metadata = Collections.singletonMap("directory", "metadata");
shareClient.setMetadata(metadata);

Obtenir une stratégie d’accès au partage

Prenant shareClient dans KeyConcept, ${shareClient} .

shareClient.getAccessPolicy();

Définir une stratégie d’accès au partage

Prenant shareClient dans KeyConcept, ${shareClient} .

ShareAccessPolicy accessPolicy = new ShareAccessPolicy().setPermissions("r")
    .setStartsOn(OffsetDateTime.now(ZoneOffset.UTC))
    .setExpiresOn(OffsetDateTime.now(ZoneOffset.UTC).plusDays(10));
ShareSignedIdentifier permission = new ShareSignedIdentifier().setId("mypolicy").setAccessPolicy(accessPolicy);
shareClient.setAccessPolicy(Collections.singletonList(permission));

Obtenir les handles sur le fichier de répertoire

En prenant directoryClient dans KeyConcept, ${directoryClient}

PagedIterable<HandleItem> handleItems = directoryClient.listHandles(null, true, Duration.ofSeconds(30), Context.NONE);

Forcer la fermeture des handles sur l’ID de handle

Prise de directoryClient dans KeyConcept et ${directoryClient} de l’ID de handle retourné ci-dessus ${handleId}=[handleItems](#get-handles-on-directory-file)

PagedIterable<HandleItem> handleItems = directoryClient.listHandles(null, true, Duration.ofSeconds(30), Context.NONE);
String handleId = handleItems.iterator().next().getHandleId();
directoryClient.forceCloseHandleWithResponse(handleId, Duration.ofSeconds(30), Context.NONE);

Définir le quota sur le partage

Prenant shareClient dans KeyConcept, ${shareClient} .

int quotaOnGB = 1;
shareClient.setPropertiesWithResponse(new ShareSetPropertiesOptions().setQuotaInGb(quotaOnGB), null, Context.NONE);

Définir les httpheaders de fichier

En prenant fileClient dans KeyConcept, ${fileClient} .

ShareFileHttpHeaders httpHeaders = new ShareFileHttpHeaders().setContentType("text/plain");
fileClient.setProperties(1024, httpHeaders, null, null);

Dépannage

Général

Lorsque vous interagissez avec un fichier à 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 demandes d’API REST. Par exemple, si vous essayez de récupérer un partage 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

Contribution

Ce projet accepte les contributions et les suggestions. La plupart des contributions vous demandent d’accepter un contrat de licence de contribution (CLA) déclarant que vous avez le droit de nous accorder, et que vous nous accordez réellement, les droits d’utilisation de votre contribution. Pour plus d’informations, visitez https://cla.microsoft.com.

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.

Pour plus d’informations sur la contribution à ce dépôt, consultez le guide de contribution.

  1. Fourchez-le
  2. Créer votre branche de fonctionnalité (git checkout -b my-new-feature)
  3. Valider vos modifications (git commit -am 'Add some feature')
  4. Envoyer (push) vers la branche (git push origin my-new-feature)
  5. Créer une demande de tirage

Impressions