Share via

ShareFileClient Clase

  • Referencia

Un cliente para interactuar con un archivo específico, aunque es posible que ese archivo aún no exista.

Para obtener más configuración opcional, haga clic aquí.

Herencia
azure.storage.fileshare._shared.base_client.StorageAccountHostsMixin
ShareFileClient

Constructor

ShareFileClient(account_url: str, share_name: str, file_path: str, snapshot: str | Dict[str, Any] | None = None, credential: str | Dict[str, str] | AzureNamedKeyCredential | AzureSasCredential | TokenCredential | None = None, *, token_intent: Literal['backup'] | None = None, **kwargs: Any)

Parámetros

account_url
str
Requerido

Identificador URI de la cuenta de almacenamiento. Para crear un cliente dado el URI completo al archivo, use la from_file_url clasemethod.

share_name
str
Requerido

Nombre del recurso compartido del archivo.

file_path
str
Requerido

Ruta de acceso del archivo al archivo con el que se va a interactuar. Si se especifica, este valor invalidará un valor de archivo especificado en la dirección URL del archivo.

snapshot
str
valor predeterminado: None

Instantánea de archivo opcional en la que se va a operar. Puede ser la cadena de identificador de instantánea o la respuesta devuelta desde create_snapshot.

credential
valor predeterminado: None

Credenciales con las que se va a autenticar. Esto es opcional si la dirección URL de la cuenta ya tiene un token de SAS. El valor puede ser una cadena de token de SAS, una instancia de AzureSasCredential o AzureNamedKeyCredential de azure.core.credentials, una clave de acceso compartido de cuenta o una instancia de una clase TokenCredentials de azure.identity. Si el URI del recurso ya contiene un token de SAS, se omitirá en favor de una credencial explícita.

  • excepto en el caso de AzureSasCredential, donde los tokens de SAS en conflicto generarán un valor ValueError. Si usa una instancia de AzureNamedKeyCredential, "name" debe ser el nombre de la cuenta de almacenamiento y "key" debe ser la clave de la cuenta de almacenamiento.
token_intent
Literal['backup']

Necesario cuando se usa TokenCredential para la autenticación y se omite para otras formas de autenticación. Especifica la intención de todas las solicitudes al usar la autenticación TokenCredential . Los valores posibles son:

backup: especifica que las solicitudes están pensadas para 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 también debe tener el permiso RBAC necesario.

allow_trailing_dot
bool

Si es true, el punto final no se recortará del URI de destino.

allow_source_trailing_dot
bool

Si es true, el punto final no se recortará del URI de origen.

api_version
str

La versión de la API de storage que se va a usar para las solicitudes. El valor predeterminado es la versión de servicio más reciente que es compatible con el SDK actual. Establecer en una versión anterior puede dar lugar a una compatibilidad de características reducida.

Novedades de la versión 12.1.0.

secondary_hostname
str

El nombre de host del punto de conexión secundario.

max_range_size
int

Tamaño máximo del intervalo usado para una carga de archivos. El valor predeterminado es 4*1024*1024.

audience
str

Audiencia que se va a usar al solicitar tokens para la autenticación de Azure Active Directory. Solo tiene un efecto cuando la credencial es de tipo TokenCredential. El valor podría ser https://storage.azure.com/ (valor predeterminado) o https://.file.core.windows.net.

Métodos

abort_copy

Anule una operación de copia en curso.

Esto dejará un archivo de destino con longitud cero y metadatos completos. Esto generará un error si la operación de copia ya ha finalizado.
acquire_lease

Solicita una nueva concesión.

Si el archivo no tiene una concesión activa, el servicio de archivos crea una concesión en el blob y devuelve una nueva concesión.
clear_range

Borra el intervalo especificado y libera el espacio usado en el almacenamiento de ese intervalo.
close

Este método consiste en cerrar los sockets abiertos por el cliente. No es necesario usarse cuando se usa con un administrador de contextos.
close_all_handles

Cierre los identificadores de archivo abiertos.

Esta operación se bloqueará hasta que el servicio haya cerrado todos los identificadores abiertos.
close_handle

Cierre un identificador de archivo abierto.
create_file

Crea un nuevo archivo.

Tenga en cuenta que solo inicializa el archivo sin contenido.
delete_file

Marca el archivo especificado para su eliminación. El archivo se elimina posteriormente durante la recolección de elementos no utilizados.
download_file

Descarga un archivo en StorageStreamDownloader. El método readall() se debe usar para leer todo el contenido o readinto() debe usarse para descargar el archivo en una secuencia. El uso de chunks() devuelve un iterador que permite al usuario iterar el contenido en fragmentos.
from_connection_string

Cree ShareFileClient a partir de una cadena de conexión.
from_file_url

Un cliente para interactuar con un archivo específico, aunque es posible que ese archivo aún no exista.
get_file_properties

Devuelve todos los metadatos definidos por el usuario, las propiedades HTTP estándar y las propiedades del sistema para el archivo.
get_ranges

Devuelve la lista de intervalos de páginas válidos para un archivo o una instantánea de un archivo.
get_ranges_diff

Devuelve la lista de intervalos de páginas válidos para un archivo o una instantánea de un archivo.

Novedad de la versión 12.6.0.
list_handles

Enumera los identificadores del archivo.
rename_file

Cambie el nombre del archivo de origen.

:p aramtype file_attributes:~azure.storage.fileshare.NTFSAttributes o str :keyword file_creation_time:

Hora de creación del archivo.

:p aramtype file_creation_time:~datetime.datetime o str :keyword file_last_write_time:

Hora de última escritura del archivo.

:p aramtype file_last_write_time:~datetime.datetime o str :keyword file_change_time:

Cambiar la hora del archivo. Si no se especifica, la hora de cambio se establecerá en la fecha y hora actuales.

Novedad de la versión 12.8.0: este parámetro se introdujo en la versión de API "2021-06-08".
resize_file

Cambia el tamaño de un archivo al tamaño especificado.
set_file_metadata

