Biblioteca de clientes do Compartilhamento de Arquivos do Armazenamento do Azure para Python – versão 12.15.0

  • Artigo

O Armazenamento de Compartilhamento de Arquivos do Azure oferece compartilhamentos de arquivos totalmente gerenciados na nuvem que podem ser acessados por meio do protocolo SMB padrão do setor. Os compartilhamentos de arquivos do Azure podem ser montados de maneira simultânea por implantações locais ou na nuvem do Windows, do Linux e do MacOS. Além disso, os compartilhamentos de arquivos do Azure podem ser armazenados em cache nos Windows Servers com a Sincronização de Arquivos do Azure para acesso rápido perto de onde os dados estão sendo usados.

Os compartilhamentos de arquivos do Azure podem ser usados para:

  • Substituir ou complementar os servidores de arquivos locais
  • Aplicativos "lift and shift"
  • Simplificar o desenvolvimento em nuvem com as configurações de aplicativo compartilhado, o compartilhamento de diagnóstico e as ferramentas de Desenvolvimento/Teste/Depuração

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

Introdução

Pré-requisitos

Instalar o pacote

Instale a biblioteca de clientes do Compartilhamento de Arquivos do Armazenamento do Azure para Python com pip:

pip install azure-storage-file-share

Criar uma conta de armazenamento

Se você quiser criar uma nova conta de armazenamento, poderá usar 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

Crie o cliente

A biblioteca de clientes do Compartilhamento de Arquivos do Armazenamento do Azure para Python permite que você interaja com quatro tipos de recursos: a própria conta de armazenamento, compartilhamentos de arquivos, diretórios e arquivos. A interação com esses recursos começa com uma instância de um cliente. Para criar um objeto cliente, você precisará da URL do serviço de arquivo da conta de armazenamento e de uma credencial que permita acessar a conta de armazenamento:

from azure.storage.fileshare import ShareServiceClient

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

Pesquisando a URL da conta

Você pode encontrar a URL do serviço de arquivo da conta de armazenamento usando 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árias formas diferentes, dependendo do tipo de autorização que você deseja usar:

  1. Para usar um token SAS (assinatura de acesso compartilhado), forneça o token como uma cadeia de caracteres. Se a URL da conta incluir o token SAS, omita o parâmetro de credencial. Você pode gerar um token SAS no Portal do Azure em "Assinatura de acesso compartilhado" ou usar uma das generate_sas() funções para criar um token sas para a conta de armazenamento, compartilhamento ou arquivo:

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

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

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

  2. Para usar uma chave compartilhada da conta de armazenamento (também conhecida como chave de conta ou chave de acesso), forneça a chave como uma cadeia de caracteres. Isso pode ser encontrado no Portal do Azure na seção "Chaves de Acesso" ou executando o seguinte comando da CLI do Azure:

    az storage account keys list -g MyResourceGroup -n MyStorageAccount

    Use 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>")

Criando o cliente de um cadeia de conexão

Dependendo do caso de uso e do método de autorização, talvez você prefira inicializar uma instância de cliente com uma cadeia de conexão de armazenamento em vez de fornecer a URL da conta e a credencial separadamente. Para fazer isso, passe o cadeia de conexã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)

A cadeia de conexão com sua conta de armazenamento pode ser encontrada no Portal do Azure na seção "Chaves de Acesso" ou executando o seguinte comando da CLI:

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

Principais conceitos

Os seguintes componentes compõem o Serviço de Compartilhamento de Arquivos do Azure:

  • A própria conta de armazenamento
  • Um compartilhamento de arquivos dentro da conta de armazenamento
  • Uma hierarquia opcional de diretórios dentro do compartilhamento de arquivos
  • Um arquivo dentro do compartilhamento de arquivos, que pode ter até 1 TiB de tamanho

A biblioteca de clientes do Compartilhamento de Arquivos do Armazenamento do Azure para Python permite que você interaja com cada um desses componentes por meio do uso de um objeto cliente dedicado.

Clientes assíncronos

Essa biblioteca inclui uma API assíncrona completa com suporte no Python 3.5+. Para usá-lo, primeiro você deve instalar um transporte assíncrono, como aiohttp. Confira a documentação do azure-core para obter mais informações.

Clientes e credenciais assíncronos devem ser fechados quando não forem mais necessários. Esses objetos são gerenciadores de contexto assíncronos e definem métodos assíncronos close .

Clientes

Quatro clientes diferentes são fornecidos para interagir com os vários componentes do Serviço de Compartilhamento de Arquivos:

  1. ShareServiceClient – esse cliente representa a interação com a própria conta de armazenamento do Azure e permite que você adquira instâncias de cliente pré-configuradas para acessar os compartilhamentos de arquivos dentro dele. Ele fornece operações para recuperar e configurar as propriedades de serviço, bem como listar, criar e excluir compartilhamentos dentro da conta. Para executar operações em um compartilhamento específico, recupere um cliente usando o get_share_client método .
  2. ShareClient – esse cliente representa a interação com um compartilhamento de arquivo específico (que ainda não precisa existir) e permite que você adquira instâncias de cliente pré-configuradas para acessar os diretórios e arquivos dentro dele. Ele fornece operações para criar, excluir, configurar ou criar instantâneos de um compartilhamento e inclui operações para criar e enumerar o conteúdo dos diretórios dentro dele. Para executar operações em um diretório ou arquivo específico, recupere um cliente usando os get_directory_client métodos ou get_file_client .
  3. ShareDirectoryClient – esse cliente representa a interação com um diretório específico (que ainda não precisa existir). Ele fornece operações para criar, excluir ou enumerar o conteúdo de um subdiretório imediato ou aninhado e inclui operações para criar e excluir arquivos dentro dele. Para operações relacionadas a um subdiretório ou arquivo específico, um cliente dessa entidade também pode ser recuperado usando as get_subdirectory_client funções e get_file_client .
  4. ShareFileClient – esse cliente representa a interação com um arquivo específico (que ainda não precisa existir). Ele fornece operações para carregar, baixar, criar, excluir e copiar um arquivo.

