ShareDirectoryClient Classe

Referência

Um cliente para interagir com um diretório específico, embora ainda não exista.

Para operações relacionadas a um subdiretório ou arquivo específico nesse compartilhamento, os clientes dessas entidades também podem ser recuperados usando as get_subdirectory_client funções e get_file_client .

Para obter mais configurações opcionais, clique aqui.

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

ShareDirectoryClient

Construtor

ShareDirectoryClient(account_url: str, share_name: str, directory_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

Obrigatório

O URI para a conta de armazenamento. Para criar um cliente dado o URI completo para o diretório, use o from_directory_url classmethod.

share_name: str

Obrigatório

O nome do compartilhamento para o diretório.

directory_path: str

Obrigatório

O caminho do diretório para o diretório com o qual interagir. Se especificado, esse valor substituirá um valor de diretório especificado na URL do diretório.

snapshot: str

valor padrão: None

Um compartilhamento opcional instantâneo no qual operar. Pode ser a cadeia de caracteres de ID instantâneo ou a resposta retornada de create_snapshot.

credential

valor padrão: None

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

exceto no caso de AzureSasCredential, em que os tokens SAS conflitantes gerarão um ValueError. Se estiver usando uma instância de AzureNamedKeyCredential, "name" deverá ser o nome da conta de armazenamento e "key" deverá ser a chave da conta de armazenamento.

token_intent: Literal['backup']

Necessário ao usar TokenCredential para autenticação e ignorado para outras formas de autenticação. Especifica a intenção para todas as solicitações ao usar a autenticação TokenCredential . Os valores possíveis são:

backup – especifica que as solicitações são destinadas a operações de tipo de backup/administrador, o que significa que todas as ACLs de arquivo/diretório são ignoradas e permissões completas são concedidas. O usuário também deve ter a permissão RBAC necessária.

allow_trailing_dot: bool

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

allow_source_trailing_dot: bool

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

api_version: str

A versão da API de Armazenamento a ser usada para solicitações. O valor padrão é a versão de serviço mais recente compatível com o SDK atual. A configuração para uma versão mais antiga pode resultar em redução da compatibilidade de recursos.

Novo na versão 12.1.0.

secondary_hostname: str

O nome do host do ponto de extremidade secundário.

max_range_size: int

O tamanho máximo do intervalo usado para um upload de arquivo. O padrão é 4*1024*1024.

audience: str

O público-alvo a ser usado ao solicitar tokens para autenticação do Azure Active Directory. Só tem efeito quando a credencial é do tipo TokenCredential. O valor pode ser https://storage.azure.com/ (padrão) ou https://.file.core.windows.net.

Métodos

close	Esse método é para fechar os soquetes abertos pelo cliente. Ele não precisa ser usado ao usar com um gerenciador de contexto.
close_all_handles	Feche todos os identificadores de arquivo abertos. Essa operação será bloqueada até que o serviço feche todos os identificadores abertos.
close_handle	Feche um identificador de arquivo aberto.
create_directory	Cria um novo diretório no diretório referenciado pelo cliente.
create_subdirectory	Cria um novo subdiretório e retorna um cliente para interagir com o subdiretório.
delete_directory	Marca o diretório para exclusão. O diretório é posteriormente excluído durante a coleta de lixo.
delete_file	Marca o arquivo especificado para exclusão. O arquivo é posteriormente excluído durante a coleta de lixo.
delete_subdirectory	Exclui um subdiretório.
exists	Retornará True se houver um diretório e retornar False caso contrário.
from_connection_string	Crie ShareDirectoryClient a partir de uma cadeia de conexão.
from_directory_url	Crie um ShareDirectoryClient a partir de uma URL de diretório.
get_directory_properties	Retorna todos os metadados definidos pelo usuário e as propriedades do sistema para o diretório especificado. Os dados retornados não incluem a lista de arquivos do diretório.
get_file_client	Faça com que um cliente interaja com um arquivo específico. O arquivo ainda não precisa existir.
get_subdirectory_client	Faça com que um cliente interaja com um subdiretório específico. O subdiretório ainda não precisa existir.
list_directories_and_files	Lista todos os diretórios e arquivos no diretório .
list_handles	Lista identificadores abertos em um diretório ou um arquivo no diretório.
rename_directory	Renomeie o diretório de origem. :p aramtype file_attributes:~azure.storage.fileshare.NTFSAttributes ou str :palavra-chave file_creation_time: Tempo de criação para o diretório. :p aramtype file_creation_time:~datetime.datetime ou str :palavra-chave file_last_write_time: Hora da última gravação do arquivo. :p aramtype file_last_write_time:~datetime.datetime ou str :palavra-chave file_change_time: Altere o tempo para o diretório. Se não for especificado, a hora da alteração será definida como a data/hora atual. Novo na versão 12.8.0: esse parâmetro foi introduzido na versão da API '2021-06-08'.
set_directory_metadata	Define os metadados do diretório. Cada chamada para essa operação substitui todos os metadados existentes anexados ao diretório. Para remover todos os metadados do diretório, chame essa operação com um ditado de metadados vazio.
set_http_headers	Define cabeçalhos HTTP no diretório.
upload_file	Cria um novo arquivo no diretório e retorna um ShareFileClient para interagir com o arquivo.

close

Esse método é para fechar os soquetes abertos pelo cliente. Ele não precisa ser usado ao usar com um gerenciador de contexto.

close()

close_all_handles

Feche todos os identificadores de arquivo abertos.

Essa operação será bloqueada até que o serviço feche todos os identificadores abertos.

close_all_handles(recursive: bool = False, **kwargs: Any) -> Dict[str, int]

Parâmetros

recursive: bool

Obrigatório

Booliano que especifica se a operação deve ser aplicada ao diretório especificado pelo cliente, seus arquivos, seus subdiretórios e seus arquivos. O valor padrão é Falso.

timeout: int

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

Retornos

O número de identificadores fechados (pode ser 0 se o identificador especificado não foi encontrado) e o número de identificadores não foi fechado em um dict.

Tipo de retorno

dict[str, int]

close_handle

Feche um identificador de arquivo aberto.

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

Parâmetros

handle: str ou Handle

Obrigatório

Um identificador específico a ser fechado.

timeout: int

Retornos

O número de identificadores fechados (pode ser 0 se o identificador especificado não foi encontrado) e o número de identificadores não foi fechado em um dict.

Tipo de retorno

dict[str, int]

create_directory

Cria um novo diretório no diretório referenciado pelo cliente.

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

Parâmetros

file_attributes: NTFSAttributes

Os atributos do sistema de arquivos para arquivos e diretórios. Se não for definido, o valor padrão será "none" e os atributos serão definidos como "Archive". Aqui está um exemplo de quando o tipo var é str: 'Temporary|Arquivar'. file_attributes valor não diferencia maiúsculas de minúsculas.

file_creation_time: str ou datetime

Hora de criação do diretório. Valor padrão: "now".

file_last_write_time: str ou datetime

Hora da última gravação do diretório. Valor padrão: "now".

file_permission: str

Se especificado, a permissão (descritor de segurança) deverá ser definida para o diretório/arquivo. Esse cabeçalho poderá ser usado se Permission size for <= 8KB, caso contrário, o cabeçalho file-permission-key deverá ser usado. Valor padrão: Herdar. Se SDDL for especificado como entrada, ele deverá ter proprietário, grupo e dacl. Observação: apenas uma das permissões de arquivo ou chave de permissão de arquivo deve ser especificada.

file_permission_key: str

Chave da permissão a ser definida para o diretório/arquivo. Observação: apenas uma das permissões de arquivo ou chave de permissão de arquivo deve ser especificada.

file_change_time: str ou datetime

Altere o tempo para o diretório. Se não for especificado, a hora da alteração será definida como a data/hora atual.

Novo na versão 12.8.0: esse parâmetro foi introduzido na versão da API '2021-06-08'.

metadata: dict(str,str)

Pares nome-valor associados ao diretório como metadados.

timeout: int

Retornos

Dict de propriedade atualizado pelo diretório (Etag e última modificação).

Tipo de retorno

dict(str, Any)

Exemplos

Cria um diretório.


   my_directory.create_directory()

create_subdirectory

Cria um novo subdiretório e retorna um cliente para interagir com o subdiretório.

create_subdirectory(directory_name: str, **kwargs) -> ShareDirectoryClient

Parâmetros

directory_name: str

Obrigatório

O nome do subdiretório.

metadata: dict(str,str)

Pares nome-valor associados ao subdiretório como metadados.

timeout: int

Retornos

ShareDirectoryClient

Tipo de retorno

ShareDirectoryClient

Exemplos

Crie um subdiretório.


   # Create the directory
   parent_dir.create_directory()

   # Create a subdirectory
   subdir = parent_dir.create_subdirectory("subdir")

delete_directory

Marca o diretório para exclusão. O diretório é posteriormente excluído durante a coleta de lixo.

delete_directory(**kwargs: Any) -> None

Parâmetros

timeout: int

Tipo de retorno

None

Exemplos

Exclui um diretório.


   my_directory.delete_directory()

delete_file

Marca o arquivo especificado para exclusão. O arquivo é posteriormente excluído durante a coleta de lixo.

delete_file(file_name: str, **kwargs: Any | None) -> None

Parâmetros

file_name: str

Obrigatório

O nome do arquivo a ser excluído.

timeout: int

Tipo de retorno

None

Exemplos

Exclua um arquivo em um diretório.


   # Delete the file in the directory
   my_directory.delete_file(file_name="sample")

delete_subdirectory

Exclui um subdiretório.

delete_subdirectory(directory_name: str, **kwargs) -> None

Parâmetros

directory_name: str

Obrigatório

O nome do subdiretório.

timeout: int

Tipo de retorno

None

Exemplos

Exclua um subdiretório.


   parent_dir.delete_subdirectory("subdir")

exists

Retornará True se houver um diretório e retornar False caso contrário.

exists(**kwargs: Any) -> bool

Parâmetros

timeout: int

Retornos

True se o diretório existir, False caso contrário.

Tipo de retorno

bool

from_connection_string

Crie ShareDirectoryClient a partir de uma cadeia de conexão.

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

Parâmetros

conn_str: str

Obrigatório

Um cadeia de conexão para uma conta de Armazenamento do Azure.

share_name: str

Obrigatório

O nome do compartilhamento.

directory_path: str

Obrigatório

O caminho do diretório.

credential

valor padrão: None

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

exceto no caso do AzureSasCredential, em que os tokens SAS conflitantes gerarão um ValueError. Se estiver usando uma instância do AzureNamedKeyCredential, "name" deverá ser o nome da conta de armazenamento e "key" deverá ser a chave da conta de armazenamento.

audience: str

O público-alvo a ser usado ao solicitar 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/ (padrão) ou https://.file.core.windows.net.

Retornos

Um cliente de diretório.

Tipo de retorno

ShareDirectoryClient

from_directory_url

Crie um ShareDirectoryClient a partir de uma URL de diretório.

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

Parâmetros

directory_url: str

Obrigatório

O URI completo para o diretório.

snapshot: str

valor padrão: None

Um compartilhamento opcional instantâneo no qual operar. Esse pode ser o instantâneo cadeia de caracteres de ID ou a resposta retornada de create_snapshot.

credential

valor padrão: None

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

exceto no caso do AzureSasCredential, em que os tokens SAS conflitantes gerarão um ValueError. Se estiver usando uma instância do AzureNamedKeyCredential, "name" deverá ser o nome da conta de armazenamento e "key" deverá ser a chave da conta de armazenamento.

audience: str

Retornos

Um cliente de diretório.

Tipo de retorno

ShareDirectoryClient

get_directory_properties

Retorna todos os metadados definidos pelo usuário e as propriedades do sistema para o diretório especificado. Os dados retornados não incluem a lista de arquivos do diretório.

get_directory_properties(**kwargs: Any) -> DirectoryProperties

Parâmetros

timeout: int

Retornos

DirectoryProperties

Tipo de retorno

DirectoryProperties

get_file_client

Faça com que um cliente interaja com um arquivo específico.

O arquivo ainda não precisa existir.

get_file_client(file_name: str, **kwargs: Any) -> ShareFileClient

Parâmetros

file_name: str

Obrigatório

O nome do arquivo.

Retornos

Um cliente de arquivo.

Tipo de retorno

ShareFileClient

get_subdirectory_client

Faça com que um cliente interaja com um subdiretório específico.

O subdiretório ainda não precisa existir.

get_subdirectory_client(directory_name: str, **kwargs: Any) -> ShareDirectoryClient

Parâmetros

directory_name: str

Obrigatório

O nome do subdiretório.

Retornos

Um cliente de diretório.

Tipo de retorno

ShareDirectoryClient

Exemplos

Obtém o cliente subdiretório.


   # Get a directory client and create the directory
   parent = share.get_directory_client("dir1")
   parent.create_directory()

   # Get a subdirectory client and create the subdirectory "dir1/dir2"
   subdirectory = parent.get_subdirectory_client("dir2")
   subdirectory.create_directory()

list_directories_and_files

Lista todos os diretórios e arquivos no diretório .

list_directories_and_files(name_starts_with: str | None = None, **kwargs: Any) -> ItemPaged

Parâmetros

name_starts_with: str

Obrigatório

Filtra os resultados para retornar apenas entidades cujos nomes começam com o prefixo especificado.

include: list[str]

Inclua esse parâmetro para especificar um ou mais conjuntos de dados a serem incluídos na resposta. Os valores str possíveis são "carimbos de data/hora", "Etag", "Atributos", "PermissionKey".

Novo na versão 12.6.0.

Esse argumento palavra-chave foi introduzido na versão da API '2020-10-02'.

include_extended_info: bool

Se isso for definido como true, a ID do arquivo será retornada nos resultados listados.

Novo na versão 12.6.0.

Esse argumento palavra-chave foi introduzido na versão da API '2020-10-02'.

timeout: int

Retornos

Um iterável de paginação automática de DirectoryProperties e FileProperties semelhantes a ditados

Tipo de retorno

ItemPaged[DirectoryProperties <xref:and> FileProperties]

Exemplos

Listar diretórios e arquivos.


   # List the directories and files under the parent directory
   my_list = list(parent_dir.list_directories_and_files())
   print(my_list)

list_handles

Lista identificadores abertos em um diretório ou um arquivo no diretório.

list_handles(recursive: bool = False, **kwargs: Any) -> ItemPaged[Handle]

Parâmetros

recursive: bool

Obrigatório

Boolean que especifica se a operação deve ser aplicada ao diretório especificado pelo cliente, seus arquivos, seus subdiretórios e seus arquivos. O valor padrão é Falso.

timeout: int

Retornos

Uma iteração de paginação automática do Identificador

Tipo de retorno

ItemPaged[Handle]

rename_directory

Renomeie o diretório de origem.

:p aramtype file_attributes:~azure.storage.fileshare.NTFSAttributes ou str :palavra-chave file_creation_time:

Tempo de criação para o diretório.

:p aramtype file_creation_time:~datetime.datetime ou str :palavra-chave file_last_write_time:

Hora da última gravação do arquivo.

:p aramtype file_last_write_time:~datetime.datetime ou str :palavra-chave file_change_time:

Altere o tempo para o diretório. Se não for especificado, a hora da alteração será definida como a data/hora atual.

Novo na versão 12.8.0: esse parâmetro foi introduzido na versão da API '2021-06-08'.

rename_directory(new_name: str, **kwargs: Any) -> ShareDirectoryClient

Parâmetros

metadata: Dict[str,str]

Um par nome-valor a ser associado a um objeto de armazenamento de arquivos.

destination_lease: ShareLeaseClient ou str

Obrigatório se o arquivo de destino tiver uma concessão ativa. O valor pode ser um objeto ShareLeaseClient ou a ID de concessão como uma cadeia de caracteres.

Retornos

O novo Cliente de Diretório.

Tipo de retorno

ShareDirectoryClient

set_directory_metadata

Define os metadados do diretório.

Cada chamada para essa operação substitui todos os metadados existentes anexados ao diretório. Para remover todos os metadados do diretório, chame essa operação com um ditado de metadados vazio.

set_directory_metadata(metadata: Dict[str, Any], **kwargs: Any) -> Dict[str, Any]

Parâmetros

metadata: dict(str, str)

Obrigatório

Pares nome-valor associados ao diretório como metadados.

timeout: int

Retornos

Ditado de propriedade atualizado pelo diretório (Etag e última modificação).

Tipo de retorno

dict(str, Any)

set_http_headers

Define cabeçalhos HTTP no diretório.

set_http_headers(file_attributes: str | NTFSAttributes = 'none', 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

file_attributes: NTFSAttributes

Obrigatório

Os atributos do sistema de arquivos para arquivos e diretórios. Se não estiver definido, indicará a preservação dos valores existentes. Aqui está um exemplo de quando o tipo var é str: 'Temporário|Arquivo'

file_creation_time: str ou datetime

Obrigatório

Hora de criação do arquivo Valor padrão: Preservar.

file_last_write_time: str ou datetime

Obrigatório

Hora da última gravação do arquivo Valor padrão: Preservar.

file_permission: str

Obrigatório

Se especificado, a permissão (descritor de segurança) será definida para o diretório/arquivo. Esse cabeçalho poderá ser usado se o tamanho da permissão for <= 8KB, caso contrário, o cabeçalho x-ms-file-permission-key será usado. Valor padrão: Herdar. Se o SDDL for especificado como entrada, ele deverá ter proprietário, grupo e dacl. Observação: apenas um dos x-ms-file-permission ou x-ms-file-permission-key deve ser especificado.

permission_key: str

Obrigatório

Chave da permissão a ser definida para o diretório/arquivo. Observação: apenas um dos x-ms-file-permission ou x-ms-file-permission-key deve ser especificado.

file_change_time: str ou datetime

Altere o tempo para o diretório. Se não for especificado, a hora da alteração será definida como a data/hora atual.

Novo na versão 12.8.0: esse parâmetro foi introduzido na versão da API '2021-06-08'.

timeout: int

Retornos

Ditado de propriedade atualizado por arquivo (Etag e última modificação).

Tipo de retorno

dict(str, Any)

upload_file

Cria um novo arquivo no diretório e retorna um ShareFileClient para interagir com o arquivo.

upload_file(file_name: str, data: bytes | str | Iterable | IO, length: int | None = None, **kwargs) -> ShareFileClient

Parâmetros

file_name: str

Obrigatório

O nome do arquivo.

data

Obrigatório

Conteúdo do arquivo.

length: int

Obrigatório

Comprimento do arquivo em bytes. Especifique seu tamanho máximo, até 1 TiB.

metadata: dict(str,str)

Pares de nome-valor associados ao arquivo como metadados.

content_settings: ContentSettings

Objeto ContentSettings usado para definir propriedades de arquivo. Usado para definir o tipo de conteúdo, codificação, idioma, disposição, md5 e controle de cache.

validate_content: bool

Se for true, calculará um hash MD5 para cada intervalo do arquivo. O serviço de armazenamento verifica o hash do conteúdo que chegou com o hash que foi enviado. Isso é importante principalmente para detectar bitflips no fio se o uso de http em vez de https como https (o padrão) já validará. Observe que esse hash MD5 não é armazenado com o arquivo .

max_concurrency: int

Número máximo de conexões paralelas a serem usadas.

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

Um retorno de chamada para acompanhar o progresso de um upload de execução prolongada. A assinatura é function(current: int, total: Optional[int]) em que current é o número de bytes transferidos até agora, e total é o tamanho do blob ou Nenhum se o tamanho for desconhecido.

timeout: int

encoding: str

O padrão é UTF-8.

Retornos

ShareFileClient

Tipo de retorno

ShareFileClient

Exemplos

Carregue um arquivo em um diretório.


   # Upload a file to the directory
   with open(SOURCE_FILE, "rb") as source:
       my_directory.upload_file(file_name="sample", data=source)

Atributos

api_version

A versão da API de Armazenamento usada para solicitações.

location_mode

O modo de localização que o cliente está usando no momento.

Por padrão, isso será "primário". As opções incluem "primário" e "secundário".

primary_endpoint

A URL completa do ponto de extremidade primário.

primary_hostname

O nome do host do ponto de extremidade primário.

secondary_endpoint

A URL completa do ponto de extremidade secundário, se configurada.

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

Exceções

ValueError

secondary_hostname

O nome do host do ponto de extremidade secundário.

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

url

A URL completa do ponto de extremidade para essa entidade, incluindo o token SAS, se usado.

Isso pode ser o ponto de extremidade primário ou o ponto de extremidade secundário, dependendo do atual location_mode. :returns: a URL completa do ponto de extremidade para essa entidade, incluindo o token SAS, se usado. :rtype: str