Biblioteca cliente de Azure File Data Lake para Java, versión 12.17.1

  • Artículo

Azure Data Lake Storage es la solución de almacenamiento optimizada de Microsoft para cargas de trabajo de análisis de macrodatos. Parte fundamental de Data Lake Storage Gen2 es la incorporación de un espacio de nombres jerárquico en Blob Storage. El espacio de nombres jerárquico organiza los objetos o archivos en una jerarquía de directorios para un acceso eficaz a los datos.

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

Introducción

Requisitos previos

Inclusión del paquete

Inclusión del archivo BOM

Incluya azure-sdk-bom en el proyecto para que dependa 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-datalake</artifactId>
  </dependency>
</dependencies>

Inclusión de dependencias directas

Si desea 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-datalake</artifactId>
    <version>12.17.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. Nota: Para usar data lake, la cuenta debe tener habilitado el espacio de nombres jerárquico.

# 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

La dirección URL de la cuenta de almacenamiento, identificada posteriormente como <your-storage-account-url>, tendría el formato siguiente: http(s)://<storage-account-name>.dfs.core.windows.net

Autenticar el cliente

Para interactuar con el servicio de almacenamiento, 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

Obtener credenciales

Token de SAS

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

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}

Ejemplo:

CONNECTION_STRING=<connection-string>

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

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

  1. Vaya a la cuenta de almacenamiento.
  2. Seleccione Shared access signature en el menú de la izquierda.
  3. Haga clic en Generate SAS and connection string (después de la instalación)
Credencial de clave compartida

a. Use nombre de cuenta y clave de cuenta. El nombre de la cuenta es el nombre de la cuenta de almacenamiento.

  1. Vaya a la cuenta de almacenamiento.
  2. Seleccione Access keys en el menú de la izquierda.
  3. En key1/key2 Copiar el contenido del Key campo

o

b. Use el cadena de conexión.

  1. Vaya a la cuenta de almacenamiento.
  2. Seleccione Access keys en el menú de la izquierda.
  3. En key1/key2 Copiar el contenido del Connection string campo

Conceptos clave

DataLake Storage Gen2 se diseñó para:

  • Servicio de varios petabytes de información mientras mantiene cientos de gigabits de rendimiento
  • Le permite administrar fácilmente grandes cantidades de datos.

Entre las características clave de DataLake Storage Gen2 se incluyen las siguientes:

  • Acceso compatible con Hadoop
  • Superconjunto de permisos POSIX
  • Rentable en términos de capacidad de almacenamiento y transacciones de bajo costo
  • Controlador optimizado para análisis de macrodatos

Parte fundamental de Data Lake Storage Gen2 es la incorporación de un espacio de nombres jerárquico en Blob Storage. El espacio de nombres jerárquico organiza los objetos o archivos en una jerarquía de directorios para un acceso eficaz a los datos.

Anteriormente, los análisis basados en la nube tenían que llegar a un acuerdo en materia de rendimiento, administración y seguridad. Data Lake Storage Gen2 aborda cada uno de estos aspectos de las siguientes formas:

  • El rendimiento se optimiza porque no es necesario copiar ni transformar datos como requisito previo para el análisis. El espacio de nombres jerárquico mejora considerablemente el rendimiento de las operaciones de administración de directorios y, consecuentemente, el rendimiento general del trabajo.
  • La administración es más fácil, ya que puede organizar y manipular archivos a través de directorios y subdirectorios.
  • La seguridad se aplicable porque se pueden definir permisos POSIX en los directorios o archivos individuales.
  • La rentabilidad se hace posible gracias a que Data Lake Storage Gen2 se ha diseñado a partir de Azure Blob Storage de bajo costo. Las características adicionales reducen aún más el costo total de propiedad para la ejecución de análisis de macrodatos en Azure.

Data Lake Storage Gen2 ofrece dos tipos de recursos:

  • _filesystem utilizado a través de "DataLakeFileSystemClient"
  • _path utilizado a través de "DataLakeFileClient" o "DataLakeDirectoryClient"
ADLS Gen2 Blob
Sistema de archivos Contenedor
Ruta de acceso (archivo o directorio) Blob

Nota: Esta biblioteca cliente no admite cuentas de almacenamiento deshabilitadas del espacio de nombres jerárquico (HNS).

Formato de dirección URL

Las rutas de acceso son direccionables con el siguiente formato de dirección URL: La siguiente dirección URL direcciona un archivo:

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

Sintaxis del URI de recurso

Para la cuenta de almacenamiento, el URI base para las operaciones de datalake incluye el nombre de la cuenta solo:

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

Para un sistema de archivos, el URI base incluye el nombre de la cuenta y el nombre del sistema de archivos:

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

Para un archivo o directorio, el URI base incluye el nombre de la cuenta, el nombre del sistema de archivos y el nombre de la ruta de acceso:

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

Tenga en cuenta que es posible que los URI anteriores no contengan escenarios más avanzados, como nombres de dominio personalizados.

Ejemplos

En las secciones siguientes se proporcionan varios fragmentos de código que abarcan algunas de las tareas más comunes de Azure Storage Blob, entre las que se incluyen:

Creación de una clase DataLakeServiceClient

Cree un DataLakeServiceClient con el sasToken elemento generado anteriormente.

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

o

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

Creación de una clase DataLakeFileSystemClient

Cree un DataLakeFileSystemClient objeto mediante .DataLakeServiceClient

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

o

Cree un DataLakeFileSystemClient objeto a partir del generador sasToken generado anteriormente.

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

o

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

Creación de una clase DataLakeFileClient

Cree un DataLakeFileClient objeto mediante .DataLakeFileSystemClient

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

o

Cree un FileClient objeto a partir del generador sasToken generado anteriormente.

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

o

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

Creación de una clase DataLakeDirectoryClient

Obtiene un DataLakeDirectoryClient objeto mediante un DataLakeFileSystemClientobjeto .

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

o

Cree un DirectoryClient objeto a partir del generador sasToken generado anteriormente.

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

o

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

Creación de un sistema de archivos

Cree un sistema de archivos mediante .DataLakeServiceClient

dataLakeServiceClient.createFileSystem("myfilesystem");

o

Cree un sistema de archivos mediante .DataLakeFileSystemClient

dataLakeFileSystemClient.create();

Enumerar rutas de acceso

Enumerar todas las rutas de acceso mediante .DataLakeFileSystemClient

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

Cambiar el nombre de un archivo

Cambie el nombre de un archivo mediante .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");

Cambiar el nombre de un directorio

Cambie el nombre de un directorio mediante .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");

Obtener las propiedades de archivos

Obtener propiedades de un archivo mediante .DataLakeFileClient

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

Obtención de propiedades de directorio

Obtenga las propiedades de un directorio mediante .DataLakeDirectoryClient

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

Autenticación con la identidad de Azure

La biblioteca de identidades de Azure proporciona compatibilidad con Azure Active Directory para la autenticación con Azure Storage.

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

Solución de problemas

Al interactuar con data lake 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 sistema de archivos o una ruta de acceso 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

Hay varios ejemplos del SDK de Java de Storage datalake disponibles en el repositorio de GitHub del SDK.

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.

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.

Impresiones