Partilhar via

ShareFileClient Classe

  • Referência

Um cliente para interagir com um ficheiro específico, embora esse ficheiro possa ainda não existir.

Para obter uma configuração mais opcional, clique aqui.

Herança
azure.storage.fileshare._shared.base_client.StorageAccountHostsMixin
ShareFileClient

Construtor

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
Necessário

O URI para a conta de armazenamento. Para criar um cliente com o URI completo no ficheiro, utilize o from_file_url classmethod.

share_name
str
Necessário

O nome da partilha do ficheiro.

file_path
str
Necessário

O caminho do ficheiro para o ficheiro com o qual pretende interagir. Se for especificado, este valor substituirá um valor de ficheiro especificado no URL do ficheiro.

snapshot
str
valor predefinido: None

Um instantâneo de ficheiro opcional no qual pretende operar. Pode ser a cadeia de ID do instantâneo ou a resposta devolvida a partir de create_snapshot.

credential
valor predefinido: None

As credenciais com as quais se autenticar. Isto é opcional se o URL da conta já tiver um token de SAS. O valor pode ser uma cadeia de token de SAS, uma instância de um AzureSasCredential ou AzureNamedKeyCredential a partir de azure.core.credentials, uma chave de acesso partilhada de conta ou uma instância de uma classe TokenCredentials a partir de azure.identity. Se o URI do recurso já contiver um token de SAS, este será ignorado a favor de uma credencial explícita

  • exceto no caso do AzureSasCredential, em que os tokens SAS em conflito gerarão um ValueError. Se utilizar uma instância do AzureNamedKeyCredential, "name" deve ser o nome da conta de armazenamento e "chave" deve ser a chave da conta de armazenamento.
token_intent
Literal['backup']

Necessário ao utilizar o TokenCredential para autenticação e ignorado para outras formas de autenticação. Especifica a intenção para todos os pedidos ao utilizar a autenticação TokenCredential . Os valores possíveis são:

cópia de segurança – especifica que os pedidos se destinam a operações de tipo de cópia de segurança/administrador, o que significa que todas as ACLs de ficheiro/diretório são ignoradas e são concedidas permissões completas. O utilizador também tem de ter a permissão RBAC necessária.

allow_trailing_dot
bool

Se for verdadeiro, o ponto à direita não será cortado do URI de destino.

allow_source_trailing_dot
bool

Se for verdadeiro, o ponto à direita não será cortado do URI de origem.

api_version
str

A versão da API de Armazenamento a utilizar para pedidos. O valor predefinido é a versão de serviço mais recente compatível com o SDK atual. Definir para uma versão mais antiga pode resultar numa compatibilidade de funcionalidades reduzida.

Novidade na versão 12.1.0.

secondary_hostname
str

O nome do anfitrião do ponto final secundário.

max_range_size
int

O tamanho máximo do intervalo utilizado para um carregamento de ficheiros. A predefinição é 4*1024*1024.

audience
str

A audiência a utilizar ao pedir tokens para autenticação do Azure Active Directory. Só tem um efeito quando a credencial é do tipo TokenCredential. O valor pode ser https://storage.azure.com/ (predefinição) ou https://.file.core.windows.net.

Métodos

abort_copy

Abortar uma operação de cópia em curso.

Isto irá deixar um ficheiro de destino com comprimento zero e metadados completos. Isto gerará um erro se a operação de cópia já tiver terminado.
acquire_lease

Pede uma nova concessão.

Se o ficheiro não tiver uma concessão ativa, o Serviço de Ficheiros cria uma concessão no blob e devolve uma nova concessão.
clear_range

Limpa o intervalo especificado e liberta o espaço utilizado no armazenamento para esse intervalo.
close

Este método consiste em fechar os sockets abertos pelo cliente. Não é necessário utilizá-la ao utilizar com um gestor de contexto.
close_all_handles

Feche quaisquer identificadores de ficheiro abertos.

Esta operação irá bloquear até que o serviço tenha fechado todos os identificadores abertos.
close_handle

Feche uma alça de ficheiro aberta.
create_file

Cria um novo ficheiro.

Tenha em atenção que apenas inicializa o ficheiro sem conteúdo.
delete_file

Marca o ficheiro especificado para eliminação. O ficheiro é eliminado mais tarde durante a libertação da memória.
download_file

Transfere um ficheiro para o StorageStreamDownloader. O método readall() tem de ser utilizado para ler todo o conteúdo ou o método readinto() tem de ser utilizado para transferir o ficheiro para um fluxo. A utilização de segmentos() devolve um iterador que permite ao utilizador iterar sobre o conteúdo em segmentos.
from_connection_string

Criar ShareFileClient a partir de uma Cadeia de Ligação.
from_file_url

Um cliente para interagir com um ficheiro específico, embora esse ficheiro possa ainda não existir.
get_file_properties

Devolve todos os metadados definidos pelo utilizador, propriedades HTTP padrão e propriedades do sistema para o ficheiro.
get_ranges

Devolve a lista de intervalos de página válidos para um ficheiro ou instantâneo de um ficheiro.
get_ranges_diff

Devolve a lista de intervalos de página válidos para um ficheiro ou instantâneo de um ficheiro.

Novidade na versão 12.6.0.
list_handles

Lista identificadores para o ficheiro.
rename_file

Mude o nome do ficheiro de origem.

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

Hora de criação do ficheiro.

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

Hora da última escrita do ficheiro.

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

Altere a hora do ficheiro. Se não for especificado, a hora de alteração será definida como a data/hora atual.

