Biblioteca cliente de Azure File Share para Java: versión 12.20.1

  • Artículo

El protocolo bloque de mensajes del servidor (SMB) es el protocolo de recurso compartido de archivos preferido que se usa actualmente en el entorno local. El servicio Microsoft Azure File Share permite a los clientes aprovechar la disponibilidad y escalabilidad de SMB de infraestructura como servicio (IaaS) de Azure sin tener que volver a escribir aplicaciones cliente SMB.

Los archivos almacenados en recursos compartidos de servicio de Recursos compartidos de archivos de Azure son accesibles a través del protocolo SMB y también a través de las API REST. El servicio Recurso compartido de archivos ofrece los cuatro recursos siguientes: la cuenta de almacenamiento, los recursos compartidos, los directorios y los archivos. Los recursos compartidos proporcionan una manera de organizar conjuntos de archivos y también se pueden montar como un recurso compartido de archivos mediante SMB hospedado en la nube.

Código | fuenteDocumentación | de referencia de APIDocumentación | de la API RESTDocumentación | del productoMuestras

Introducción

Requisitos previos

Inclusión del paquete

Inclusión del archivo BOM

Incluya azure-sdk-bom en el proyecto para depender de la versión de disponibilidad general de la biblioteca. En el fragmento de código siguiente, reemplace el marcador de posición {bom_version_to_target} por el número de versión. Para más información sobre la lista de materiales, consulte EL ARCHIVO LÉAME BOM del SDK de 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>

y, luego, incluya la dependencia directa en la sección de dependencias sin la etiqueta de versión.

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

Inclusión de dependencias directas

Si quiere depender de una versión determinada de la biblioteca que no está presente en la lista de materiales, agregue la dependencia directa al proyecto como se indica a continuación.

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-storage-file-share</artifactId>
  <version>12.20.1</version>
</dependency>

Creación de una cuenta de almacenamiento

Para crear una cuenta de almacenamiento, puede usar Azure Portal o la CLI de Azure.

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

Autenticar el cliente

Para interactuar con el servicio De almacenamiento (Servicio de recurso compartido de archivos, Recurso compartido, Directorio, MessageId, Archivo), deberá crear una instancia de la clase Service Client. Para que esto sea posible, necesitará la cadena saS de cuenta (firma de acceso compartido) de la cuenta de almacenamiento. Más información en Token de SAS

Get Credentials

  • SAS Token

    • Use el siguiente fragmento de código de la CLI de Azure para obtener el token de SAS de la cuenta de almacenamiento.

      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

    • Como alternativa, obtenga el token de SAS de cuenta de Azure Portal.

      1. Vaya a la cuenta de almacenamiento.
      2. Haga clic en "Firma de acceso compartido".
      3. Haga clic en "Generar SAS y cadena de conexión".

  • Credencial de clave compartida

    • Hay dos maneras de crear una credencial de clave compartida; la primera consiste en usar el nombre de la cuenta de almacenamiento y la clave de cuenta. El segundo usa el cadena de conexión de almacenamiento.
      1. Use el nombre de la cuenta y la clave de cuenta.
        1. El nombre de la cuenta es el nombre de la cuenta de almacenamiento.
        2. Vaya a la cuenta de almacenamiento.
        3. Seleccione la pestaña "Claves de acceso".
        4. Copie el valor "Key" para Key 1 o Key 2.
      2. Usar el cadena de conexión
        1. Vaya a la cuenta de almacenamiento.
        2. Seleccione la pestaña "Claves de acceso".
        3. Copie el valor "Cadena de conexión" para la clave 1 o la clave 2.

Conceptos clave

Formato de dirección URL

Los recursos compartidos de archivos son direccionables con el siguiente formato de dirección URL:

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

La siguiente dirección URL dirige a una cola del diagrama:

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

Sintaxis del URI de recurso

En lo que respecta a la cuenta de almacenamiento, el URI base para las operaciones en la cola incluye solamente el nombre de la cuenta:

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

En el caso del archivo, el URI base incluye el nombre de la cuenta y el nombre del directorio o archivo:

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

Controlar las excepciones

Usa la shareServiceClient sección generada a partir de shareServiceClient siguiente.

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

