Biblioteca de cliente da Partilha de Ficheiros de Armazenamento do Azure para Python – versão 12.15.0

  • Artigo

O armazenamento da Partilha de Ficheiros do Azure oferece partilhas de ficheiros totalmente geridas na cloud que são acessíveis através do protocolo SMB (Server Message Block) padrão da indústria. As partilhas de ficheiros do Azure podem ser montadas em simultâneo por implementações na cloud ou no local do Windows, Linux e macOS. Além disso, as partilhas de ficheiros do Azure podem ser colocadas em cache em Servidores Windows com o Azure File Sync para acesso rápido perto do local onde os dados estão a ser utilizados.

As partilhas de ficheiros do Azure podem ser utilizadas para:

  • Substituir ou complementar servidores de ficheiros no local
  • Aplicações "lift-and-shift"
  • Simplificar o desenvolvimento na cloud com definições de aplicações partilhadas, partilha de diagnósticos e ferramentas de Dev/Test/Debug

Código fonte | Pacote (PyPI) | Pacote (Conda) | Documentação | de referência da APIDocumentação do | produtoExemplos

Introdução

Pré-requisitos

Instalar o pacote

Instale a biblioteca de cliente da Partilha de Ficheiros de Armazenamento do Azure para Python com pip:

pip install azure-storage-file-share

Criar uma conta de armazenamento

Se quiser criar uma nova conta de armazenamento, pode utilizar o Portal do Azure, Azure PowerShell ou a CLI do Azure:

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

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

Criar o cliente

A biblioteca de cliente da Partilha de Ficheiros de Armazenamento do Azure para Python permite-lhe interagir com quatro tipos de recursos: a própria conta de armazenamento, partilhas de ficheiros, diretórios e ficheiros. A interação com estes recursos começa com uma instância de um cliente. Para criar um objeto de cliente, precisará do URL do serviço de ficheiros da conta de armazenamento e de uma credencial que lhe permita aceder à conta de armazenamento:

from azure.storage.fileshare import ShareServiceClient

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

Procurar o URL da conta

Pode encontrar o URL do serviço de ficheiros da conta de armazenamento com o Portal do Azure, Azure PowerShell ou a CLI do Azure:

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

Tipos de credenciais

O credential parâmetro pode ser fornecido em vários formulários diferentes, consoante o tipo de autorização que pretende utilizar:

  1. Para utilizar um token de assinatura de acesso partilhado (SAS), forneça o token como uma cadeia. Se o URL da conta incluir o token de SAS, omita o parâmetro de credencial. Pode gerar um token de SAS a partir do Portal do Azure em "Assinatura de acesso partilhado" ou utilizar uma das generate_sas() funções para criar um token sas para a conta de armazenamento, partilha ou ficheiro:

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

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

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

  2. Para utilizar uma chave partilhada de conta de armazenamento (também conhecida como chave de conta ou chave de acesso), forneça a chave como uma cadeia. Isto pode ser encontrado no Portal do Azure na secção "Chaves de Acesso" ou ao executar o seguinte comando da CLI do Azure:

    az storage account keys list -g MyResourceGroup -n MyStorageAccount

    Utilize a chave como o parâmetro de credencial para autenticar o cliente:

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

Criar o cliente a partir de um cadeia de ligação

Dependendo do seu caso de utilização e do método de autorização, pode preferir inicializar uma instância de cliente com um cadeia de ligação de armazenamento em vez de fornecer o URL e a credencial da conta separadamente. Para tal, transmita o cadeia de ligação de armazenamento para o método de classe do from_connection_string cliente:

from azure.storage.fileshare import ShareServiceClient

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

O cadeia de ligação para a sua conta de armazenamento pode ser encontrado no Portal do Azure na secção "Chaves de Acesso" ou ao executar o seguinte comando da CLI:

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

Conceitos-chave

Os seguintes componentes compõem o Serviço de Partilha de Ficheiros do Azure:

  • A própria conta de armazenamento
  • Uma partilha de ficheiros na conta de armazenamento
  • Uma hierarquia opcional de diretórios na partilha de ficheiros
  • Um ficheiro na partilha de ficheiros, que pode ter até 1 TiB de tamanho

A biblioteca de cliente da Partilha de Ficheiros de Armazenamento do Azure para Python permite-lhe interagir com cada um destes componentes através da utilização de um objeto de cliente dedicado.