Novidade na versão 12.8.0: este parâmetro foi introduzido na versão de API "2021-06-08".
resize_file

Redimensiona um ficheiro para o tamanho especificado.
set_file_metadata

Define metadados definidos pelo utilizador para o ficheiro especificado como um ou mais pares nome-valor.

Cada chamada para esta operação substitui todos os metadados existentes anexados ao ficheiro. Para remover todos os metadados do ficheiro, chame esta operação sem dict de metadados.
set_http_headers

Define cabeçalhos HTTP no ficheiro.
start_copy_from_url

Inicia a cópia de dados de um URL de origem para o ficheiro referenciado pelo cliente.

O estado desta operação de cópia pode ser encontrado com o método get_properties .
upload_file

Carrega um novo ficheiro.

Dados de param: conteúdo do ficheiro.

Comprimento do parâmetro int: comprimento do ficheiro em bytes. Especifique o tamanho máximo, até 1 TiB.

param file_attributes: os atributos do sistema de ficheiros para ficheiros e diretórios. Se não estiver definido, o valor predefinido será "Nenhum" e os atributos serão definidos como "Arquivo". Eis um exemplo para quando o tipo de var é str: 'Temporary|Arquivo'. file_attributes valor não é sensível a maiúsculas e minúsculas.

escreva file_attributes: str ou ~azure.storage.fileshare.NTFSAttributes

param file_creation_time: Tempo de criação do valor predefinido do ficheiro: Agora.

escreva file_creation_time: str ou ~datetime.datetime

param file_last_write_time: Última hora de escrita para o valor predefinido do ficheiro: Agora.

escreva file_last_write_time: str ou ~datetime.datetime

param file_permission: se especificar a permissão (descritor de segurança) será definida para o diretório/ficheiro. Este cabeçalho pode ser utilizado se o Tamanho da permissão for <= 8KB, caso contrário, será utilizado o cabeçalho x-ms-file-permission-key. Valor predefinido: Herdar. Se o SDDL for especificado como entrada, tem de ter proprietário, grupo e dacl. Nota: só deve ser especificada uma das chaves x-ms-file-permission ou x-ms-file-permission-key.

tipo file_permission: str

param permission_key: chave da permissão a definir para o diretório/ficheiro. Nota: só deve ser especificada uma das chaves x-ms-file-permission ou x-ms-file-permission-key.

tipo permission_key: str
upload_range

Carregue um intervalo de bytes para um ficheiro.
upload_range_from_url

Escreve os bytes de um ponto final de Ficheiro do Azure no intervalo especificado de outro ponto final de Ficheiro do Azure.

abort_copy

Abortar uma operação de cópia em curso.

Isto irá deixar um ficheiro de destino com comprimento zero e metadados completos. Isto gerará um erro se a operação de cópia já tiver terminado.

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

Parâmetros

copy_id
str ou FileProperties
Necessário

A operação de cópia a abortar. Pode ser um ID ou uma instância de FileProperties.

lease
ShareLeaseClient ou str

Necessário se o ficheiro tiver uma concessão ativa. O valor pode ser um objeto ShareLeaseClient ou o ID de concessão como uma cadeia.

Novidade na versão 12.1.0.

timeout
int

Define o tempo limite do lado do servidor para a operação em segundos. Para obter mais detalhes, veja https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations. Este valor não é controlado ou validado no cliente. Para configurar tempos limite de rede do lado do cliente, veja aqui.

Tipo de retorno

None

acquire_lease

Pede uma nova concessão.

Se o ficheiro não tiver uma concessão ativa, o Serviço de Ficheiros cria uma concessão no blob e devolve uma nova concessão.

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

Parâmetros

lease_id
str
Necessário

ID de concessão proposto, num formato de cadeia GUID. O Serviço de Ficheiros devolve 400 (Pedido inválido) se o ID de concessão proposto não estiver no formato correto.

timeout
int

Define o tempo limite do lado do servidor para a operação em segundos. Para obter mais detalhes, veja https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations. Este valor não é controlado ou validado no cliente. Para configurar tempos limite de rede do lado do cliente, veja aqui.

Devoluções

Um objeto ShareLeaseClient.

Tipo de retorno

ShareLeaseClient

Exemplos

Adquirir uma concessão num ficheiro.


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

   lease.release()

clear_range

Limpa o intervalo especificado e liberta o espaço utilizado no armazenamento para esse intervalo.

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

Parâmetros

offset
int
Necessário

Início do intervalo de bytes a utilizar para limpar uma secção do ficheiro. O intervalo pode ter até 4 MB de tamanho.

length
int
Necessário

Número de bytes a utilizar para limpar uma secção do ficheiro. O intervalo pode ter até 4 MB de tamanho.

lease
ShareLeaseClient ou str

Necessário se o ficheiro tiver uma concessão ativa. O valor pode ser um objeto ShareLeaseClient ou o ID de concessão como uma cadeia.

Novidade na versão 12.1.0.

timeout
int

Define o tempo limite do lado do servidor para a operação em segundos. Para obter mais detalhes, veja https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations. Este valor não é controlado ou validado no cliente. Para configurar tempos limite de rede do lado do cliente, veja aqui.

Devoluções

Dict da propriedade atualizada pelo ficheiro (Etag e última modificação).

Tipo de retorno

Dict[str, Any]

close

Este método consiste em fechar os sockets abertos pelo cliente. Não é necessário utilizá-la ao utilizar com um gestor de contexto.

close()

close_all_handles

Feche quaisquer identificadores de ficheiro abertos.

Esta operação irá bloquear até que o serviço tenha fechado todos os identificadores abertos.

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