Para obter detalhes sobre restrições de nomenclatura de caminho, consulte Nomenclatura e referência de compartilhamentos, diretórios, arquivos e metadados.

Exemplos

As seções a seguir fornecem vários snippets de código que abrangem algumas das tarefas mais comuns do Compartilhamento de Arquivos de Armazenamento, incluindo:

Criar um compartilhamento de arquivos

Criar um compartilhamento de arquivos para armazenar seus arquivos

from azure.storage.fileshare import ShareClient

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

Usar o cliente assíncrono para criar um compartilhamento de arquivos

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 arquivo

Carregar um arquivo no compartilhamento

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 arquivo 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)

Baixar um arquivo

Baixar um arquivo do compartilhamento

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)

Baixar um arquivo 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)

Listando o conteúdo de um diretório

Listar todos os diretórios e arquivos em um diretório pai

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 o conteúdo 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 opcionais palavra-chave que podem ser passados no nível do cliente e por operação.

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

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

  • retry_total (int): número total de tentativas a serem permitidas. Tem precedência sobre outras contagens. retry_total=0 Passe se você não quiser repetir as solicitações. O valor padrão é 10.
  • retry_connect (int): quantos erros relacionados à conexão tentar novamente. O valor padrão é 3.
  • retry_read (int): quantas vezes tentar novamente em erros de leitura. O valor padrão é 3.
  • retry_status (int): quantas vezes tentar novamente em códigos de status inválidos. O valor padrão é 3.
  • retry_to_secondary (bool): se a solicitação deve ser repetida para secundária, se possível. Isso só deve ser habilitado para que contas RA-GRS sejam usadas e dados potencialmente obsoletos possam ser tratados. Assume o padrão de False.

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

Outra configuração opcional palavra-chave argumentos 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 conexão com o servidor. O padrão é 20 segundos.
  • read_timeout (int): o número de segundos que o cliente aguardará, entre operações de leitura consecutivas, por uma resposta do servidor. Esse é um tempo limite de nível de soquete e não é afetado pelo tamanho geral dos dados. Os tempos limite de leitura do lado do cliente serão repetidos automaticamente. O padrão é 60 segundos.
  • transport (Any): transporte fornecido pelo usuário para enviar a solicitação HTTP.

Argumentos de palavra-chave por operação:

  • raw_response_hook (callable): o retorno de chamada especificado usa a resposta retornada do serviço.
  • raw_request_hook (callable): o retorno de chamada especificado usa a solicitação antes de ser enviado ao serviço.
  • client_request_id (str): identificação especificada pelo usuário opcional da solicitação.
  • user_agent (str): acrescenta o valor personalizado ao cabeçalho user-agent a ser enviado com a solicitação.
  • logging_enable (bool): habilita o registro em log no nível de DEBUG. Usa False como padrão. Também pode ser passado no nível do cliente para habilitá-lo para todas as solicitações.
  • logging_body (bool): habilita o registro em log do corpo da solicitação e da resposta. Usa False como padrão. Também pode ser passado no nível do cliente para habilitá-lo para todas as solicitações.
  • cabeçalhos (ditado): passe cabeçalhos personalizados como pares de chave e valor. Por exemplo, headers={'CustomValue': value}

Solução de problemas

Geral

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

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

Registro em log

Essa biblioteca usa a biblioteca de log padrão para registro em log. Informações básicas sobre sessões HTTP (URLs, cabeçalhos etc.) são registradas no nível INFO.

O log detalhado do nível de DEBUG, incluindo corpos de solicitação/resposta e cabeçalhos não redigidos, pode ser habilitado em um 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 habilitar o log detalhado para uma operação individual, mesmo quando ela não está habilitada para o cliente:

service_client.get_service_properties(logging_enable=True)

Próximas etapas

Mais códigos de exemplo

Introdução aos nossos exemplos de Compartilhamento de Arquivos.

Vários exemplos do SDK do Python de Compartilhamento de Arquivos de Armazenamento estão disponíveis para você no repositório GitHub do SDK. Esses exemplos fornecem código de exemplo para cenários adicionais comumente encontrados ao trabalhar com o Compartilhamento de Arquivos de Armazenamento:

Documentação adicional

Para obter uma documentação mais abrangente sobre o armazenamento do Compartilhamento de Arquivos do Azure, consulte a documentação de armazenamento do Compartilhamento de Arquivos do Azure no docs.microsoft.com.

Contribuição

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder, e de fato concede, os direitos de usar sua contribuição. Para obter detalhes, visite https://cla.microsoft.com.

Quando você envia uma solicitação de pull, um bot do CLA determina automaticamente se você precisa fornecer um CLA e preencher a PR corretamente (por exemplo, rótulo, comentário). Basta seguir as instruções fornecidas pelo bot. Você só precisará fazer isso uma vez em todos os repositórios que usam nosso CLA.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, confira as Perguntas frequentes sobre o Código de Conduta ou contate opencode@microsoft.com para enviar outras perguntas ou comentários.