Establece los metadatos definidos por el usuario para el archivo especificado como uno o varios pares nombre-valor.

Cada llamada a esta operación reemplaza todos los metadatos existentes adjuntados al archivo. Para quitar todos los metadatos del archivo, llame a esta operación sin dict de metadatos.
set_http_headers

Establece encabezados HTTP en el archivo.
start_copy_from_url

Inicia la copia de datos de una dirección URL de origen en el archivo al que hace referencia el cliente.

El estado de esta operación de copia se puede encontrar mediante el método get_properties .
upload_file

Carga un nuevo archivo.

datos param: contenido del archivo.

param int length: longitud del archivo en bytes. Especifique su tamaño máximo, hasta 1 TiB.

param file_attributes: los atributos del sistema de archivos para archivos y directorios. Si no se establece, el valor predeterminado sería "None" y los atributos se establecerán en "Archive". Este es un ejemplo para cuando el tipo var es str: 'Temporal|Archive'. file_attributes valor no distingue mayúsculas de minúsculas.

type file_attributes: str o ~azure.storage.fileshare.NTFSAttributes

param file_creation_time: Hora de creación del archivo Valor predeterminado: Ahora.

type file_creation_time: str o ~datetime.datetime

param file_last_write_time: hora de última escritura del archivo Valor predeterminado: Ahora.

type file_last_write_time: str o ~datetime.datetime

param file_permission: si se especifica el permiso (descriptor de seguridad) se establecerá para el directorio o archivo. Este encabezado se puede usar si el tamaño del permiso es <= 8 KB; de lo contrario, se usará el encabezado x-ms-file-permission-key. Valor predeterminado: Heredar. Si SDDL se especifica como entrada, debe tener propietario, grupo y dacl. Nota: Solo se debe especificar una de las claves x-ms-file-permission o x-ms-file-permission-key.

type file_permission: str

param permission_key: clave del permiso que se va a establecer para el directorio o archivo. Nota: Solo se debe especificar una de las claves x-ms-file-permission o x-ms-file-permission-key.

type permission_key: str
upload_range

Cargue un intervalo de bytes en un archivo.
upload_range_from_url

Escribe los bytes de un punto de conexión de Azure File en el intervalo especificado de otro punto de conexión de Azure File.

abort_copy

Anule una operación de copia en curso.

Esto dejará un archivo de destino con longitud cero y metadatos completos. Esto generará un error si la operación de copia ya ha finalizado.

abort_copy(copy_id: str | FileProperties, **kwargs: Any) -> None

Parámetros

copy_id
str o FileProperties
Requerido

Operación de copia que se va a anular. Puede ser un identificador o una instancia de FileProperties.

lease
ShareLeaseClient o str

Requerido si el archivo tiene una concesión activa. El valor puede ser un objeto ShareLeaseClient o el identificador de concesión como una cadena.

Novedades de la versión 12.1.0.

timeout
int

Establece el tiempo de espera del lado servidor para la operación en segundos. Para más información, consulte https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations. Este valor no se realiza un seguimiento ni se valida en el cliente. Para configurar tiempos de espera de red del lado cliente, consulte aquí.

Tipo de valor devuelto

None

acquire_lease

Solicita una nueva concesión.

Si el archivo no tiene una concesión activa, el servicio de archivos crea una concesión en el blob y devuelve una nueva concesión.

acquire_lease(lease_id: str | None = None, **kwargs: Any) -> ShareLeaseClient

Parámetros

lease_id
str
Requerido

Identificador de concesión propuesto, con formato de cadena de GUID. El servicio de archivos devuelve 400 (solicitud no válida) si el identificador de concesión propuesto no tiene el formato correcto.

timeout
int

Establece el tiempo de espera del lado servidor para la operación en segundos. Para más información, consulte https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations. Este valor no se realiza un seguimiento ni se valida en el cliente. Para configurar tiempos de espera de red del lado cliente, consulte aquí.

Devoluciones

Objeto ShareLeaseClient.

Tipo de valor devuelto

ShareLeaseClient

Ejemplos

Adquirir una concesión en un archivo.


   source_file.create_file(1024)
   lease = source_file.acquire_lease()
   source_file.upload_file(b'hello world', lease=lease)

   lease.release()

clear_range

Borra el intervalo especificado y libera el espacio usado en el almacenamiento de ese intervalo.

clear_range(offset: int, length: int, **kwargs) -> Dict[str, Any]

Parámetros

offset
int
Requerido

Inicio del intervalo de bytes que se va a usar para borrar una sección del archivo. El intervalo puede tener un tamaño de hasta 4 MB.

length
int
Requerido

Número de bytes que se usarán para borrar una sección del archivo. El intervalo puede tener un tamaño de hasta 4 MB.

lease
ShareLeaseClient o str

Requerido si el archivo tiene una concesión activa. El valor puede ser un objeto ShareLeaseClient o el identificador de concesión como una cadena.

Novedades de la versión 12.1.0.

timeout
int

Establece el tiempo de espera del lado servidor para la operación en segundos. Para más información, consulte https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations. Este valor no se realiza un seguimiento ni se valida en el cliente. Para configurar tiempos de espera de red del lado cliente, consulte aquí.

Devoluciones

Dict de propiedad actualizada por archivo (Etag y última modificación).

Tipo de valor devuelto

Dict[str, Any]

close

Este método consiste en cerrar los sockets abiertos por el cliente. No es necesario usarse cuando se usa con un administrador de contextos.

close()

close_all_handles

Cierre los identificadores de archivo abiertos.

Esta operación se bloqueará hasta que el servicio haya cerrado todos los identificadores abiertos.

close_all_handles(**kwargs: Any) -> Dict[str, int]

Parámetros

timeout
int

Establece el tiempo de espera del lado servidor para la operación en segundos. Para más información, consulte https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations. Este valor no se realiza un seguimiento ni se valida en el cliente. Para configurar tiempos de espera de red del lado cliente, consulte aquí.

Devoluciones