Parâmetros

timeout
int

Define o tempo limite do lado do servidor para a operação em segundos. Para obter mais detalhes, veja https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations. Este valor não é controlado ou validado no cliente. Para configurar tempos limite de rede do lado do cliente, veja aqui.

Devoluções

O número de identificadores fechados (pode ser 0 se a alça especificada não tiver sido encontrada) e o número de identificadores não conseguiu fechar num ditado.

Tipo de retorno

dict[str, int]

close_handle

Feche uma alça de ficheiro aberta.

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

Parâmetros

handle
str ou Handle
Necessário

Um identificador específico para fechar.

timeout
int

Define o tempo limite do lado do servidor para a operação em segundos. Para obter mais detalhes, veja https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations. Este valor não é controlado ou validado no cliente. Para configurar tempos limite de rede do lado do cliente, veja aqui.

Devoluções

O número de identificadores fechados (pode ser 0 se a alça especificada não tiver sido encontrada) e o número de identificadores não conseguiu fechar num ditado.

Tipo de retorno

dict[str, int]

create_file

Cria um novo ficheiro.

Tenha em atenção que apenas inicializa o ficheiro sem conteúdo.

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
Necessário

Especifica o tamanho máximo para o ficheiro, até 1 TB.

file_attributes
NTFSAttributes
Necessário

Os atributos do sistema de ficheiros para ficheiros e diretórios. Se não for definido, o valor predefinido será "Nenhum" e os atributos serão definidos como "Arquivo". Eis um exemplo para quando o tipo de var é str: 'Temporary|Arquivo'. file_attributes valor não é sensível a maiúsculas e minúsculas.

file_creation_time
str ou datetime
Necessário

Hora de criação do valor predefinido do ficheiro: Agora.

file_last_write_time
str ou datetime
Necessário

Hora da última escrita do ficheiro Valor predefinido: Agora.

file_permission
str
Necessário

Se for especificada, a permissão (descritor de segurança) será definida para o diretório/ficheiro. Este cabeçalho pode ser utilizado se o Tamanho da permissão for <= 8 KB, caso contrário, será utilizado o cabeçalho x-ms-file-permission-key. Valor predefinido: Herdar. Se o SDDL for especificado como entrada, tem de ter proprietário, grupo e dacl. Nota: apenas deve ser especificado um dos x-ms-file-permission ou x-ms-file-permission-key.

permission_key
str
Necessário

Chave da permissão a definir para o diretório/ficheiro. Nota: apenas deve ser especificado um dos x-ms-file-permission ou x-ms-file-permission-key.

file_change_time
str ou datetime

Altere a hora do ficheiro. Se não for especificado, a hora de alteração será definida como a data/hora atual.

Novidade na versão 12.8.0: este parâmetro foi introduzido na versão de API "2021-06-08".

content_settings
ContentSettings

Objeto ContentSettings utilizado para definir propriedades de ficheiro. Utilizado para definir o tipo de conteúdo, codificação, idioma, disposição, md5 e controlo de cache.

metadata
dict(str,str)

Pares nome-valor associados ao ficheiro como metadados.

lease
ShareLeaseClient ou str

Necessário se o ficheiro tiver uma concessão ativa. O valor pode ser um objeto ShareLeaseClient ou o ID de concessão como uma cadeia.

Novidade na versão 12.1.0.

timeout
int

Define o tempo limite do lado do servidor para a operação em segundos. Para obter mais detalhes, veja https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations. Este valor não é controlado ou validado no cliente. Para configurar tempos limite de rede do lado do cliente, veja aqui.

Devoluções

Dict da propriedade atualizada pelo ficheiro (Etag e última modificação).

Tipo de retorno

dict(str, Any)

Exemplos

Criar um ficheiro.


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

delete_file

Marca o ficheiro especificado para eliminação. O ficheiro é eliminado mais tarde durante a libertação da memória.

delete_file(**kwargs: Any) -> None

Parâmetros

lease
ShareLeaseClient ou str

Necessário se o ficheiro tiver uma concessão ativa. O valor pode ser um objeto ShareLeaseClient ou o ID de concessão como uma cadeia.

Novidade na versão 12.1.0.

timeout
int

Define o tempo limite do lado do servidor para a operação em segundos. Para obter mais detalhes, veja https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations. Este valor não é controlado ou validado no cliente. Para configurar tempos limite de rede do lado do cliente, veja aqui.

Tipo de retorno

None

Exemplos

Eliminar um ficheiro.


   my_file.delete_file()

download_file

Transfere um ficheiro para o StorageStreamDownloader. O método readall() tem de ser utilizado para ler todo o conteúdo ou o método readinto() tem de ser utilizado para transferir o ficheiro para um fluxo. A utilização de segmentos() devolve um iterador que permite ao utilizador iterar sobre o conteúdo em segmentos.

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

Parâmetros

offset
int
Necessário

Início do intervalo de bytes a utilizar para transferir uma secção do ficheiro. Tem de ser definido se o comprimento for fornecido.

length
int
Necessário

Número de bytes a ler a partir da transmissão em fluxo. Isto é opcional, mas deve ser fornecido para um desempenho ideal.

max_concurrency
int

Número máximo de ligações paralelas a utilizar.

validate_content
bool