Clientes Assíncrono

Esta biblioteca inclui uma API assíncrona completa suportada no Python 3.5+. Para utilizá-lo, primeiro tem de instalar um transporte assíncrono, como aiohttp. Veja a documentação do azure-core para obter mais informações.

Os clientes assíncronas e as credenciais devem ser fechados quando já não forem necessários. Estes objetos são gestores de contexto assíncrono e definem métodos assíncrono close .

Clientes

São fornecidos quatro clientes diferentes para interagir com os vários componentes do Serviço de Partilha de Ficheiros:

  1. ShareServiceClient – este cliente representa a interação com a própria conta de armazenamento do Azure e permite-lhe adquirir instâncias de cliente pré-configuradas para aceder às partilhas de ficheiros no seu interior. Fornece operações para obter e configurar as propriedades do serviço, bem como listar, criar e eliminar partilhas na conta. Para realizar operações numa partilha específica, obtenha um cliente com o get_share_client método .
  2. ShareClient – este cliente representa a interação com uma partilha de ficheiros específica (que ainda não precisa de existir) e permite-lhe adquirir instâncias de cliente pré-configuradas para aceder aos diretórios e ficheiros no seu interior. Fornece operações para criar, eliminar, configurar ou criar instantâneos de uma partilha e inclui operações para criar e enumerar os conteúdos dos diretórios na mesma. Para efetuar operações num diretório ou ficheiro específico, obtenha um cliente com os get_directory_client métodos ou get_file_client .
  3. ShareDirectoryClient – este cliente representa a interação com um diretório específico (que ainda não precisa de existir). Fornece operações para criar, eliminar ou enumerar os conteúdos de um subdiretório imediato ou aninhado e inclui operações para criar e eliminar ficheiros no mesmo. Para operações relacionadas com um subdiretório ou ficheiro específico, um cliente para essa entidade também pode ser obtido com as get_subdirectory_client funções e get_file_client .
  4. ShareFileClient – este cliente representa a interação com um ficheiro específico (que ainda não precisa de existir). Fornece operações para carregar, transferir, criar, eliminar e copiar um ficheiro.

Para obter detalhes sobre as restrições de nomenclatura de caminhos, veja Nomenclatura e Referência de Partilhas, Diretórios, Ficheiros e Metadados.

Exemplos

As secções seguintes fornecem vários fragmentos de código que abrangem algumas das tarefas mais comuns da Partilha de Ficheiros de Armazenamento, incluindo:

Criar uma partilha de ficheiros

Criar uma partilha de ficheiros para armazenar os seus ficheiros

from azure.storage.fileshare import ShareClient

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

Utilizar o cliente assíncrono para criar uma partilha de ficheiros

from azure.storage.fileshare.aio import ShareClient

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

Carregar um ficheiro

Carregar um ficheiro para a partilha

from azure.storage.fileshare import ShareFileClient

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

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

Carregar um ficheiro de forma assíncrona

from azure.storage.fileshare.aio import ShareFileClient

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

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

Transferir um ficheiro

Transferir um ficheiro a partir da partilha

from azure.storage.fileshare import ShareFileClient

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

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

Transferir um ficheiro de forma assíncrona

from azure.storage.fileshare.aio import ShareFileClient

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

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

Listar conteúdos de um diretório

Listar todos os diretórios e ficheiros num diretório principal

from azure.storage.fileshare import ShareDirectoryClient

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

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

Listar conteúdos de um diretório de forma assíncrona

from azure.storage.fileshare.aio import ShareDirectoryClient

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

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

Configuração opcional

Argumentos de palavra-chave opcionais que podem ser transmitidos ao nível do cliente e por operação.

Configuração da Política de Repetição

Utilize os seguintes argumentos de palavra-chave ao instanciar um cliente para configurar a política de repetição:

  • retry_total (int): número total de tentativas a permitir. Tem precedência sobre outras contagens. retry_total=0 Transmita se não quiser repetir os pedidos. A predefinição é 10.
  • retry_connect (int): quantos erros relacionados com a ligação podem repetir. A predefinição é 3.
  • retry_read (int): quantas vezes repetir erros de leitura. A predefinição é 3.
  • retry_status (int): quantas vezes tentar novamente em códigos de estado incorretos. A predefinição é 3.
  • retry_to_secondary (bool): se o pedido deve ser repetido novamente para secundário, se possível. Esta ação só deve ser ativada para as contas RA-GRS e podem ser processados dados potencialmente obsoletos. Predefinições para False.