Número de identificadores cerrados (puede ser 0 si no se encontró el identificador especificado) y el número de identificadores no se pudo cerrar en un dict.

Tipo de valor devuelto

dict[str, int]

close_handle

Cierre un identificador de archivo abierto.

close_handle(handle: str | Handle, **kwargs: Any) -> Dict[str, int]

Parámetros

handle
str o Handle
Requerido

Identificador específico que se va a cerrar.

timeout
int

Establece el tiempo de espera del lado servidor para la operación en segundos. Para más información, consulte https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations. Este valor no se realiza un seguimiento ni se valida en el cliente. Para configurar tiempos de espera de red del lado cliente, consulte aquí.

Devoluciones

Número de identificadores cerrados (puede ser 0 si no se encontró el identificador especificado) y el número de identificadores no se pudo cerrar en un dict.

Tipo de valor devuelto

dict[str, int]

create_file

Crea un nuevo archivo.

Tenga en cuenta que solo inicializa el archivo sin contenido.

create_file(size: int, file_attributes: str | NTFSAttributes = 'none', file_creation_time: str | datetime | None = 'now', file_last_write_time: str | datetime | None = 'now', file_permission: str | None = None, permission_key: str | None = None, **kwargs: Any) -> Dict[str, Any]

Parámetros

size
int
Requerido

Especifica el tamaño máximo del archivo, hasta 1 TB.

file_attributes
NTFSAttributes
Requerido

Atributos del sistema de archivos para archivos y directorios. Si no se establece, el valor predeterminado sería "None" y los atributos se establecerán en "Archive". Este es un ejemplo de cuándo el tipo var es str: 'Temporary|Archive'. file_attributes valor no distingue mayúsculas de minúsculas.

file_creation_time
str o datetime
Requerido

Hora de creación del archivo Valor predeterminado: Ahora.

file_last_write_time
str o datetime
Requerido

Hora de última escritura para el valor predeterminado del archivo: Ahora.

file_permission
str
Requerido

Si se especifica el permiso (descriptor de seguridad) se establecerá para el directorio o archivo. Este encabezado se puede usar si el tamaño del permiso es <= 8 KB; de lo contrario, se usará el encabezado x-ms-file-permission-key. Valor predeterminado: Heredar. Si SDDL se especifica como entrada, debe tener propietario, grupo y dacl. Nota: Solo se debe especificar una de las claves x-ms-file-permission o x-ms-file-permission-key.

permission_key
str
Requerido

Clave del permiso que se va a establecer para el directorio o archivo. Nota: Solo se debe especificar una de las claves x-ms-file-permission o x-ms-file-permission-key.

file_change_time
str o datetime

Cambiar la hora del archivo. Si no se especifica, la hora de cambio se establecerá en la fecha y hora actuales.

Novedad de la versión 12.8.0: este parámetro se introdujo en la versión de API "2021-06-08".

content_settings
ContentSettings

Objeto ContentSettings usado para establecer propiedades de archivo. Se usa para establecer el tipo de contenido, la codificación, el idioma, la disposición, md5 y el control de caché.

metadata
dict(str,str)

Pares nombre-valor asociados al archivo como metadatos.

lease
ShareLeaseClient o str

Obligatorio si el archivo tiene una concesión activa. El valor puede ser un objeto ShareLeaseClient o el identificador de concesión como una cadena.

Novedad de la versión 12.1.0.

timeout
int

Establece el tiempo de espera del lado servidor para la operación en segundos. Para más información, consulte https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations. Este valor no se realiza ni se valida en el cliente. Para configurar los tiempos de espera de red del lado cliente, consulte aquí.

Devoluciones

Dict de propiedad actualizada por archivo (Etag y última modificación).

Tipo de valor devuelto

dict(str, Any)

Ejemplos

Cree un archivo.


   # Create and allocate bytes for the file (no content added yet)
   my_allocated_file.create_file(size=100)

delete_file

Marca el archivo especificado para su eliminación. El archivo se elimina posteriormente durante la recolección de elementos no utilizados.

delete_file(**kwargs: Any) -> None

Parámetros

lease
ShareLeaseClient o str

Obligatorio si el archivo tiene una concesión activa. El valor puede ser un objeto ShareLeaseClient o el identificador de concesión como una cadena.

Novedad de la versión 12.1.0.

timeout
int

Establece el tiempo de espera del lado servidor para la operación en segundos. Para más información, consulte https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations. Este valor no se realiza ni se valida en el cliente. Para configurar los tiempos de espera de red del lado cliente, consulte aquí.

Tipo de valor devuelto

None

Ejemplos

Elimina un archivo.


   my_file.delete_file()

download_file

Descarga un archivo en StorageStreamDownloader. El método readall() se debe usar para leer todo el contenido o readinto() debe usarse para descargar el archivo en una secuencia. El uso de chunks() devuelve un iterador que permite al usuario iterar el contenido en fragmentos.

download_file(offset: int | None = None, length: int | None = None, **kwargs: Any) -> StorageStreamDownloader

Parámetros

offset
int
Requerido

Inicio del intervalo de bytes que se va a usar para descargar una sección del archivo. Debe establecerse si se proporciona longitud.

length
int
Requerido

Número de bytes que se van a leer de la secuencia. Esto es opcional, pero debe proporcionarse para obtener un rendimiento óptimo.

max_concurrency
int

Número máximo de conexiones paralelas que se van a usar.

validate_content
bool

Si es true, calcula un hash MD5 para cada fragmento del archivo. El servicio de almacenamiento comprueba el hash del contenido que ha llegado con el hash que se envió. Esto es principalmente útil para detectar bitflips en la conexión si el uso de http en lugar de https como https (el valor predeterminado) ya se validará. Tenga en cuenta que este hash MD5 no se almacena con el archivo . Tenga en cuenta también que si está habilitado, no se usará el algoritmo de carga eficaz para memoria, ya que calcular el hash MD5 requiere almacenar en búfer bloques completos y, al hacerlo, se anula el propósito del algoritmo eficiente en memoria.