Se for verdadeiro, calcula um hash MD5 para cada segmento do ficheiro. O serviço de armazenamento compara o hash do conteúdo que chegou ao hash que foi enviado. Isto é importante para detetar bitflips no fio se a utilização de http em vez de https como https (a predefinição) já for validada. Tenha em atenção que este hash MD5 não é armazenado com o ficheiro. Tenha também em atenção que, se estiver ativado, o algoritmo de carregamento com eficiência de memória não será utilizado, uma vez que a computação do hash MD5 requer a colocação em memória intermédia de blocos inteiros e, ao fazê-lo, irá derrotar a finalidade do algoritmo com eficiência de memória.

lease
ShareLeaseClient ou str

Necessário se o ficheiro tiver uma concessão ativa. O valor pode ser um objeto ShareLeaseClient ou o ID de concessão como uma cadeia.

Novidade na versão 12.1.0.

progress_hook
Callable[[int, int], None]

Uma chamada de retorno para controlar o progresso de uma transferência de execução prolongada. A assinatura é uma função (atual: int, total: int) em que atual é o número de bytes transferidos até agora e o total é o tamanho total da transferência.

timeout
int

Define o tempo limite do lado do servidor para a operação em segundos. Para obter mais detalhes, veja https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations. Este valor não é controlado ou validado no cliente. Para configurar tempos limite de rede do lado do cliente, veja aqui.

Devoluções

Um objeto de transmissão em fluxo (StorageStreamDownloader)

Tipo de retorno

<xref:azure.storage.fileshare.StorageStreamDownloader>

Exemplos

Transfira um ficheiro.


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

from_connection_string

Criar ShareFileClient a partir de uma Cadeia de Ligação.

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
Necessário

Uma cadeia de ligação a uma conta de Armazenamento do Azure.

share_name
str
Necessário

O nome da partilha.

file_path
str
Necessário

O caminho do ficheiro.

snapshot
str
valor predefinido: None

Um instantâneo de ficheiro opcional no qual pretende operar. Pode ser a cadeia de ID do instantâneo ou a resposta devolvida a partir de create_snapshot.

credential
valor predefinido: None

As credenciais com as quais se autenticar. Isto é opcional se o URL da conta já tiver um token de SAS. O valor pode ser uma cadeia de token de SAS, uma instância de um AzureSasCredential ou AzureNamedKeyCredential a partir de azure.core.credentials, uma chave de acesso partilhada de conta ou uma instância de uma classe TokenCredentials a partir de azure.identity. Se o URI do recurso já contiver um token de SAS, este será ignorado a favor de uma credencial explícita

  • exceto no caso do AzureSasCredential, em que os tokens SAS em conflito gerarão um ValueError. Se utilizar uma instância do AzureNamedKeyCredential, "name" deve ser o nome da conta de armazenamento e "chave" deve ser a chave da conta de armazenamento.
audience
str

A audiência a utilizar ao pedir tokens para autenticação do Azure Active Directory. Só tem um efeito quando a credencial é do tipo TokenCredential. O valor pode ser https://storage.azure.com/ (predefinição) ou https://.file.core.windows.net.

Devoluções

Um Cliente de ficheiros.

Tipo de retorno

ShareFileClient

Exemplos

Cria o cliente de ficheiros com cadeia de ligação.


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

from_file_url

Um cliente para interagir com um ficheiro específico, embora esse ficheiro possa ainda não existir.

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
Necessário

O URI completo para o ficheiro.

snapshot
str
valor predefinido: None

Um instantâneo de ficheiro opcional no qual pretende operar. Pode ser a cadeia de ID do instantâneo ou a resposta devolvida a partir de create_snapshot.

credential
valor predefinido: None

As credenciais com as quais se autenticar. Isto é opcional se o URL da conta já tiver um token de SAS. O valor pode ser uma cadeia de token de SAS, uma instância de um AzureSasCredential ou AzureNamedKeyCredential a partir de azure.core.credentials, uma chave de acesso partilhada de conta ou uma instância de uma classe TokenCredentials a partir de azure.identity. Se o URI do recurso já contiver um token de SAS, este será ignorado a favor de uma credencial explícita

  • exceto no caso do AzureSasCredential, em que os tokens SAS em conflito gerarão um ValueError. Se utilizar uma instância do AzureNamedKeyCredential, "name" deve ser o nome da conta de armazenamento e "chave" deve ser a chave da conta de armazenamento.
audience
str

A audiência a utilizar ao pedir tokens para autenticação do Azure Active Directory. Só tem um efeito quando a credencial é do tipo TokenCredential. O valor pode ser https://storage.azure.com/ (predefinição) ou https://.file.core.windows.net.

Devoluções

Um Cliente de ficheiros.

Tipo de retorno

ShareFileClient

get_file_properties

Devolve todos os metadados definidos pelo utilizador, propriedades HTTP padrão e propriedades do sistema para o ficheiro.

get_file_properties(**kwargs: Any) -> FileProperties

Parâmetros

lease
ShareLeaseClient ou str

Necessário se o ficheiro tiver uma concessão ativa. O valor pode ser um objeto ShareLeaseClient ou o ID de concessão como uma cadeia.

Novidade na versão 12.1.0.

timeout
int

Define o tempo limite do lado do servidor para a operação em segundos. Para obter mais detalhes, veja https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations. Este valor não é controlado ou validado no cliente. Para configurar tempos limite de rede do lado do cliente, veja aqui.

Devoluções

FileProperties

Tipo de retorno

FileProperties

get_ranges

Devolve a lista de intervalos de página válidos para um ficheiro ou instantâneo de um ficheiro.

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

Parâmetros

offset
int
Necessário

Especifica o desvio inicial de bytes sobre os quais obter intervalos.

length
int
Necessário

Número de bytes a utilizar para obter intervalos.