Outra configuração de cliente/por operação

Outros argumentos de palavra-chave de configuração opcionais que podem ser especificados no cliente ou por operação.

Argumentos de palavra-chave do cliente:

  • connection_timeout (int): o número de segundos que o cliente aguardará para estabelecer uma ligação ao servidor. A predefinição é de 20 segundos.
  • read_timeout (int): o número de segundos que o cliente aguardará, entre operações de leitura consecutivas, para obter uma resposta do servidor. Trata-se de um tempo limite ao nível do socket e não é afetado pelo tamanho geral dos dados. Os tempos limite de leitura do lado do cliente serão repetidos automaticamente. A predefinição é de 60 segundos.
  • transporte (Qualquer): transporte fornecido pelo utilizador para enviar o pedido HTTP.

Argumentos de palavra-chave por operação:

  • raw_response_hook (callable): a chamada de retorno dada utiliza a resposta devolvida pelo serviço.
  • raw_request_hook (callable): a chamada de retorno especificada utiliza o pedido antes de ser enviado para o serviço.
  • client_request_id (str): identificação especificada pelo utilizador opcional do pedido.
  • user_agent (str): acrescenta o valor personalizado ao cabeçalho user-agent a ser enviado com o pedido.
  • logging_enable (bool): ativa o registo ao nível de DEBUG. Predefinições para Falso. Também pode ser transmitido ao nível do cliente para ativá-lo para todos os pedidos.
  • logging_body (bool): ativa o registo do pedido e do corpo da resposta. Predefinições para Falso. Também pode ser transmitido ao nível do cliente para ativá-lo para todos os pedidos.
  • cabeçalhos (dict): transmita cabeçalhos personalizados como chave, pares de valores. Por exemplo, headers={'CustomValue': value}

Resolução de problemas

Geral

Os clientes do Ficheiro de Armazenamento geram exceções definidas no Azure Core.

Esta lista pode ser utilizada para referência para obter exceções geradas. Para obter o código de erro específico da exceção, utilize o error_code atributo, ou seja, exception.error_code.

Registo

Esta biblioteca utiliza a biblioteca de registos padrão para registos. As informações básicas sobre as sessões HTTP (URLs, cabeçalhos, etc.) são registadas ao nível da INFORMAÇÃO.

O registo ao nível de DEBUG detalhado, incluindo corpos de pedido/resposta e cabeçalhos não retotados, pode ser ativado num cliente com o logging_enable argumento:

import sys
import logging
from azure.storage.fileshare import ShareServiceClient

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

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

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

Da mesma forma, logging_enable pode ativar o registo detalhado para uma única operação, mesmo quando não está ativado para o cliente:

service_client.get_service_properties(logging_enable=True)

Passos seguintes

Mais código de exemplo

Introdução aos nossos exemplos de Partilha de Ficheiros.

Estão disponíveis vários exemplos do SDK Python da Partilha de Ficheiros de Armazenamento no repositório do GitHub do SDK. Estes exemplos fornecem código de exemplo para cenários adicionais normalmente encontrados ao trabalhar com a Partilha de Ficheiros de Armazenamento:

Documentação adicional

Para obter documentação mais extensa sobre o armazenamento da Partilha de Ficheiros do Azure, veja a documentação de armazenamento da Partilha de Ficheiros do Azure sobre docs.microsoft.com.

Contribuir

Agradecemos todas as contribuições e sugestões para este projeto. A maioria das contribuições requerem que celebre um Contrato de Licença de Contribuição (CLA) no qual se declare que tem o direito de conceder e que, na verdade, concede-nos os direitos para utilizar a sua contribuição. Para mais detalhes, visite https://cla.microsoft.com.

Quando submete um pedido Pull, um bot do CLA determina automaticamente se tem de fornecer um CLA e decorar o PR de forma adequada (por exemplo, etiqueta, comentário). Só tem de seguir as instruções fornecidas pelo bot. Apenas terá de fazer isto uma vez em todos os repositórios com o nosso CLA.

Este projeto adotou o Microsoft Open Source Code of Conduct (Código de Conduta do Microsoft Open Source). Para obter mais informações, consulte as FAQ do Código de Conduta ou o contacto opencode@microsoft.com com quaisquer perguntas ou comentários adicionais.