lease
ShareLeaseClient o str

Obligatorio si el archivo tiene una concesión activa. El valor puede ser un objeto ShareLeaseClient o el identificador de concesión como una cadena.

Novedad de la versión 12.1.0.

progress_hook
Callable[[int, int], None]

Devolución de llamada para realizar un seguimiento del progreso de una descarga de larga duración. La firma es function(current: int, total: int) donde current es el número de bytes transferidos hasta ahora, y total es el tamaño total de la descarga.

timeout
int

Establece el tiempo de espera del lado servidor para la operación en segundos. Para más información, consulte https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations. Este valor no se realiza ni se valida en el cliente. Para configurar los tiempos de espera de red del lado cliente, consulte aquí.

Devoluciones

Un objeto de streaming (StorageStreamDownloader)

Tipo de valor devuelto

<xref:azure.storage.fileshare.StorageStreamDownloader>

Ejemplos

Descargue un archivo.


   with open(DEST_FILE, "wb") as data:
       stream = my_file.download_file()
       data.write(stream.readall())

from_connection_string

Cree ShareFileClient a partir de una cadena de conexión.

from_connection_string(conn_str: str, share_name: str, file_path: str, snapshot: str | Dict[str, Any] | None = None, credential: str | Dict[str, str] | AzureNamedKeyCredential | AzureSasCredential | TokenCredential | None = None, **kwargs: Any) -> Self

Parámetros

conn_str
str
Requerido

Un cadena de conexión a una cuenta de Azure Storage.

share_name
str
Requerido

Nombre del recurso compartido.

file_path
str
Requerido

Ruta de acceso al archivo.

snapshot
str
valor predeterminado: None

Instantánea de archivo opcional en la que se va a operar. Puede ser la cadena de identificador de instantánea o la respuesta devuelta de create_snapshot.

credential
valor predeterminado: None

Credenciales con las que se va a autenticar. Esto es opcional si la dirección URL de la cuenta ya tiene un token de SAS. El valor puede ser una cadena de token de SAS, una instancia de AzureSasCredential o AzureNamedKeyCredential de azure.core.credentials, una clave de acceso compartido de cuenta o una instancia de una clase TokenCredentials de azure.identity. Si el URI del recurso ya contiene un token de SAS, se omitirá en favor de una credencial explícita.

  • excepto en el caso de AzureSasCredential, donde los tokens de SAS en conflicto generarán un valor ValueError. Si usa una instancia de AzureNamedKeyCredential, "name" debe ser el nombre de la cuenta de almacenamiento y "key" debe ser la clave de la cuenta de almacenamiento.
audience
str

Audiencia que se va a usar al solicitar tokens para la autenticación de Azure Active Directory. Solo tiene un efecto cuando la credencial es de tipo TokenCredential. El valor podría ser https://storage.azure.com/ (valor predeterminado) o https://.file.core.windows.net.

Devoluciones

Un cliente de archivo.

Tipo de valor devuelto

ShareFileClient

Ejemplos

Crea el cliente de archivos con cadena de conexión.


   from azure.storage.fileshare import ShareFileClient
   file = ShareFileClient.from_connection_string(
       self.connection_string,
       share_name="helloworld2",
       file_path="myfile")

from_file_url

Un cliente para interactuar con un archivo específico, aunque es posible que ese archivo aún no exista.

from_file_url(file_url: str, snapshot: str | Dict[str, Any] | None = None, credential: str | Dict[str, str] | AzureNamedKeyCredential | AzureSasCredential | TokenCredential | None = None, **kwargs: Any) -> Self

Parámetros

file_url
str
Requerido

Identificador URI completo del archivo.

snapshot
str
valor predeterminado: None

Instantánea de archivo opcional en la que se va a operar. Puede ser la cadena de identificador de instantánea o la respuesta devuelta de create_snapshot.

credential
valor predeterminado: None

Credenciales con las que se va a autenticar. Esto es opcional si la dirección URL de la cuenta ya tiene un token de SAS. El valor puede ser una cadena de token de SAS, una instancia de AzureSasCredential o AzureNamedKeyCredential de azure.core.credentials, una clave de acceso compartido de cuenta o una instancia de una clase TokenCredentials de azure.identity. Si el URI del recurso ya contiene un token de SAS, se omitirá en favor de una credencial explícita.

  • excepto en el caso de AzureSasCredential, donde los tokens de SAS en conflicto generarán un valor ValueError. Si usa una instancia de AzureNamedKeyCredential, "name" debe ser el nombre de la cuenta de almacenamiento y "key" debe ser la clave de la cuenta de almacenamiento.
audience
str

Audiencia que se va a usar al solicitar tokens para la autenticación de Azure Active Directory. Solo tiene un efecto cuando la credencial es de tipo TokenCredential. El valor podría ser https://storage.azure.com/ (valor predeterminado) o https://.file.core.windows.net.

Devoluciones

Un cliente de archivo.

Tipo de valor devuelto

ShareFileClient

get_file_properties

Devuelve todos los metadatos definidos por el usuario, las propiedades HTTP estándar y las propiedades del sistema para el archivo.

get_file_properties(**kwargs: Any) -> FileProperties

Parámetros

lease
ShareLeaseClient o str

Obligatorio si el archivo tiene una concesión activa. El valor puede ser un objeto ShareLeaseClient o el identificador de concesión como una cadena.

Novedad de la versión 12.1.0.

timeout
int

Establece el tiempo de espera del lado servidor para la operación en segundos. Para más información, consulte https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations. Este valor no se realiza ni se valida en el cliente. Para configurar los tiempos de espera de red del lado cliente, consulte aquí.

Devoluciones

FileProperties

Tipo de valor devuelto

FileProperties

get_ranges

Devuelve la lista de intervalos de páginas válidos para un archivo o una instantánea de un archivo.

get_ranges(offset: int | None = None, length: int | None = None, **kwargs: Any) -> List[Dict[str, int]]

Parámetros

offset
int
Requerido