lease
ShareLeaseClient ou str

Necessário se o ficheiro tiver uma concessão ativa. O valor pode ser um objeto ShareLeaseClient ou o ID de concessão como uma cadeia.

Novidade na versão 12.1.0.

timeout
int

Define o tempo limite do lado do servidor para a operação em segundos. Para obter mais detalhes, veja https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations. Este valor não é controlado ou validado no cliente. Para configurar tempos limite de rede do lado do cliente, veja aqui.

Devoluções

Uma lista de intervalos válidos.

Tipo de retorno

List[dict[str, int]]

get_ranges_diff

Devolve a lista de intervalos de página válidos para um ficheiro ou instantâneo de um ficheiro.

Novidade na versão 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
Necessário

Especifica o desvio inicial de bytes sobre os quais obter intervalos.

length
int
Necessário

Número de bytes a utilizar para obter intervalos.

previous_sharesnapshot
str
Necessário

O parâmetro de diferença de instantâneo que contém um valor dateTime opaco que especifica um instantâneo de ficheiro anterior para ser comparado com um instantâneo mais recente ou o ficheiro atual.

lease
ShareLeaseClient ou str

Necessário se o ficheiro tiver uma concessão ativa. O valor pode ser um objeto ShareLeaseClient ou o ID de concessão como uma cadeia.

timeout
int

Define o tempo limite do lado do servidor para a operação em segundos. Para obter mais detalhes, veja https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations. Este valor não é controlado ou validado no cliente. Para configurar tempos limite de rede do lado do cliente, veja aqui.

Devoluções

Uma cadeia de identificação de duas listas de intervalos de ficheiros como dicionários com chaves "start" e "end". O primeiro elemento são intervalos de ficheiros preenchidos, o segundo elemento é intervalos de ficheiros limpos.

Tipo de retorno

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

list_handles

Lista identificadores para o ficheiro.

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

Parâmetros

timeout
int

Define o tempo limite do lado do servidor para a operação em segundos. Para obter mais detalhes, veja https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations. Este valor não é controlado ou validado no cliente. Para configurar tempos limite de rede do lado do cliente, veja aqui.

Devoluções

Iterável de paginação automática do Identificador

Tipo de retorno

ItemPaged[Handle]

rename_file

Mude o nome do ficheiro de origem.

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

Hora de criação do ficheiro.

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

Hora da última escrita do ficheiro.

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

Altere a hora do ficheiro. Se não for especificado, a hora de alteração será definida como a data/hora atual.

Novidade na versão 12.8.0: este parâmetro foi introduzido na versão de API "2021-06-08".

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

Parâmetros

content_type
str

O Tipo de Conteúdo do novo ficheiro.

Novidade na versão 12.8.0: este parâmetro foi introduzido na versão de API "2021-06-08".

metadata
Dict[str,str]

Um par nome-valor para associar a um objeto de armazenamento de ficheiros.

source_lease
ShareLeaseClient ou str

Necessário se o ficheiro de origem tiver uma concessão ativa. O valor pode ser um objeto ShareLeaseClient ou o ID de concessão como uma cadeia.

destination_lease
ShareLeaseClient ou str

Necessário se o ficheiro de destino tiver uma concessão ativa. O valor pode ser um objeto ShareLeaseClient ou o ID de concessão como uma cadeia.

Devoluções

O novo Cliente de Ficheiros.

Tipo de retorno

ShareFileClient

resize_file

Redimensiona um ficheiro para o tamanho especificado.

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

Parâmetros

size
int
Necessário

Tamanho para redimensionar o ficheiro para (em bytes)

lease
ShareLeaseClient ou str

Necessário se o ficheiro tiver uma concessão ativa. O valor pode ser um objeto ShareLeaseClient ou o ID de concessão como uma cadeia.

Novidade na versão 12.1.0.

timeout
int

Define o tempo limite do lado do servidor para a operação em segundos. Para obter mais detalhes, veja https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations. Este valor não é controlado ou validado no cliente. Para configurar tempos limite de rede do lado do cliente, veja aqui.

Devoluções

Dict da propriedade atualizada pelo ficheiro (Etag e última modificação).

Tipo de retorno

Dict[str, Any]

set_file_metadata

Define metadados definidos pelo utilizador para o ficheiro especificado como um ou mais pares nome-valor.

Cada chamada para esta operação substitui todos os metadados existentes anexados ao ficheiro. Para remover todos os metadados do ficheiro, chame esta operação sem dict de metadados.

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

Parâmetros

metadata
dict(str, str)
Necessário

Pares nome-valor associados ao ficheiro como metadados.

lease
ShareLeaseClient ou str

Necessário se o ficheiro tiver uma concessão ativa. O valor pode ser um objeto ShareLeaseClient ou o ID de concessão como uma cadeia.

Novidade na versão 12.1.0.

timeout
int

Define o tempo limite do lado do servidor para a operação em segundos. Para obter mais detalhes, veja https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations. Este valor não é controlado ou validado no cliente. Para configurar tempos limite de rede do lado do cliente, veja aqui.

Devoluções

Dict da propriedade atualizada pelo ficheiro (Etag e última modificação).

Tipo de retorno

dict(str, Any)

set_http_headers

Define cabeçalhos HTTP no ficheiro.

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
Necessário

Objeto ContentSettings utilizado para definir propriedades de ficheiro. Utilizado para definir o tipo de conteúdo, codificação, idioma, disposição, md5 e controlo de cache.

file_attributes
NTFSAttributes
Necessário