Nombres de recurso

El URI para hacer referencia a un recurso compartido, directorio o archivo debe ser único. En una cuenta de almacenamiento concreta, cada recurso compartido debe tener un nombre único. Todos los archivos de un determinado recurso compartido o directorio también deben tener un nombre único dentro de ese recurso compartido o directorio.

Si intenta crear un recurso compartido, directorio o archivo con un nombre que infrinja las reglas de nomenclatura, la solicitud producirá un error con el código de estado 400 (solicitud incorrecta).

Nombres de recursos compartidos

Las reglas para los nombres de servicio de recurso compartido de archivos son más restrictivas que las que prescribe el protocolo SMB para los nombres de recurso compartido de SMB, de modo que los servicios de blob y archivos puedan compartir convenciones de nomenclatura similares para contenedores y recursos compartidos. Las restricciones de nomenclatura para los recursos compartidos son:

  1. El nombre del recurso compartido debe ser un nombre DNS válido.
  2. Los nombres de recursos compartidos deben comenzar con una letra o un número y solo pueden contener letras, números y guiones (-).
  3. Cada guión (-) debe estar precedido y seguido inmediatamente de una letra o un número; los guiones consecutivos no se permiten en los nombres de recursos compartidos.
  4. Todas las letras de un nombre de recurso compartido deben ser minúsculas.
  5. Los nombres de recursos compartidos deben tener entre 3 y 63 caracteres.

Nombres de archivo y directorio

Las reglas de nomenclatura del servicio Azure File Share para los nombres de directorio y archivo son las siguientes:

  1. Los nombres de directorio y archivo compartidos conservan mayúsculas de minúsculas y distinguen mayúsculas de minúsculas.
  2. Los nombres de directorio y componente de archivo compartidos no deben tener más de 255 caracteres de longitud.
  3. Los nombres de directorio compartido no pueden terminar con el carácter de barra diagonal (/). Si se proporciona, se quitará automáticamente.
  4. Los nombres de archivo compartidos no deben terminar con el carácter de barra diagonal (/).
  5. Los caracteres de URL reservadas deben convertirse correspondientemente.
  6. No se permiten los caracteres siguientes: " \ / : | < > * ?
  7. No se permiten los caracteres de ruta de acceso de dirección URL no válidos. los puntos de código como \uE000, aunque son válidos en nombres de archivos NTFS, no son caracteres Unicode válidos. Por otra parte, algunos caracteres ASCII o Unicode, como los caracteres de control (0x00 a 0x1F, \u0081, etc.), tampoco están permitidos. Para conocer las reglas que rigen las cadenas Unicode en HTTP/1.1, consulte RFC 2616, sección 2.2: Reglas básicas y RFC 3987.
  8. No se permiten los siguientes nombres de archivo: LPT1, LPT2, LPT3, LPT4, LPT5, LPT6, LPT7, LPT8, LPT9, COM1, COM2, COM3, COM4, COM5, COM6, COM7, COM8, COM9, PRN, AUX, NUL, CON, CLOCK$, dot character (.) y dos caracteres de punto (..).

Nombres de metadatos

Los metadatos de un recurso compartido o un recurso de archivos se almacenan como pares de valor con nombre asociados al recurso. Los directorios no tiene metadatos. Los nombres de metadatos deben cumplir las reglas de nomenclatura de los identificadores de C#.

Tenga en cuenta que los nombres de los metadatos conservan las mayúsculas y minúsculas iniciales, pero no distinguen entre mayúsculas y minúsculas cuando se establecen o se leen. Si se envían dos o más encabezados de metadatos con el mismo nombre para un recurso, el servicio Archivo de Azure devuelve el código de estado 400 (solicitud incorrecta).

Compartir servicios

La API de REST del servicio recurso compartido de archivos proporciona operaciones en cuentas y administra las propiedades del servicio de archivos. Permite las operaciones de enumerar y eliminar recursos compartidos, obtener y establecer las propiedades del servicio de archivos. Una vez que tenga saSToken, puede construir con shareServiceClient${accountName}, ${sasToken}

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

Compartir