Especifica el desplazamiento inicial de bytes sobre el que se van a obtener los intervalos.

length
int
Requerido

Número de bytes que se van a usar para obtener intervalos.

lease
ShareLeaseClient o str

Obligatorio si el archivo tiene una concesión activa. El valor puede ser un objeto ShareLeaseClient o el identificador de concesión como una cadena.

Novedad de la versión 12.1.0.

timeout
int

Establece el tiempo de espera del lado servidor para la operación en segundos. Para más información, consulte https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations. Este valor no se realiza ni se valida en el cliente. Para configurar los tiempos de espera de red del lado cliente, consulte aquí.

Devoluciones

Lista de intervalos válidos.

Tipo de valor devuelto

List[dict[str, int]]

get_ranges_diff

Devuelve la lista de intervalos de páginas válidos para un archivo o una instantánea de un archivo.

Novedad de la versión 12.6.0.

get_ranges_diff(previous_sharesnapshot: str | Dict[str, Any], offset: int | None = None, length: int | None = None, **kwargs: Any) -> Tuple[List[Dict[str, int]], List[Dict[str, int]]]

Parámetros

offset
int
Requerido

Especifica el desplazamiento inicial de bytes sobre el que se van a obtener los intervalos.

length
int
Requerido

Número de bytes que se van a usar para obtener intervalos.

previous_sharesnapshot
str
Requerido

Parámetro de diferencia de instantánea que contiene un valor DateTime opaco que especifica una instantánea de archivo anterior que se va a comparar con una instantánea más reciente o con el archivo actual.

lease
ShareLeaseClient o str

Obligatorio si el archivo tiene una concesión activa. El valor puede ser un objeto ShareLeaseClient o el identificador de concesión como una cadena.

timeout
int

Establece el tiempo de espera del lado servidor para la operación en segundos. Para más información, consulte https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations. Este valor no se realiza ni se valida en el cliente. Para configurar los tiempos de espera de red del lado cliente, consulte aquí.

Devoluciones

Tupla de dos listas de intervalos de archivos como diccionarios con claves "start" y "end". El primer elemento son intervalos de archivos rellenados, el segundo elemento está borrado de intervalos de archivos.

Tipo de valor devuelto