Os atributos do sistema de ficheiros para ficheiros e diretórios. Se não estiver definido, indica a preservação dos valores existentes. Eis um exemplo para quando o tipo de var é str: 'Temporary|Arquivo"

file_creation_time
str ou datetime
Necessário

Tempo de criação do ficheiro Valor predefinido: Preservar.

file_last_write_time
str ou datetime
Necessário

Hora da última escrita do ficheiro Valor predefinido: Preservar.

file_permission
str
Necessário

Se for especificada, a permissão (descritor de segurança) será definida para o diretório/ficheiro. Este cabeçalho pode ser utilizado se o Tamanho da permissão for <= 8 KB, caso contrário, será utilizado o cabeçalho x-ms-file-permission-key. Valor predefinido: Herdar. Se o SDDL for especificado como entrada, tem de ter proprietário, grupo e dacl. Nota: apenas deve ser especificado um dos x-ms-file-permission ou x-ms-file-permission-key.

permission_key
str
Necessário

Chave da permissão a definir para o diretório/ficheiro. Nota: apenas deve ser especificado um dos x-ms-file-permission ou x-ms-file-permission-key.

file_change_time
str ou datetime

Altere a hora do ficheiro. Se não for especificado, a hora de alteração será definida como a data/hora atual.

Novidade na versão 12.8.0: este parâmetro foi introduzido na versão de API "2021-06-08".

lease
ShareLeaseClient ou str

Necessário se o ficheiro tiver uma concessão ativa. O valor pode ser um objeto ShareLeaseClient ou o ID de concessão como uma cadeia.

Novidade na versão 12.1.0.

timeout
int

Define o tempo limite do lado do servidor para a operação em segundos. Para obter mais detalhes, veja https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations. Este valor não é controlado ou validado no cliente. Para configurar tempos limite de rede do lado do cliente, veja aqui.

Devoluções

Dict da propriedade atualizada pelo ficheiro (Etag e última modificação).

Tipo de retorno

dict(str, Any)

start_copy_from_url

Inicia a cópia de dados de um URL de origem para o ficheiro referenciado pelo cliente.

O estado desta operação de cópia pode ser encontrado com o método get_properties .

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

Parâmetros

source_url
str
Necessário

Especifica o URL do ficheiro de origem.

file_permission
str

Se for especificada, a permissão (descritor de segurança) será definida para o diretório/ficheiro. Este valor pode ser definido como "origem" para copiar o descritor de segurança do ficheiro de origem. Caso contrário, se estiver definido, este valor será utilizado para substituir o valor de origem. Se não estiver definido, o valor de permissão é herdado do diretório principal do ficheiro de destino. Esta definição pode ser utilizada se o Tamanho da permissão for <= 8 KB, caso contrário, será utilizado permission_key. Se o SDDL for especificado como entrada, tem de ter proprietário, grupo e dacl. Nota: apenas um dos file_permission ou permission_key deve ser especificado.

Novidade na versão 12.1.0: este parâmetro foi introduzido na versão da API "2019-07-07".

permission_key
str

Chave da permissão a definir para o diretório/ficheiro. Este valor pode ser definido como "origem" para copiar o descritor de segurança do ficheiro de origem. Caso contrário, se estiver definido, este valor será utilizado para substituir o valor de origem. Se não estiver definido, o valor de permissão é herdado do diretório principal do ficheiro de destino. Nota: apenas um dos file_permission ou permission_key deve ser especificado.

Novidade na versão 12.1.0: este parâmetro foi introduzido na versão da API "2019-07-07".

file_attributes
NTFSAttributes

Este valor pode ser definido como "origem" para copiar atributos de ficheiro do ficheiro de origem para o ficheiro de destino ou, para limpar todos os atributos, pode ser definido como "Nenhum". Caso contrário, pode ser definido como uma lista de atributos a definir no ficheiro de destino. Se isto não estiver definido, o valor predefinido é "Arquivo".

Novidade na versão 12.1.0: este parâmetro foi introduzido na versão da API "2019-07-07".

file_creation_time
str ou datetime

Este valor pode ser definido como "origem" para copiar a hora de criação do ficheiro de origem para o ficheiro de destino ou um datetime para definir como hora de criação no ficheiro de destino. Também pode ser uma cadeia no formato ISO 8601. Se isto não estiver definido, a hora de criação será definida para o valor de data/hora da criação (ou quando foi substituído) do ficheiro de destino por motor de cópia.

Novidade na versão 12.1.0: este parâmetro foi introduzido na versão da API "2019-07-07".

file_last_write_time
str ou datetime

Este valor pode ser definido como "origem" para copiar a última hora de escrita do ficheiro de origem para o ficheiro de destino ou um datetime para definir como a última hora de escrita no ficheiro de destino. Também pode ser uma cadeia no formato ISO 8601. Se isto não estiver definido, o valor será a última hora de escrita para o ficheiro pelo motor de cópia.

Novidade na versão 12.1.0: este parâmetro foi introduzido na versão da API "2019-07-07".

file_change_time
str ou datetime

Altere a hora do ficheiro. Se não for especificado, a hora de alteração será definida para a data/hora atual.

Novidade na versão 12.9.0: este parâmetro foi introduzido na versão da API "2021-06-08".

ignore_read_only
bool

Especifica a opção para substituir o ficheiro de destino se já existir e tiver o atributo só de leitura definido.

Novidade na versão 12.1.0: este parâmetro foi introduzido na versão da API "2019-07-07".

set_archive_attribute
bool

Especifica a opção para definir o atributo de arquivo no ficheiro de destino. Verdadeiro significa que o atributo de arquivo será definido no ficheiro de destino, apesar das substituições de atributos ou do estado do ficheiro de origem.

