Biblioteca cliente del servicio Azure DataLake para Python: versión 12.14.0

Artículo
11/08/2023

Información general

Este paquete de versión preliminar para Python incluye compatibilidad específica con la API de ADLS Gen2 disponible en el SDK de Storage. Esto incluye:

Nuevas operaciones de nivel de directorio (Crear, Cambiar nombre, Eliminar) para la cuenta de almacenamiento del espacio de nombres jerárquico habilitado (HNS). En el caso de las cuentas habilitadas para HNS, las operaciones de cambio de nombre y movimiento son atómicas.
Operaciones relacionadas con permisos (ACL Get/Set) para cuentas jerárquicas habilitadas para el espacio de nombres (HNS).

Introducción

Requisitos previos

Se requiere Python 3.7 o posterior para usar este paquete. Para más información, lea nuestra página sobre la directiva de compatibilidad con versiones de Azure SDK para Python.
Debe tener una suscripción de Azure y una cuenta de almacenamiento de Azure para usar este paquete.

Instalar el paquete

Instale la biblioteca cliente de Azure DataLake Storage para Python con pip:

pip install azure-storage-file-datalake --pre

Crear una cuenta de almacenamiento

Si desea crear una cuenta de almacenamiento, puede usar Azure Portal, Azure PowerShell o la CLI de Azure:

# Create a new resource group to hold the storage account -
# if using an existing resource group, skip this step
az group create --name my-resource-group --location westus2

# Install the extension 'Storage-Preview'
az extension add --name storage-preview

# Create the storage account
az storage account create --name my-storage-account-name --resource-group my-resource-group --sku Standard_LRS --kind StorageV2 --hierarchical-namespace true

Autenticar el cliente

La interacción con DataLake Storage comienza con una instancia de la clase DataLakeServiceClient. Necesita una cuenta de almacenamiento existente, su dirección URL y una credencial para crear una instancia del objeto de cliente.

Obtener credenciales

Para autenticar el cliente, tiene algunas opciones:

Uso de una cadena de token de SAS
Uso de una clave de acceso compartido de cuenta
Uso de una credencial de token de azure.identity

Como alternativa, puede autenticarse con un cadena de conexión de almacenamiento mediante el from_connection_string método . Vea ejemplo: Creación de clientes con un cadena de conexión.

Puede omitir la credencial si la dirección URL de la cuenta ya tiene un token de SAS.

Crear el cliente

Una vez que tenga lista la dirección URL y las credenciales de la cuenta, puede crear DataLakeServiceClient:

from azure.storage.filedatalake import DataLakeServiceClient

service = DataLakeServiceClient(account_url="https://<my-storage-account-name>.dfs.core.windows.net/", credential=credential)

Conceptos clave

DataLake Storage ofrece cuatro tipos de recursos:

La cuenta de almacenamiento
Un sistema de archivos en la cuenta de almacenamiento
Un directorio en el sistema de archivos
Un archivo en un sistema de archivos o en el directorio

Clientes asincrónicos

Esta biblioteca incluye una API asincrónica completa compatible con Python 3.5 y versiones posteriores. Para usarlo, primero debe instalar un transporte asincrónico, como aiohttp. Consulte la documentación de azure-core para más información.

Los clientes asincrónicos y las credenciales deben cerrarse cuando ya no sean necesarios. Estos objetos son administradores de contexto asincrónicos y definen métodos asincrónicos close .

Clientes

El SDK de DataLake Storage proporciona cuatro clientes diferentes para interactuar con el servicio DataLake:

DataLakeServiceClient : este cliente interactúa con el servicio DataLake en el nivel de cuenta. Proporciona operaciones para recuperar y configurar las propiedades de la cuenta, así como para enumerar, crear y eliminar sistemas de archivos dentro de la cuenta. En el caso de las operaciones relacionadas con un sistema de archivos específico, directorio o archivo, los clientes de esas entidades también se pueden recuperar mediante las get_file_clientfunciones , get_directory_client o get_file_system_client .
FileSystemClient : este cliente representa la interacción con un sistema de archivos específico, incluso si ese sistema de archivos aún no existe. Proporciona operaciones para crear, eliminar o configurar sistemas de archivos e incluye operaciones para enumerar rutas de acceso en el sistema de archivos, cargar y eliminar archivos o directorios en el sistema de archivos. Para las operaciones relacionadas con un archivo específico, el cliente también se puede recuperar mediante la get_file_client función . Para las operaciones relacionadas con un directorio específico, el cliente se puede recuperar mediante la get_directory_client función .
DataLakeDirectoryClient : este cliente representa la interacción con un directorio específico, incluso si ese directorio aún no existe. Proporciona operaciones de directorio para crear, eliminar, cambiar el nombre, obtener propiedades y establecer operaciones de propiedades.
DataLakeFileClient : este cliente representa la interacción con un archivo específico, incluso si ese archivo aún no existe. Proporciona operaciones de archivo para anexar datos, vaciar datos, eliminar, crear y leer archivos.
DataLakeLeaseClient : este cliente representa interacciones de concesión con un FileSystemClient, DataLakeDirectoryClient o DataLakeFileClient. Proporciona operaciones para adquirir, renovar, liberar, cambiar y interrumpir concesiones en los recursos.

Ejemplos

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

Creación de cliente con un cadena de conexión
Carga de un archivo
Descarga de un archivo
Enumeración de rutas de acceso

Creación de cliente con un cadena de conexión

Cree DataLakeServiceClient mediante el cadena de conexión a la cuenta de Azure Storage.

from azure.storage.filedatalake import DataLakeServiceClient

service = DataLakeServiceClient.from_connection_string(conn_str="my_connection_string")

Carga de un archivo

Cargue un archivo en el sistema de archivos.

from azure.storage.filedatalake import DataLakeFileClient

data = b"abc"
file = DataLakeFileClient.from_connection_string("my_connection_string",
                                                 file_system_name="myfilesystem", file_path="myfile")
file.create_file ()
file.append_data(data, offset=0, length=len(data))
file.flush_data(len(data))

Descarga de un archivo

Descargue un archivo del sistema de archivos.

from azure.storage.filedatalake import DataLakeFileClient

file = DataLakeFileClient.from_connection_string("my_connection_string",
                                                 file_system_name="myfilesystem", file_path="myfile")

with open("./BlockDestination.txt", "wb") as my_file:
    download = file.download_file()
    download.readinto(my_file)

Enumeración de rutas de acceso

Enumere las rutas de acceso del sistema de archivos.

from azure.storage.filedatalake import FileSystemClient

file_system = FileSystemClient.from_connection_string("my_connection_string", file_system_name="myfilesystem")

paths = file_system.get_paths()
for path in paths:
    print(path.name + '\n')

Configuración opcional

Argumentos de palabra clave opcionales que se pueden pasar en el cliente y en el nivel de operación.

Configuración de la directiva de reintento

Use los argumentos de palabra clave siguientes al crear una instancia de un cliente para configurar la directiva de reintento:

retry_total (int): número total de reintentos que se van a permitir. Tiene prioridad sobre otros recuentos. retry_total=0 Pase si no desea volver a intentarlo en las solicitudes. El valor predeterminado es 10.
retry_connect (int): cuántos errores relacionados con la conexión se reintentan. El valor predeterminado es 3.
retry_read (int): cuántas veces se reintenta en los errores de lectura. El valor predeterminado es 3.
retry_status (int): cuántas veces se reintenta en códigos de estado incorrectos. El valor predeterminado es 3.
retry_to_secondary (bool): indica si la solicitud se debe reintentar en la secundaria, si es posible. Esto solo debe habilitarse en las cuentas de RA-GRS y se pueden controlar los datos potencialmente obsoletos. Tiene como valor predeterminado False.

Otra configuración de cliente o por operación

Otros argumentos de palabra clave de configuración opcionales que se pueden especificar en el cliente o por operación.

Argumentos de palabra clave de cliente:

connection_timeout (int): número de segundos que el cliente esperará para establecer una conexión con el servidor. El valor predeterminado es de 20 segundos.
read_timeout (int): número de segundos que el cliente esperará, entre operaciones de lectura consecutivas, para una respuesta del servidor. Se trata de un tiempo de espera de nivel de socket y no se ve afectado por el tamaño total de los datos. Los tiempos de espera de lectura del lado cliente se reintentarán automáticamente. El valor predeterminado es 60 segundos.
transport (Any): transporte proporcionado por el usuario para enviar la solicitud HTTP.

Argumentos de palabra clave por operación:

raw_response_hook (invocable): la devolución de llamada especificada usa la respuesta devuelta por el servicio.
raw_request_hook (invocable): la devolución de llamada especificada usa la solicitud antes de enviarse al servicio.
client_request_id (str): identificación especificada por el usuario opcional de la solicitud.
user_agent (str): anexa el valor personalizado al encabezado user-agent que se enviará con la solicitud.
logging_enable (bool): habilita el registro en el nivel DEBUG. El valor predeterminado es False. También se puede pasar en el nivel de cliente para habilitarlo para todas las solicitudes.
logging_body (bool): habilita el registro de la solicitud y el cuerpo de la respuesta. El valor predeterminado es False. También se puede pasar en el nivel de cliente para habilitarlo para todas las solicitudes.
encabezados (dict): pase encabezados personalizados como pares clave-valor. Por ejemplo headers={'CustomValue': value}

Solución de problemas

General

Los clientes de DataLake Storage generan excepciones definidas en Azure Core.

Esta lista se puede usar como referencia para detectar excepciones producidas. Para obtener el código de error específico de la excepción, use el error_code atributo , es decir, exception.error_code.

Registro

Esta biblioteca usa la biblioteca de registro estándar para el registro. La información básica sobre las sesiones HTTP (direcciones URL, encabezados, etc.) se registra en el nivel INFO.

El registro detallado de nivel de DEPURACIÓN, incluidos los cuerpos de solicitud/respuesta y los encabezados no aprobados, se puede habilitar en un cliente con el logging_enable argumento :

import sys
import logging
from azure.storage.filedatalake import DataLakeServiceClient

# Create a logger for the 'azure.storage.filedatalake' SDK
logger = logging.getLogger('azure.storage')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

# This client will log detailed information about its HTTP sessions, at DEBUG level
service_client = DataLakeServiceClient.from_connection_string("your_connection_string", logging_enable=True)

Igualmente, logging_enable puede habilitar el registro detallado de una sola operación, aunque no esté habilitado para el cliente:

service_client.list_file_systems(logging_enable=True)

Pasos siguientes

Más código de ejemplo

Introducción a nuestros ejemplos de Azure DataLake.

Hay varios ejemplos del SDK de Python de DataLake Storage disponibles en el repositorio de GitHub del SDK. Estos ejemplos proporcionan código de ejemplo para escenarios adicionales que se suelen encontrar al trabajar con DataLake Storage:

datalake_samples_access_control.py - Ejemplos de tareas comunes de DataLake Storage:
- Configuración de un sistema de archivos
- Creación de un directorio
- Establecimiento y obtención del control de acceso para el directorio
- Creación de archivos en el directorio
- Establecer o obtener control de acceso para cada archivo
- Eliminación de un sistema de archivos
datalake_samples_upload_download.py - Ejemplos de tareas comunes de DataLake Storage:
- Configuración de un sistema de archivos
- Crear archivo
- Anexar datos al archivo
- Vaciado de datos en el archivo
- Descarga de los datos cargados
- Eliminación de un sistema de archivos

Documentación adicional

Tabla para ADLS Gen1 a ADLS Gen2 API Mapping (Asignación de API de ADLS Gen2) Para obtener documentación de REST más amplia sobre Data Lake Storage Gen2, consulte la documentación de Data Lake Storage Gen2 sobre docs.microsoft.com.

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.

Compartir a través de