tuple(list(dict(str, str), list(dict(str, str))

list_handles

Enumera los identificadores del archivo.

list_handles(**kwargs: Any) -> ItemPaged[Handle]

Parámetros

timeout
int

Establece el tiempo de espera del lado servidor para la operación en segundos. Para más información, consulte https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations. Este valor no se realiza ni se valida en el cliente. Para configurar los tiempos de espera de red del lado cliente, consulte aquí.

Devoluciones

Iterable de paginación automática de Handle

Tipo de valor devuelto

ItemPaged[Handle]

rename_file

Cambie el nombre del archivo de origen.

:p aramtype file_attributes:~azure.storage.fileshare.NTFSAttributes o str :keyword file_creation_time:

Hora de creación del archivo.

:p aramtype file_creation_time:~datetime.datetime o str :keyword file_last_write_time:

Hora de última escritura del archivo.

:p aramtype file_last_write_time:~datetime.datetime o str :keyword file_change_time:

Cambiar la hora del archivo. Si no se especifica, la hora de cambio se establecerá en la fecha y hora actuales.

Novedad de la versión 12.8.0: este parámetro se introdujo en la versión de API "2021-06-08".

rename_file(new_name: str, **kwargs: Any) -> ShareFileClient

Parámetros

content_type
str

Tipo de contenido del nuevo archivo.

Novedad de la versión 12.8.0: este parámetro se introdujo en la versión de API "2021-06-08".

metadata
Dict[str,str]

Par nombre-valor que se va a asociar a un objeto de almacenamiento de archivos.

source_lease
ShareLeaseClient o str

Obligatorio si el archivo de origen tiene una concesión activa. El valor puede ser un objeto ShareLeaseClient o el identificador de concesión como una cadena.

destination_lease
ShareLeaseClient o str

Obligatorio si el archivo de destino tiene una concesión activa. El valor puede ser un objeto ShareLeaseClient o el identificador de concesión como una cadena.

Devoluciones

Nuevo cliente de archivos.

Tipo de valor devuelto

ShareFileClient

resize_file

Cambia el tamaño de un archivo al tamaño especificado.

resize_file(size: int, **kwargs: Any) -> Dict[str, Any]

Parámetros

size
int
Requerido

Tamaño para cambiar el tamaño del archivo a (en bytes)

lease
ShareLeaseClient o str

Obligatorio si el archivo tiene una concesión activa. El valor puede ser un objeto ShareLeaseClient o el identificador de concesión como una cadena.

Novedad de la versión 12.1.0.

timeout
int

Establece el tiempo de espera del lado servidor para la operación en segundos. Para más información, consulte https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations. Este valor no se realiza ni se valida en el cliente. Para configurar los tiempos de espera de red del lado cliente, consulte aquí.

Devoluciones

Dict de propiedad actualizada por archivo (Etag y última modificación).

Tipo de valor devuelto

Dict[str, Any]

set_file_metadata

Establece los metadatos definidos por el usuario para el archivo especificado como uno o varios pares nombre-valor.

Cada llamada a esta operación reemplaza todos los metadatos existentes adjuntados al archivo. Para quitar todos los metadatos del archivo, llame a esta operación sin dict de metadatos.

set_file_metadata(metadata: Dict[str, Any] | None = None, **kwargs: Any) -> Dict[str, Any]

Parámetros

metadata
dict(str, str)
Requerido

Pares nombre-valor asociados al archivo como metadatos.

lease
ShareLeaseClient o str

Obligatorio si el archivo tiene una concesión activa. El valor puede ser un objeto ShareLeaseClient o el identificador de concesión como una cadena.

Novedad de la versión 12.1.0.

timeout
int

Establece el tiempo de espera del lado servidor para la operación en segundos. Para más información, consulte https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations. Este valor no se realiza ni se valida en el cliente. Para configurar los tiempos de espera de red del lado cliente, consulte aquí.

Devoluciones

Dict de propiedad actualizada por archivo (Etag y última modificación).

Tipo de valor devuelto

dict(str, Any)

set_http_headers

Establece encabezados HTTP en el archivo.

set_http_headers(content_settings: ContentSettings, file_attributes: str | NTFSAttributes = 'preserve', file_creation_time: str | datetime | None = 'preserve', file_last_write_time: str | datetime | None = 'preserve', file_permission: str | None = None, permission_key: str | None = None, **kwargs: Any) -> Dict[str, Any]

Parámetros

content_settings
ContentSettings
Requerido

Objeto ContentSettings usado para establecer propiedades de archivo. Se usa para establecer el tipo de contenido, la codificación, el idioma, la disposición, md5 y el control de caché.

file_attributes
NTFSAttributes
Requerido

Atributos del sistema de archivos para archivos y directorios. Si no se establece, indica la conservación de los valores existentes. Este es un ejemplo de cuándo el tipo var es str: 'Temporary|Archivo'

file_creation_time
str o datetime
Requerido

Hora de creación del archivo Valor predeterminado: Conservar.

file_last_write_time
str o datetime
Requerido

Hora de última escritura del archivo Valor predeterminado: Conservar.

file_permission
str
Requerido

Si se especifica el permiso (descriptor de seguridad) se establecerá para el directorio o archivo. Este encabezado se puede usar si el tamaño del permiso es <= 8 KB; de lo contrario, se usará el encabezado x-ms-file-permission-key. Valor predeterminado: Heredar. Si SDDL se especifica como entrada, debe tener propietario, grupo y dacl. Nota: Solo se debe especificar una de las claves x-ms-file-permission o x-ms-file-permission-key.

permission_key
str
Requerido

Clave del permiso que se va a establecer para el directorio o archivo. Nota: Solo se debe especificar una de las claves x-ms-file-permission o x-ms-file-permission-key.

file_change_time
str o datetime

Cambiar la hora del archivo. Si no se especifica, la hora de cambio se establecerá en la fecha y hora actuales.

Novedad de la versión 12.8.0: este parámetro se introdujo en la versión de API "2021-06-08".

lease
ShareLeaseClient o str

Obligatorio si el archivo tiene una concesión activa. El valor puede ser un objeto ShareLeaseClient o el identificador de concesión como una cadena.

Novedad de la versión 12.1.0.

timeout
int

Establece el tiempo de espera del lado servidor para la operación en segundos. Para más información, consulte https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations. Este valor no se realiza ni se valida en el cliente. Para configurar los tiempos de espera de red del lado cliente, consulte aquí.

Devoluciones

Dict de propiedad actualizada por archivo (Etag y última modificación).

Tipo de valor devuelto

dict(str, Any)

start_copy_from_url

Inicia la copia de datos de una dirección URL de origen en el archivo al que hace referencia el cliente.

El estado de esta operación de copia se puede encontrar mediante el método get_properties .

start_copy_from_url(source_url: str, **kwargs: Any) -> Any

Parámetros

source_url
str
Requerido

Especifica la dirección URL del archivo de origen.

file_permission
str

Si se especifica el permiso (descriptor de seguridad) se establecerá para el directorio o archivo. Este valor se puede establecer en "source" para copiar el descriptor de seguridad del archivo de origen. De lo contrario, si se establece, este valor se usará para invalidar el valor de origen. Si no se establece, el valor de permiso se hereda del directorio primario del archivo de destino. Esta configuración se puede usar si el tamaño del permiso es <= 8 KB; de lo contrario, se usará permission_key. Si SDDL se especifica como entrada, debe tener propietario, grupo y dacl. Nota: Solo se debe especificar una de las file_permission o permission_key.

Novedad de la versión 12.1.0: este parámetro se introdujo en la versión de API "2019-07-07".

permission_key
str

Clave del permiso que se va a establecer para el directorio o archivo. Este valor se puede establecer en "source" para copiar el descriptor de seguridad del archivo de origen. De lo contrario, si se establece, este valor se usará para invalidar el valor de origen. Si no se establece, el valor de permiso se hereda del directorio primario del archivo de destino. Nota: Solo se debe especificar una de las file_permission o permission_key.

Novedad de la versión 12.1.0: este parámetro se introdujo en la versión de API "2019-07-07".

file_attributes
NTFSAttributes

Este valor se puede establecer en "source" para copiar atributos de archivo del archivo de origen en el archivo de destino o para borrar todos los atributos, se puede establecer en "None". De lo contrario, se puede establecer en una lista de atributos que se van a establecer en el archivo de destino. Si no se establece, el valor predeterminado es "Archive".

Novedad de la versión 12.1.0: este parámetro se introdujo en la versión de API "2019-07-07".

file_creation_time
str o datetime

Este valor se puede establecer en "source" para copiar la hora de creación del archivo de origen en el archivo de destino o una fecha y hora para establecer como hora de creación en el archivo de destino. Esto también podría ser una cadena en formato ISO 8601. Si no se establece, la hora de creación se establecerá en el valor de fecha y hora de la creación (o cuando se sobrescribió) del archivo de destino mediante el motor de copia.

Novedad de la versión 12.1.0: este parámetro se introdujo en la versión de API "2019-07-07".

file_last_write_time
str o datetime

Este valor se puede establecer en "source" para copiar la última hora de escritura del archivo de origen en el archivo de destino, o una fecha y hora para establecer como la última hora de escritura en el archivo de destino. Esto también podría ser una cadena en formato ISO 8601. Si no se establece, el valor será la última hora de escritura en el archivo por parte del motor de copia.

Novedad de la versión 12.1.0: este parámetro se introdujo en la versión de API "2019-07-07".

file_change_time
str o datetime

Cambie la hora del archivo. Si no se especifica, la hora de cambio se establecerá en la fecha y hora actuales.

Novedad de la versión 12.9.0: este parámetro se introdujo en la versión de API "2021-06-08".

ignore_read_only
bool

Especifica la opción de sobrescribir el archivo de destino si ya existe y tiene establecido un atributo de solo lectura.

Novedad de la versión 12.1.0: este parámetro se introdujo en la versión de API "2019-07-07".

set_archive_attribute
bool

Especifica la opción para establecer el atributo de archivo en el archivo de destino. True significa que el atributo de archivo se establecerá en el archivo de destino a pesar de las invalidaciones de atributo o el estado del archivo de origen.

Novedad de la versión 12.1.0: este parámetro se introdujo en la versión de API "2019-07-07".

metadata

Pares nombre-valor asociados al archivo como metadatos.

lease
ShareLeaseClient o str

Requerido si el archivo tiene una concesión activa. El valor puede ser un objeto ShareLeaseClient o el identificador de concesión como una cadena.

Novedades de la versión 12.1.0.

timeout
int

Establece el tiempo de espera del lado servidor para la operación en segundos. Para más información, consulte https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations. Este valor no se realiza un seguimiento ni se valida en el cliente. Para configurar tiempos de espera de red del lado cliente, consulte aquí.

Tipo de valor devuelto

dict(str, Any)

Ejemplos

Copia de un archivo desde una dirección URL


   destination_file.start_copy_from_url(source_url=source_url)

upload_file

Carga un nuevo archivo.

datos param: contenido del archivo.

param int length: longitud del archivo en bytes. Especifique su tamaño máximo, hasta 1 TiB.

param file_attributes: los atributos del sistema de archivos para archivos y directorios. Si no se establece, el valor predeterminado sería "None" y los atributos se establecerán en "Archive". Este es un ejemplo para cuando el tipo var es str: 'Temporal|Archive'. file_attributes valor no distingue mayúsculas de minúsculas.

type file_attributes: str o ~azure.storage.fileshare.NTFSAttributes

param file_creation_time: Hora de creación del archivo Valor predeterminado: Ahora.

type file_creation_time: str o ~datetime.datetime

param file_last_write_time: hora de última escritura del archivo Valor predeterminado: Ahora.

type file_last_write_time: str o ~datetime.datetime

param file_permission: si se especifica el permiso (descriptor de seguridad) se establecerá para el directorio o archivo. Este encabezado se puede usar si el tamaño del permiso es <= 8 KB; de lo contrario, se usará el encabezado x-ms-file-permission-key. Valor predeterminado: Heredar. Si SDDL se especifica como entrada, debe tener propietario, grupo y dacl. Nota: Solo se debe especificar una de las claves x-ms-file-permission o x-ms-file-permission-key.

type file_permission: str

param permission_key: clave del permiso que se va a establecer para el directorio o archivo. Nota: Solo se debe especificar una de las claves x-ms-file-permission o x-ms-file-permission-key.

type permission_key: str

upload_file(data: bytes | str | Iterable | IO, length: int | None = None, file_attributes: str | NTFSAttributes = 'none', file_creation_time: str | datetime | None = 'now', file_last_write_time: str | datetime | None = 'now', file_permission: str | None = None, permission_key: str | None = None, **kwargs) -> Dict[str, Any]

Parámetros

file_change_time

Cambie la hora del archivo. Si no se especifica, la hora de cambio se establecerá en la fecha y hora actuales.

Novedad de la versión 12.8.0: este parámetro se introdujo en la versión de API "2021-06-08".

paramtype file_change_time: str o ~datetime.datetime

metadatos de palabra clave dict(str,str): pares nombre-valor asociados al archivo como metadatos.

palabra clave ~azure.storage.fileshare.ContentSettings content_settings: objeto ContentSettings usado para establecer las propiedades del archivo. Se usa para establecer el tipo de contenido, la codificación, el idioma, la disposición, md5 y el control de caché.

palabra clave bool validate_content: si es true, calcula un hash MD5 para cada intervalo del archivo. El servicio de almacenamiento comprueba el hash del contenido que ha llegado con el hash que se envió. Esto es principalmente útil para detectar bitflips en la conexión si el uso de http en lugar de https como https (valor predeterminado) ya se validará. Tenga en cuenta que este hash MD5 no se almacena con el archivo .

palabra clave int max_concurrency: número máximo de conexiones paralelas que se van a usar.

concesión de palabra clave: obligatorio si el archivo tiene una concesión activa. El valor puede ser un objeto ShareLeaseClient o el identificador de concesión como una cadena.

Novedades de la versión 12.1.0.

paramtype lease: ~azure.storage.fileshare.ShareLeaseClient o str

palabra clave progress_hook: devolución de llamada para realizar un seguimiento del progreso de una carga de larga duración. La firma es function(current: int, total: Optional[int]) donde current es el número de bytes transferidos hasta ahora, y total es el tamaño del blob o None si se desconoce el tamaño.

paramtype progress_hook: Callable[[int, Optional[int]], None]

palabra clave int timeout: establece el tiempo de espera del lado servidor para la operación en segundos. Para más información, consulte https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations. Este valor no se realiza un seguimiento ni se valida en el cliente. Para configurar tiempos de espera de red del lado cliente, consulte aquí.

codificación str de palabra clave: el valor predeterminado es UTF-8.

returns: dict de propiedad actualizada por archivo (Etag y última modificación).

rtype: dict(str, Any)

Ejemplo: Cargar un archivo.


   with open(SOURCE_FILE, "rb") as source:
       my_file.upload_file(source)

upload_range

Cargue un intervalo de bytes en un archivo.

upload_range(data: bytes, offset: int, length: int, **kwargs) -> Dict[str, Any]

Parámetros

data
bytes
Requerido

Los datos que se van a cargar.

offset
int
Requerido

Inicio del intervalo de bytes que se va a usar para cargar una sección del archivo. El intervalo puede tener un tamaño de hasta 4 MB.

length
int
Requerido

Número de bytes que se usarán para cargar una sección del archivo. El intervalo puede tener un tamaño de hasta 4 MB.

validate_content
bool

Si es true, calcula un hash MD5 del contenido de la página. El servicio de almacenamiento comprueba el hash del contenido que ha llegado con el hash que se envió. Esto es principalmente útil para detectar bitflips en la conexión si el uso de http en lugar de https como https (valor predeterminado) ya se validará. Tenga en cuenta que este hash MD5 no se almacena con el archivo .

file_last_write_mode
Literal["preserve", "now"]

Si la hora de la última escritura del archivo debe conservarse o sobrescribirse. Los valores posibles son "preserve" o "now". Si no se especifica, la hora de la última escritura del archivo se cambiará a la fecha y hora actuales.

Novedad de la versión 12.8.0: este parámetro se introdujo en la versión de API "2021-06-08".

lease
ShareLeaseClient o str

Requerido si el archivo tiene una concesión activa. El valor puede ser un objeto ShareLeaseClient o el identificador de concesión como una cadena.

Novedades de la versión 12.1.0.

timeout
int

Establece el tiempo de espera del lado servidor para la operación en segundos. Para más información, consulte https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations. Este valor no se realiza un seguimiento ni se valida en el cliente. Para configurar tiempos de espera de red del lado cliente, consulte aquí.

encoding
str

El valor predeterminado es UTF-8.

Devoluciones

Dict de propiedad actualizada por archivo (Etag y última modificación).

Tipo de valor devuelto

Dict[str, Any]

upload_range_from_url

Escribe los bytes de un punto de conexión de Azure File en el intervalo especificado de otro punto de conexión de Azure File.

upload_range_from_url(source_url: str, offset: int, length: int, source_offset: int, **kwargs: Any) -> Dict[str, Any]

Parámetros

offset
int
Requerido

Inicio del intervalo de bytes que se va a usar para actualizar una sección del archivo. El intervalo puede tener un tamaño de hasta 4 MB.

length
int
Requerido

Número de bytes que se usarán para actualizar una sección del archivo. El intervalo puede tener un tamaño de hasta 4 MB.

source_url
str
Requerido

Dirección URL de hasta 2 KB de longitud que especifica un archivo o un blob de Azure. El valor debe estar codificado para URL tal y como aparecería en un URI de solicitud. Si el origen está en otra cuenta, el origen debe ser público o debe autenticarse a través de una firma de acceso compartido. Si el origen es público, no se requiere autenticación. Ejemplos: https://myaccount.file.core.windows.net/myshare/mydir/myfilehttps://otheraccount.file.core.windows.net/myshare/mydir/myfile?sastoken

source_offset
int
Requerido

Esto indica el inicio del intervalo de bytes (inclusive) que se debe tomar del origen de copia. El servicio leerá el mismo número de bytes que el intervalo de destino (desplazamiento de longitud).

source_if_modified_since
datetime

Un valor DateTime. Azure espera que el valor de fecha pasado sea UTC. Si se incluye la zona horaria, las fechas no UTC se convertirán a UTC. Si se pasa una fecha sin información de zona horaria, se supone que es UTC. Especifique este encabezado condicional para copiar el blob solo si el blob de origen se ha modificado desde la fecha u hora especificadas.

source_if_unmodified_since
datetime

Un valor DateTime. Azure espera que el valor de fecha pasado sea UTC. Si se incluye la zona horaria, las fechas no UTC se convertirán a UTC. Si se pasa una fecha sin información de zona horaria, se supone que es UTC. Especifique este encabezado condicional para copiar el blob solo si el blob de origen no se ha modificado desde la fecha u hora especificadas.

source_etag
str

Valor ETag de origen o carácter comodín (*). Se usa para comprobar si el recurso ha cambiado y actuar según la condición especificada por el parámetro match_condition .

source_match_condition
MatchConditions

Condición de coincidencia de origen que se va a usar en el etag.

file_last_write_mode
Literal["preserve", "now"]

Si la hora de la última escritura del archivo debe conservarse o sobrescribirse. Los valores posibles son "preserve" o "now". Si no se especifica, la hora de la última escritura del archivo se cambiará a la fecha y hora actuales.

Novedad de la versión 12.8.0: este parámetro se introdujo en la versión de API "2021-06-08".

lease
ShareLeaseClient o str

Requerido si el archivo tiene una concesión activa. El valor puede ser un objeto ShareLeaseClient o el identificador de concesión como una cadena.

Novedades de la versión 12.1.0.

timeout
int

Establece el tiempo de espera del lado servidor para la operación en segundos. Para más información, consulte https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations. Este valor no se realiza un seguimiento ni se valida en el cliente. Para configurar tiempos de espera de red del lado cliente, consulte aquí.

source_authorization
str

Autentíquese como entidad de servicio mediante un secreto de cliente para acceder a un blob de origen. Asegúrese de que "portador" es el prefijo de la cadena source_authorization.

Atributos

api_version

La versión de la API de storage que se usa para las solicitudes.

location_mode

Modo de ubicación que el cliente está usando actualmente.

De forma predeterminada, será "principal". Entre las opciones se incluyen "primary" y "secondary".

primary_endpoint

Dirección URL completa del punto de conexión principal.

primary_hostname

Nombre de host del punto de conexión principal.

secondary_endpoint

Dirección URL completa del punto de conexión secundario si está configurada.

Si no está disponible, se generará un valor ValueError. Para especificar explícitamente un nombre de host secundario, use el argumento opcional secondary_hostname palabra clave en la creación de instancias.

Excepciones

ValueError

secondary_hostname

El nombre de host del punto de conexión secundario.

Si no está disponible, será Ninguno. Para especificar explícitamente un nombre de host secundario, use el argumento opcional secondary_hostname palabra clave en la creación de instancias.

url

Dirección URL completa del punto de conexión a esta entidad, incluido el token de SAS si se usa.

Puede ser el punto de conexión principal o el punto de conexión secundario en función del actual location_mode. :returns: la dirección URL completa del punto de conexión a esta entidad, incluido el token de SAS si se usa. :rtype: str