Novidade na versão 12.1.0: este parâmetro foi introduzido na versão da API "2019-07-07".

metadata

Pares nome-valor associados ao ficheiro como metadados.

lease
ShareLeaseClient ou str

Necessário se o ficheiro tiver uma concessão ativa. O valor pode ser um objeto ShareLeaseClient ou o ID de concessão como uma cadeia.

Novidades na versão 12.1.0.

timeout
int

Define o tempo limite do lado do servidor para a operação em segundos. Para obter mais detalhes, veja https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations. Este valor não é monitorizado nem validado no cliente. Para configurar tempos limite de rede do lado do cliente, veja aqui.

Tipo de retorno

dict(str, Any)

Exemplos

Copiar um ficheiro de um URL


   destination_file.start_copy_from_url(source_url=source_url)

upload_file

Carrega um novo ficheiro.

Dados de param: conteúdo do ficheiro.

Comprimento do parâmetro int: comprimento do ficheiro em bytes. Especifique o tamanho máximo, até 1 TiB.

param file_attributes: os atributos do sistema de ficheiros para ficheiros e diretórios. Se não estiver definido, o valor predefinido será "Nenhum" e os atributos serão definidos como "Arquivo". Eis um exemplo para quando o tipo de var é str: 'Temporary|Arquivo'. file_attributes valor não é sensível a maiúsculas e minúsculas.

escreva file_attributes: str ou ~azure.storage.fileshare.NTFSAttributes

param file_creation_time: Tempo de criação do valor predefinido do ficheiro: Agora.

escreva file_creation_time: str ou ~datetime.datetime

param file_last_write_time: Última hora de escrita para o valor predefinido do ficheiro: Agora.

escreva file_last_write_time: str ou ~datetime.datetime

param file_permission: se especificar a permissão (descritor de segurança) será definida para o diretório/ficheiro. Este cabeçalho pode ser utilizado se o Tamanho da permissão for <= 8KB, caso contrário, será utilizado o cabeçalho x-ms-file-permission-key. Valor predefinido: Herdar. Se o SDDL for especificado como entrada, tem de ter proprietário, grupo e dacl. Nota: só deve ser especificada uma das chaves x-ms-file-permission ou x-ms-file-permission-key.

tipo file_permission: str

param permission_key: chave da permissão a definir para o diretório/ficheiro. Nota: só deve ser especificada uma das chaves x-ms-file-permission ou x-ms-file-permission-key.

tipo 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

Altere a hora do ficheiro. Se não for especificado, a hora de alteração será definida para a data/hora atual.

Novidade na versão 12.8.0: este parâmetro foi introduzido na versão da API "2021-06-08".

paramtype file_change_time: str ou ~datetime.datetime

metadados de palavras-chave dict(str,str): pares nome-valor associados ao ficheiro como metadados.

keyword ~azure.storage.fileshare.ContentSettings content_settings: Objeto ContentSettings utilizado para definir propriedades de ficheiro. Utilizado para definir o tipo de conteúdo, codificação, idioma, disposição, md5 e controlo de cache.

validate_content bool de palavra-chave: se for verdadeiro, calcula um hash MD5 para cada intervalo do ficheiro. O serviço de armazenamento compara o hash do conteúdo que chegou ao hash que foi enviado. Isto é essencialmente importante para detetar bitflips no fio se utilizar http em vez de https como https (a predefinição) já irá validar. Tenha em atenção que este hash MD5 não é armazenado com o ficheiro.

max_concurrency de palavras-chave: número máximo de ligações paralelas a utilizar.

concessão de palavras-chave: necessário se o ficheiro tiver uma concessão ativa. O valor pode ser um objeto ShareLeaseClient ou o ID de concessão como uma cadeia.

Novidades na versão 12.1.0.

concessão de parâmetros: ~azure.storage.fileshare.ShareLeaseClient ou str

palavra-chave progress_hook: uma chamada de retorno para controlar o progresso de um carregamento de execução prolongada. A assinatura é função(atual: int, total: Opcional[int]) em que atual é o número de bytes transferidos até agora e o total é o tamanho do blob ou Nenhum se o tamanho for desconhecido.

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

tempo limite de int de palavra-chave: define o tempo limite do lado do servidor para a operação em segundos. Para obter mais detalhes, veja https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations. Este valor não é monitorizado nem validado no cliente. Para configurar tempos limite de rede do lado do cliente, veja aqui.

codificação de str de palavras-chave: predefinições para UTF-8.

devolve: Dict de propriedades atualizadas por ficheiros (Etag e última modificação).

rtype: dict(str, Any)

Exemplo: Carregar um ficheiro.


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

upload_range

Carregue um intervalo de bytes para um ficheiro.

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

Parâmetros

data
bytes
Necessário

Os dados a carregar.

offset
int
Necessário

Início do intervalo de bytes a utilizar para carregar uma secção do ficheiro. O intervalo pode ter até 4 MB de tamanho.

length
int
Necessário

Número de bytes a utilizar para carregar uma secção do ficheiro. O intervalo pode ter até 4 MB de tamanho.

validate_content
bool

Se for verdadeiro, calcula um hash MD5 do conteúdo da página. O serviço de armazenamento compara o hash do conteúdo que chegou ao hash que foi enviado. Isto é essencialmente importante para detetar bitflips no fio se utilizar http em vez de https como https (a predefinição) já irá validar. Tenha em atenção que este hash MD5 não é armazenado com o ficheiro.

