Biblioteca de cliente do serviço Azure DataLake para Python – versão 12.14.0

  • Artigo

Descrição Geral

Este pacote de pré-visualização para Python inclui o suporte de API específico do ADLS Gen2 disponibilizado no SDK de Armazenamento. O que está incluído:

  1. Novas operações ao nível do diretório (Criar, Mudar o Nome, Eliminar) para a conta de armazenamento com espaço de nomes hierárquico ativado (HNS). Para contas ativadas por HNS, as operações de mudança/mudança de nome são atómicas.
  2. Operações relacionadas com permissões (Obter/Definir ACLs) para contas de espaço de nomes hierárquicos ativadas (HNS).

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 do Armazenamento do Azure DataLake para Python com pip:

pip install azure-storage-file-datalake --pre

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

# Install the extension 'Storage-Preview'
az extension add --name storage-preview

# Create the storage account
az storage account create --name my-storage-account-name --resource-group my-resource-group --sku Standard_LRS --kind StorageV2 --hierarchical-namespace true

Autenticar o cliente

A interação com o Armazenamento dataLake começa com uma instância da classe DataLakeServiceClient. Precisa de uma conta de armazenamento existente, o respetivo URL e uma credencial para instanciar o objeto de cliente.

Obter credenciais

Para autenticar o cliente, tem algumas opções:

  1. Utilizar uma cadeia de token de SAS
  2. Utilizar uma chave de acesso partilhado de conta
  3. Utilizar uma credencial de token a partir de azure.identity

Em alternativa, pode autenticar-se com um cadeia de ligação de armazenamento com o from_connection_string método . Veja exemplo: Criação de cliente com um cadeia de ligação.

Pode omitir a credencial se o URL da sua conta já tiver um token DE SAS.

Criar cliente

Assim que tiver o URL e as credenciais da conta prontos, pode criar o DataLakeServiceClient:

from azure.storage.filedatalake import DataLakeServiceClient

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

Conceitos-chave

O armazenamento DataLake oferece quatro tipos de recursos:

  • A conta de armazenamento
  • Um sistema de ficheiros na conta de armazenamento
  • Um diretório no sistema de ficheiros
  • Um ficheiro num sistema de ficheiros ou num diretório

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

O SDK de Armazenamento dataLake fornece quatro clientes diferentes para interagir com o Serviço DataLake:

  1. DataLakeServiceClient – este cliente interage com o Serviço DataLake ao nível da conta. Fornece operações para obter e configurar as propriedades da conta, bem como listar, criar e eliminar sistemas de ficheiros na conta. Para operações relacionadas com um sistema de ficheiros, diretório ou ficheiro específico, os clientes dessas entidades também podem ser obtidos com as get_file_clientfunções , get_directory_client ou get_file_system_client .
  2. FileSystemClient – este cliente representa a interação com um sistema de ficheiros específico, mesmo que esse sistema de ficheiros ainda não exista. Fornece operações para criar, eliminar ou configurar sistemas de ficheiros e inclui operações para listar caminhos no sistema de ficheiros, carregar e eliminar ficheiros ou diretórios no sistema de ficheiros. Para operações relacionadas com um ficheiro específico, o cliente também pode ser obtido com a get_file_client função. Para operações relacionadas com um diretório específico, o cliente pode ser obtido com a get_directory_client função.
  3. DataLakeDirectoryClient – este cliente representa a interação com um diretório específico, mesmo que esse diretório ainda não exista. Fornece operações de diretório para criar, eliminar, mudar o nome, obter propriedades e definir operações de propriedades.
  4. DataLakeFileClient – este cliente representa a interação com um ficheiro específico, mesmo que esse ficheiro ainda não exista. Fornece operações de ficheiros para acrescentar dados, remover dados, eliminar, criar e ler ficheiros.
  5. DataLakeLeaseClient - este cliente representa interações de concessão com um FileSystemClient, DataLakeDirectoryClient ou DataLakeFileClient. Fornece operações para adquirir, renovar, lançar, alterar e interromper concessões nos recursos.

Exemplos

As secções seguintes fornecem vários fragmentos de código que abrangem algumas das tarefas mais comuns do Storage DataLake, incluindo:

Criação de cliente com um cadeia de ligação

Crie o DataLakeServiceClient com o cadeia de ligação para a sua conta de Armazenamento do Azure.

from azure.storage.filedatalake import DataLakeServiceClient

service = DataLakeServiceClient.from_connection_string(conn_str="my_connection_string")

Carregar um ficheiro

Carregue um ficheiro para o seu sistema de ficheiros.

from azure.storage.filedatalake import DataLakeFileClient

data = b"abc"
file = DataLakeFileClient.from_connection_string("my_connection_string",
                                                 file_system_name="myfilesystem", file_path="myfile")
file.create_file ()
file.append_data(data, offset=0, length=len(data))
file.flush_data(len(data))

Transferir um ficheiro

Transfira um ficheiro a partir do seu sistema de ficheiros.

from azure.storage.filedatalake import DataLakeFileClient

file = DataLakeFileClient.from_connection_string("my_connection_string",
                                                 file_system_name="myfilesystem", file_path="myfile")

with open("./BlockDestination.txt", "wb") as my_file:
    download = file.download_file()
    download.readinto(my_file)

Enumerar caminhos

Liste os caminhos no seu sistema de ficheiros.

from azure.storage.filedatalake import FileSystemClient

file_system = FileSystemClient.from_connection_string("my_connection_string", file_system_name="myfilesystem")

paths = file_system.get_paths()
for path in paths:
    print(path.name + '\n')

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 especificada 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. A predefinição é 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. A predefinição é 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 valor. Por exemplo, headers={'CustomValue': value}

Resolução de problemas

Geral

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

Esta lista pode ser utilizada para referência para detetar exceções emitidas. 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 registo. As informações básicas sobre sessões HTTP (URLs, cabeçalhos, etc.) são registadas ao nível da INFORMAÇÃO.

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

import sys
import logging
from azure.storage.filedatalake import DataLakeServiceClient

# Create a logger for the 'azure.storage.filedatalake' SDK
logger = logging.getLogger('azure.storage')
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 = DataLakeServiceClient.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.list_file_systems(logging_enable=True)

Passos seguintes

Mais código de exemplo

Introdução aos nossos exemplos do Azure DataLake.

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

  • datalake_samples_access_control.py - Exemplos para tarefas comuns de Armazenamento do DataLake:

    • Configurar um sistema de ficheiros
    • Criar um diretório
    • Definir/Obter controlo de acesso para o diretório
    • Criar ficheiros no diretório
    • Definir/Obter controlo de acesso para cada ficheiro
    • Eliminar sistema de ficheiros

  • datalake_samples_upload_download.py - Exemplos para tarefas comuns de Armazenamento do DataLake:

    • Configurar um sistema de ficheiros
    • Criar ficheiro
    • Acrescentar dados ao ficheiro
    • Remover dados para o ficheiro
    • Transferir os dados carregados
    • Eliminar sistema de ficheiros

Documentação adicional

Table for ADLS Gen1 to ADLS Gen2 API Mapping (Mapeamento de API do ADLS Gen1 para o ADLS Gen2) Para obter uma documentação REST mais extensa sobre Data Lake Storage Gen2, veja a documentação Data Lake Storage Gen2 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 contacte opencode@microsoft.com com quaisquer perguntas ou comentários adicionais.