Compartir a través de

Biblioteca cliente de Recurso compartido de archivos de Azure Storage para Python, versión 12.15.0

  • Artículo

Azure File Share Storage ofrece recursos compartidos de archivos totalmente administrados en la nube a los que se puede acceder a través del protocolo estándar del sector Bloque de mensajes del servidor (SMB). Los recursos compartidos de Azure Files se pueden montar simultáneamente en implementaciones de Windows, Linux y macOS en la nube o locales. Además, los recursos compartidos de archivos de Azure Files se pueden almacenar en la caché de los servidores de Windows Server con Azure File Sync, lo que permite un acceso rápido allí donde se utilizan los datos.

Los recursos compartidos de archivos de Azure se pueden usar para:

  • Reemplazar o complementar servidores de archivos locales
  • Aplicaciones de "lift-and-shift"
  • Simplificación del desarrollo en la nube con la configuración de aplicaciones compartidas, el recurso compartido de diagnóstico y las herramientas de desarrollo, pruebas y depuración

Código | fuentePaquete (PyPI) | Paquete (Conda) | Documentación | de referencia de API | Documentación del productoMuestras

Introducción

Requisitos previos

Instalar el paquete

Instale la biblioteca cliente del recurso compartido de archivos de Azure Storage para Python con pip:

pip install azure-storage-file-share

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

# Create the storage account
az storage account create -n my-storage-account-name -g my-resource-group

Creación del cliente

La biblioteca cliente de Recursos compartidos de archivos de Azure Storage para Python permite interactuar con cuatro tipos de recursos: la propia cuenta de almacenamiento, los recursos compartidos de archivos, los directorios y los archivos. La interacción con estos recursos comienza con una instancia de un cliente. Para crear un objeto de cliente, necesitará la dirección URL del servicio de archivos de la cuenta de almacenamiento y una credencial que le permita acceder a la cuenta de almacenamiento:

from azure.storage.fileshare import ShareServiceClient

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

Búsqueda de la dirección URL de la cuenta

Puede encontrar la dirección URL del servicio de archivos de la cuenta de almacenamiento mediante Azure Portal, Azure PowerShell o la CLI de Azure:

# Get the file service URL for the storage account
az storage account show -n my-storage-account-name -g my-resource-group --query "primaryEndpoints.file"

Tipos de credenciales

El credential parámetro se puede proporcionar en varias formas diferentes, según el tipo de autorización que desee usar:

  1. Para usar un token de firma de acceso compartido (SAS), proporcione el token como una cadena. Si la dirección URL de la cuenta incluye el token de SAS, omita el parámetro de credencial. Puede generar un token de SAS desde Azure Portal en "Firma de acceso compartido" o usar una de las generate_sas() funciones para crear un token sas para la cuenta de almacenamiento, el recurso compartido o el archivo:

    from datetime import datetime, timedelta
from azure.storage.fileshare import ShareServiceClient, generate_account_sas, ResourceTypes, AccountSasPermissions

sas_token = generate_account_sas(
    account_name="<storage-account-name>",
    account_key="<account-access-key>",
    resource_types=ResourceTypes(service=True),
    permission=AccountSasPermissions(read=True),
    expiry=datetime.utcnow() + timedelta(hours=1)
)

share_service_client = ShareServiceClient(account_url="https://<my_account_name>.file.core.windows.net", credential=sas_token)

  2. Para usar una clave compartida de la cuenta de almacenamiento (también conocida como clave de cuenta o clave de acceso), proporcione la clave como una cadena. Esto se puede encontrar en Azure Portal en la sección "Claves de acceso" o mediante la ejecución del siguiente comando de la CLI de Azure:

    az storage account keys list -g MyResourceGroup -n MyStorageAccount

    Use la clave como parámetro de credencial para autenticar el cliente:

    from azure.storage.fileshare import ShareServiceClient
service = ShareServiceClient(account_url="https://<my_account_name>.file.core.windows.net", credential="<account_access_key>")

Creación del cliente a partir de un cadena de conexión

Según el caso de uso y el método de autorización, puede que prefiera inicializar una instancia de cliente con un cadena de conexión de almacenamiento en lugar de proporcionar la dirección URL de la cuenta y la credencial por separado. Para ello, pase el cadena de conexión de almacenamiento al método de clase del from_connection_string cliente:

from azure.storage.fileshare import ShareServiceClient

connection_string = "DefaultEndpointsProtocol=https;AccountName=xxxx;AccountKey=xxxx;EndpointSuffix=core.windows.net"
service = ShareServiceClient.from_connection_string(conn_str=connection_string)

La cadena de conexión a la cuenta de almacenamiento se puede encontrar en Azure Portal en la sección "Claves de acceso" o mediante la ejecución del siguiente comando de la CLI:

az storage account show-connection-string -g MyResourceGroup -n MyStorageAccount

Conceptos clave

Los siguientes componentes componen el servicio De recursos compartidos de archivos de Azure:

  • La propia cuenta de almacenamiento
  • Un recurso compartido de archivos dentro de la cuenta de almacenamiento
  • Jerarquía opcional de directorios dentro del recurso compartido de archivos
  • Un archivo dentro del recurso compartido de archivos, que puede tener un tamaño de hasta 1 TiB.

La biblioteca cliente del recurso compartido de archivos de Azure Storage para Python permite interactuar con cada uno de estos componentes mediante el uso de un objeto de cliente dedicado.

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 y credenciales asincrónicos deben cerrarse cuando ya no sean necesarios. Estos objetos son administradores de contexto asincrónicos y definen métodos asincrónicos close .

Clientes

Se proporcionan cuatro clientes diferentes para interactuar con los distintos componentes del servicio de recursos compartidos de archivos:

  1. ShareServiceClient : este cliente representa la interacción con la propia cuenta de almacenamiento de Azure y permite adquirir instancias de cliente preconfiguradas para acceder a los recursos compartidos de archivos. Proporciona operaciones para recuperar y configurar las propiedades del servicio, así como enumerar, crear y eliminar recursos compartidos dentro de la cuenta. Para realizar operaciones en un recurso compartido específico, recupere un cliente mediante el get_share_client método .
  2. ShareClient : este cliente representa la interacción con un recurso compartido de archivos específico (que aún no es necesario) y le permite adquirir instancias de cliente preconfiguradas para acceder a los directorios y archivos dentro. Proporciona operaciones para crear, eliminar, configurar o crear instantáneas de un recurso compartido e incluye operaciones para crear y enumerar el contenido de directorios dentro de él. Para realizar operaciones en un directorio o archivo específico, recupere un cliente mediante los get_directory_client métodos o get_file_client .
  3. ShareDirectoryClient : este cliente representa la interacción con un directorio específico (que aún no es necesario). Proporciona operaciones para crear, eliminar o enumerar el contenido de un subdirectorio inmediato o anidado, e incluye operaciones para crear y eliminar archivos dentro de él. Para las operaciones relacionadas con un subdirectorio o archivo específicos, también se puede recuperar un cliente para esa entidad mediante las get_subdirectory_client funciones y get_file_client .
  4. ShareFileClient : este cliente representa la interacción con un archivo específico (que aún no es necesario). Proporciona operaciones para cargar, descargar, crear, eliminar y copiar un archivo.

Para más información sobre las restricciones de nomenclatura de rutas de acceso, consulte Nomenclatura y referencia a recursos compartidos, directorios, archivos y metadatos.

Ejemplos

En las secciones siguientes se proporcionan varios fragmentos de código que abarcan algunas de las tareas más comunes del recurso compartido de archivos de almacenamiento, entre las que se incluyen:

Creación de un recurso compartido de archivos

Creación de un recurso compartido de archivos para almacenar los archivos

from azure.storage.fileshare import ShareClient

share = ShareClient.from_connection_string(conn_str="<connection_string>", share_name="myshare")
share.create_share()

Usar el cliente asincrónico para crear un recurso compartido de archivos

from azure.storage.fileshare.aio import ShareClient

share = ShareClient.from_connection_string(conn_str="<connection_string>", share_name="myshare")
await share.create_share()

Carga de un archivo

Carga de un archivo en el recurso compartido

from azure.storage.fileshare import ShareFileClient

file_client = ShareFileClient.from_connection_string(conn_str="<connection_string>", share_name="myshare", file_path="my_file")

with open("./SampleSource.txt", "rb") as source_file:
    file_client.upload_file(source_file)

Cargar un archivo de forma asincrónica

from azure.storage.fileshare.aio import ShareFileClient