file_last_write_mode
Literal["preserve", "now"]

Se a hora da última escrita do ficheiro tiver de ser preservada ou substituída. Os valores possíveis são "preserve" ou "now". Se não for especificado, a hora da última escrita do ficheiro será alterada para a data/hora atual.

Novidade na versão 12.8.0: este parâmetro foi introduzido na versão da API "2021-06-08".

lease
ShareLeaseClient ou str

Necessário se o ficheiro tiver uma concessão ativa. O valor pode ser um objeto ShareLeaseClient ou o ID de concessão como uma cadeia.

Novidades na versão 12.1.0.

timeout
int

Define o tempo limite do lado do servidor para a operação em segundos. Para obter mais detalhes, veja https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations. Este valor não é monitorizado nem validado no cliente. Para configurar tempos limite de rede do lado do cliente, veja aqui.

encoding
str

A predefinição é UTF-8.

Devoluções

Dict da propriedade atualizada por ficheiros (Etag e última modificação).

Tipo de retorno

Dict[str, Any]

upload_range_from_url

Escreve os bytes de um ponto final de Ficheiro do Azure no intervalo especificado de outro ponto final de Ficheiro do Azure.

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

Parâmetros

offset
int
Necessário

Início do intervalo de bytes a utilizar para atualizar uma secção do ficheiro. O intervalo pode ter até 4 MB de tamanho.

length
int
Necessário

Número de bytes a utilizar para atualizar uma secção do ficheiro. O intervalo pode ter até 4 MB de tamanho.

source_url
str
Necessário

Um URL com até 2 KB de comprimento que especifica um ficheiro ou blob do Azure. O valor deve ser codificado por URL, uma vez que apareceria num URI de pedido. Se a origem estiver noutra conta, a origem tem de ser pública ou tem de ser autenticada através de uma assinatura de acesso partilhado. Se a origem for pública, não é necessária autenticação. Exemplos: https://myaccount.file.core.windows.net/myshare/mydir/myfilehttps://otheraccount.file.core.windows.net/myshare/mydir/myfile?sastoken

source_offset
int
Necessário

Isto indica o início do intervalo de bytes(inclusive) que tem de ser retirado da origem de cópia. O serviço irá ler o mesmo número de bytes que o intervalo de destino (desvio de comprimento).

source_if_modified_since
datetime

Um valor DateTime. O Azure espera que o valor de data transmitido seja UTC. Se o fuso horário estiver incluído, quaisquer datetimes não UTC serão convertidos em UTC. Se uma data for transmitida sem informações de fuso horário, assume-se que é UTC. Especifique este cabeçalho condicional para copiar o blob apenas se o blob de origem tiver sido modificado desde a data/hora especificada.

source_if_unmodified_since
datetime

Um valor DateTime. O Azure espera que o valor de data transmitido seja UTC. Se o fuso horário estiver incluído, quaisquer datetimes não UTC serão convertidos em UTC. Se uma data for transmitida sem informações de fuso horário, assume-se que é UTC. Especifique este cabeçalho condicional para copiar o blob apenas se o blob de origem não tiver sido modificado desde a data/hora especificada.

source_etag
str

O valor ETag de origem ou o caráter universal (*). Utilizado para verificar se o recurso foi alterado e agir de acordo com a condição especificada pelo parâmetro match_condition .

source_match_condition
MatchConditions

A condição de correspondência de origem a utilizar no etag.

file_last_write_mode
Literal["preserve", "now"]

Se a hora da última escrita do ficheiro tiver de ser preservada ou substituída. Os valores possíveis são "preserve" ou "now". Se não for especificado, a hora da última escrita do ficheiro será alterada para a data/hora atual.

Novidade na versão 12.8.0: este parâmetro foi introduzido na versão da API "2021-06-08".

lease
ShareLeaseClient ou str

Necessário se o ficheiro tiver uma concessão ativa. O valor pode ser um objeto ShareLeaseClient ou o ID de concessão como uma cadeia.

Novidades na versão 12.1.0.

timeout
int

Define o tempo limite do lado do servidor para a operação em segundos. Para obter mais detalhes, veja https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations. Este valor não é monitorizado nem validado no cliente. Para configurar tempos limite de rede do lado do cliente, veja aqui.

source_authorization
str

Autenticar como principal de serviço utilizando um segredo de cliente para aceder a um blob de origem. Certifique-se de que "portador" é o prefixo da cadeia de source_authorization.

Atributos

api_version

A versão da API de Armazenamento utilizada para pedidos.

location_mode

O modo de localização que o cliente está a utilizar atualmente.

Por predefinição, será "principal". As opções incluem "principal" e "secundário".

primary_endpoint

O URL completo do ponto final primário.

primary_hostname

O nome do anfitrião do ponto final primário.

secondary_endpoint

O URL completo do ponto final secundário, se configurado.

Se não estiver disponível, será gerado um ValueError. Para especificar explicitamente um nome de anfitrião secundário, utilize o argumento opcional secondary_hostname palavra-chave na instanciação.

Exceções

ValueError

secondary_hostname

O nome do anfitrião do ponto final secundário.

Se não estiver disponível, será Nenhum. Para especificar explicitamente um nome de anfitrião secundário, utilize o argumento opcional secondary_hostname palavra-chave na instanciação.

url

O URL de ponto final completo para esta entidade, incluindo o token de SAS, se utilizado.

Este pode ser o ponto final primário ou o ponto final secundário, dependendo do atual location_mode. :returns: o URL de ponto final completo para esta entidade, incluindo o token de SAS, se utilizado. :rtype: str