El recurso de recurso compartido incluye los metadatos y las propiedades del recurso compartido. Permite las operaciones de creación, creación de instantáneas, eliminación de recursos compartidos, obtención de propiedades de recurso compartido, establecimiento de metadatos, obtención y configuración de ACL (directiva de acceso). ShareClient con ConnectionString solo puede usar la ACL (directiva de acceso) y establecerla.

Compartir con SASToken

Una vez que tenga SASToken, puede construir el cliente compartido con ${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();

Compartir con ConnectionString

Una vez que tenga ConnectionString, puede construir el cliente de recurso compartido con ${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();

Uso compartido con TokenCredential

Una vez que tenga TokenCredential, puede construir el cliente de recurso compartido con ${accountName}y ShareTokenIntent${shareName} . ShareTokenIntent.BACKUP especifica las solicitudes destinadas a las operaciones de tipo de copia de seguridad o administrador, lo que significa que se omiten todas las ACL de archivos o directorios y se conceden permisos completos. El usuario debe tener el permiso RBAC necesario para poder usar 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();

Directorio

El recurso de directorio incluye las propiedades de ese directorio. Permite las operaciones de crear, enumerar, eliminar directorios o subdirectorios o archivos, obtener propiedades, establecer metadatos, enumerar y forzar el cierre de los identificadores. Una vez que tenga SASToken, puede construir el cliente del servicio de archivos con ${accountName}, ${shareName}, ${directoryPath}, y . ${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();

Archivo

El recurso de archivo incluye las propiedades de ese archivo. Permite las operaciones de creación, carga, copia, descarga, eliminación de archivos o rango de archivos, obtención de propiedades, establecimiento de metadatos, enumeración y forzar el cierre de los identificadores. Una vez que tenga SASToken, puede construir el cliente del servicio de archivos con ${accountName}, ${shareName}, ${directoryPath}, , ${fileName}y . ${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();

Ejemplos

En las secciones siguientes se proporcionan varios fragmentos de código que abarcan algunas de las tareas más comunes del servicio de configuración, entre las que se incluyen:

Creación de un recurso compartido

Cree un recurso compartido en la cuenta de almacenamiento. Produce StorageException Si no se puede crear el recurso compartido. Tomar shareServiceClient en KeyConcept, ${shareServiceClient}.

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

Creación de una instantánea en el recurso compartido

Tomar shareServiceClient en KeyConcept, ${shareServiceClient}.

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

Creación de un directorio

Tomando shareClient inicializado anteriormente, ${shareClient}.

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

Crear un subdirectorio

Tomando directoryClient en KeyConcept, ${directoryClient}.

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

para crear un archivo

Tomando directoryClient en KeyConcept, ${directoryClient} .

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

Enumerar todos los recursos compartidos

Tomar shareServiceClient en KeyConcept, ${shareServiceClient}

shareServiceClient.listShares();

Enumeración de todos los subdirectorios y archivos

Tomando directoryClient en KeyConcept, ${directoryClient}

directoryClient.listFilesAndDirectories();

Enumeración de todos los intervalos en el archivo

Tomar fileClient en KeyConcept, ${fileClient}

fileClient.listRanges();

Eliminación de un recurso compartido

Tomar shareClient en KeyConcept, ${shareClient}

shareClient.delete();

Eliminación de un directorio

Tomando shareClient en KeyConcept, ${shareClient} .

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

Eliminación de un subdirectorio

Tomando directoryClient en KeyConcept, ${directoryClient} .

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

Eliminación de un archivo

Tomando directoryClient en KeyConcept, ${directoryClient} .

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

Copiar un archivo

Tomando fileClient en KeyConcept, ${fileClient} con una cadena de dirección URL de origen.

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

Anulación de la copia de un archivo

Tomando fileClient en KeyConcept, ${fileClient} con la respuesta de información de copia devuelta anteriormente ${copyId}=[copyInfoResponse](#copy-a-file).

fileClient.abortCopy("copyId");

Carga de datos en el almacenamiento

Tomando fileClient en KeyConcept, ${fileClient} con datos de "default" .

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

Carga de datos de más de 4 MB en el almacenamiento

Tomando fileClient en KeyConcept, ${fileClient} con datos 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);
}

Carga del archivo en el almacenamiento

Tomando fileClient en KeyConcept, ${fileClient} .

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

Descarga de datos del intervalo de archivos

Tomando fileClient en KeyConcept, ${fileClient} con el intervalo de 1024 a 2048.

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

Descarga del archivo desde el almacenamiento

Tomando fileClient en KeyConcept ${fileClient} y descárguelo en el archivo de filePath.

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

Obtención de las propiedades de un servicio de recurso compartido

Tomar shareServiceClient en KeyConcept, ${shareServiceClient} .

shareServiceClient.getProperties();

Establecimiento de las propiedades de un servicio de recurso compartido

Tomar shareServiceClient en KeyConcept, ${shareServiceClient} .

ShareServiceProperties properties = shareServiceClient.getProperties();

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

shareServiceClient.setProperties(properties);

Establecimiento de metadatos de un recurso compartido

Tomando shareClient en KeyConcept, ${shareClient} .

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

Obtención de una directiva de acceso a recursos compartidos

Tomando shareClient en KeyConcept, ${shareClient} .

shareClient.getAccessPolicy();

Establecimiento de una directiva de acceso a recursos compartidos

Tomando shareClient en 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));

Obtención de identificadores en el archivo de directorio

Tomando directoryClient en KeyConcept, ${directoryClient}

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

Forzar identificadores de cierre en identificadores de identificador

Tomar directoryClient en KeyConcept ${directoryClient} y el identificador de identificador devuelto anteriormente ${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);

Establecimiento de la cuota en el recurso compartido

Tomando shareClient en KeyConcept, ${shareClient} .

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

Establecimiento de httpheaders de archivo

Tomando fileClient en KeyConcept, ${fileClient} .

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

Solución de problemas

General

Cuando interactúa con el archivo mediante esta biblioteca cliente de Java, los errores devueltos por el servicio corresponden a los mismos códigos de estado HTTP devueltos para las solicitudes de api REST . Por ejemplo, si intenta recuperar un recurso compartido que no existe en la cuenta de almacenamiento, se devuelve un 404 error que indica Not Found.

Cliente HTTP predeterminado

Todas las bibliotecas cliente usan de forma predeterminada el cliente HTTP de Netty. Al agregar la dependencia anterior, se configurará automáticamente la biblioteca cliente para usar el cliente HTTP de Netty. La configuración o el cambio del cliente HTTP se detalla en la wiki de clientes HTTP.

Biblioteca SSL predeterminada

De forma predeterminada, todas las bibliotecas cliente usan la biblioteca Boring SSL nativa de Tomcat para habilitar el rendimiento de nivel nativo para las operaciones SSL. La biblioteca Boring SSL es un archivo uber-jar que contiene bibliotecas nativas para Linux, macOS o Windows, que proporciona un mejor rendimiento en comparación con la implementación SSL predeterminada del JDK. Para obtener más información, incluido cómo reducir el tamaño de las dependencias, consulte la sección optimización del rendimiento de la wiki.

Pasos siguientes

Contribuciones

Este proyecto agradece las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia para el colaborador (CLA) que declara que tiene el derecho a concedernos y nos concede los derechos para usar su contribución. Para más detalles, visite https://cla.microsoft.com.

Cuando se envía una solicitud de incorporación de cambios, un bot de CLA determinará de forma automática si tiene que aportar un CLA y completar la PR adecuadamente (por ejemplo, la etiqueta, el comentario). Solo siga las instrucciones que le dará el bot. Solo será necesario que lo haga una vez en todos los repositorios con nuestro CLA.

Este proyecto ha adoptado el Código de conducta de Microsoft Open Source. Para más información, consulte las preguntas más frecuentes del código de conducta o póngase en contacto con opencode@microsoft.com si tiene cualquier otra pregunta o comentario.

Para más información sobre cómo contribuir a este repositorio, consulte la guía de contribución.

  1. Bifurcarlo
  2. Creación de la rama de características (git checkout -b my-new-feature)
  3. Confirmar los cambios (git commit -am 'Add some feature')
  4. Inserción en la rama (git push origin my-new-feature)
  5. Creación de una nueva solicitud de incorporación de cambios

Impresiones