file_client = ShareFileClient.from_connection_string(conn_str="<connection_string>", share_name="myshare", file_path="my_file")

with open("./SampleSource.txt", "rb") as source_file:
    await file_client.upload_file(source_file)

Descarga de un archivo

Descargar un archivo del recurso compartido

from azure.storage.fileshare import ShareFileClient

file_client = ShareFileClient.from_connection_string(conn_str="<connection_string>", share_name="myshare", file_path="my_file")

with open("DEST_FILE", "wb") as file_handle:
    data = file_client.download_file()
    data.readinto(file_handle)

Descargar un archivo de forma asincrónica

from azure.storage.fileshare.aio import ShareFileClient

file_client = ShareFileClient.from_connection_string(conn_str="<connection_string>", share_name="myshare", file_path="my_file")

with open("DEST_FILE", "wb") as file_handle:
    data = await file_client.download_file()
    await data.readinto(file_handle)

Enumeración del contenido de un directorio

Enumeración de todos los directorios y archivos en un directorio primario

from azure.storage.fileshare import ShareDirectoryClient

parent_dir = ShareDirectoryClient.from_connection_string(conn_str="<connection_string>", share_name="myshare", directory_path="parent_dir")

my_list = list(parent_dir.list_directories_and_files())
print(my_list)

Enumerar el contenido de un directorio de forma asincrónica

from azure.storage.fileshare.aio import ShareDirectoryClient

parent_dir = ShareDirectoryClient.from_connection_string(conn_str="<connection_string>", share_name="myshare", directory_path="parent_dir")

my_files = []
async for item in parent_dir.list_directories_and_files():
    my_files.append(item)
print(my_files)

Configuración opcional

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

Configuración de directiva de reintento

Use los argumentos de palabra clave siguientes al crear instancias 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 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 a 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/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): el número de segundos que el cliente esperará para establecer una conexión con el servidor. El valor predeterminado es 20 segundos.
  • read_timeout (int): el número de segundos que el cliente esperará, entre operaciones de lectura consecutivas, para obtener una respuesta del servidor. Se trata de un tiempo de espera de nivel de socket y no se ve afectado por el tamaño general 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 storage File 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.fileshare import ShareServiceClient

# Create a logger for the 'azure.storage.fileshare' SDK
logger = logging.getLogger('azure.storage.fileshare')
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 = ShareServiceClient.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.get_service_properties(logging_enable=True)

Pasos siguientes

Más código de ejemplo

Empiece a trabajar con nuestros ejemplos de recursos compartidos de archivos.

Hay varios ejemplos del SDK de Python del recurso compartido de archivos de almacenamiento 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 el recurso compartido de archivos de almacenamiento:

  • file_samples_hello_world.py (versión asincrónica): ejemplos que se encuentran en este artículo:

    • Creación de clientes
    • Creación de un recurso compartido de archivos
    • Cargar un archivo

  • file_samples_authentication.py (versión asincrónica): ejemplos para autenticar y crear el cliente:

    • Desde un cadena de conexión
    • Desde una clave de acceso compartido
    • Desde un token de firma de acceso compartido

  • file_samples_service.py (versión asincrónica): ejemplos para interactuar con el servicio de archivos:

    • Obtención y establecimiento de las propiedades del servicio
    • Crear, enumerar y eliminar recursos compartidos
    • Obtención de un cliente compartido

  • file_samples_share.py (versión asincrónica): ejemplos para interactuar con recursos compartidos de archivos:

    • Creación de una instantánea de recurso compartido
    • Establecimiento de la cuota de recursos compartidos y los metadatos
    • Enumerar directorios y archivos
    • Obtener el directorio o el cliente de archivos para interactuar con una entidad específica

  • file_samples_directory.py (versión asincrónica): ejemplos para interactuar con directorios:

    • Creación de un directorio y adición de archivos
    • Creación y eliminación de subdirectorios
    • Obtención del cliente del subdirectorio

  • file_samples_client.py (versión asincrónica): ejemplos para interactuar con archivos:

    • Crear, cargar, descargar y eliminar archivos
    • Copia de un archivo desde una dirección URL

Documentación adicional

Para más información sobre el almacenamiento de recursos compartidos de archivos de Azure, consulte la documentación de Almacenamiento de recursos compartidos de archivos de Azure en 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.