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

  • Artigo

Visão geral

Este pacote de visualização para Python inclui suporte específico à API do ADLS Gen2 disponibilizado no SDK de Armazenamento. Isso inclui:

  1. Novas operações de nível de diretório (Criar, Renomear, Excluir) para conta de armazenamento HNS (namespace hierárquico habilitado). Para contas habilitadas para HNS, as operações de renomeação/movimentação são atômicas.
  2. Operações relacionadas à permissão (ACLs Get/Set) para contas HNS (namespace hierárquicas habilitadas).

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

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

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

# 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. Você precisa de uma conta de armazenamento existente, sua URL e uma credencial para instanciar o objeto cliente.

Obter credenciais

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

  1. Usar uma cadeia de caracteres de token SAS
  2. Usar uma chave de acesso compartilhado da conta
  3. Usar uma credencial de token do azure.identity

Como alternativa, você pode autenticar com uma cadeia de conexão de armazenamento usando o from_connection_string método . Veja o exemplo: criação de cliente com um cadeia de conexão.

Você pode omitir a credencial se a URL da sua conta já tiver um token SAS.

Criar cliente

Depois de ter a URL da conta e as credenciais prontas, você poderá criar o DataLakeServiceClient:

from azure.storage.filedatalake import DataLakeServiceClient

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

Principais conceitos

O armazenamento DataLake oferece quatro tipos de recursos:

  • A conta de armazenamento
  • Um sistema de arquivos na conta de armazenamento
  • Um diretório no sistema de arquivos
  • Um arquivo em um sistema de arquivos ou em diretório

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

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

  1. DataLakeServiceClient – esse cliente interage com o Serviço DataLake no nível da conta. Ele fornece operações para recuperar e configurar as propriedades da conta, bem como listar, criar e excluir sistemas de arquivos dentro da conta. Para operações relacionadas a um sistema de arquivos específico, diretório ou arquivo, os clientes dessas entidades também podem ser recuperados usando as get_file_clientfunções ou get_file_system_clientget_directory_client .
  2. FileSystemClient – esse cliente representa a interação com um sistema de arquivos específico, mesmo que esse sistema de arquivos ainda não exista. Ele fornece operações para criar, excluir ou configurar sistemas de arquivos e inclui operações para listar caminhos em sistema de arquivos, carregar e excluir arquivo ou diretório no sistema de arquivos. Para operações relacionadas a um arquivo específico, o cliente também pode ser recuperado usando a get_file_client função . Para operações relacionadas a um diretório específico, o cliente pode ser recuperado usando a get_directory_client função .
  3. DataLakeDirectoryClient – esse cliente representa a interação com um diretório específico, mesmo que esse diretório ainda não exista. Ele fornece operações de diretório para criar, excluir, renomear, obter propriedades e definir operações de propriedades.
  4. DataLakeFileClient – esse cliente representa a interação com um arquivo específico, mesmo que esse arquivo ainda não exista. Ele fornece operações de arquivo para acrescentar dados, liberar dados, excluir, criar e ler arquivo.
  5. DataLakeLeaseClient – esse cliente representa interações de concessão com um FileSystemClient, DataLakeDirectoryClient ou DataLakeFileClient. Ele fornece operações para adquirir, renovar, liberar, alterar e interromper concessões nos recursos.

Exemplos

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

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

Crie o DataLakeServiceClient usando o cadeia de conexão para sua conta de Armazenamento do Azure.

from azure.storage.filedatalake import DataLakeServiceClient

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

Carregar um arquivo

Carregue um arquivo no sistema de arquivos.

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

Baixar um arquivo

Baixe um arquivo do sistema de arquivos.

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)

Enumerando caminhos

Liste os caminhos em seu sistema de arquivos.

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 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 determinado usa a solicitação antes de ser enviado ao serviço.
  • client_request_id (str): identificação da solicitação especificada pelo usuário opcional.
  • 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 (dict): passe cabeçalhos personalizados como pares chave e valor. Por exemplo, headers={'CustomValue': value}

Solução de problemas

Geral

Os clientes de Armazenamento DataLake 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. As informações básicas sobre sessões HTTP (URLs, cabeçalhos etc.) são registradas no nível info.

O log detalhado no 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.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 habilitar o log detalhado para uma operação individual, mesmo quando ela não está habilitada para o cliente:

service_client.list_file_systems(logging_enable=True)

Próximas etapas

Mais códigos de exemplo

Introdução aos nossos exemplos do Azure DataLake.

Vários exemplos do SDK do Python de Armazenamento DataLake 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 Armazenamento DataLake:

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

    • Configurar um sistema de arquivos
    • Criar um diretório
    • Definir/Obter controle de acesso para o diretório
    • Criar arquivos no diretório
    • Definir/Obter controle de acesso para cada arquivo
    • Excluir sistema de arquivos

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

    • Configurar um sistema de arquivos
    • Criar arquivo
    • Acrescentar dados ao arquivo
    • Liberar dados para o arquivo
    • Baixar os dados carregados
    • Excluir sistema de arquivos

Documentação adicional

Tabela para mapeamento de API do ADLS Gen1 para ADLS Gen2 Para obter uma documentação REST mais abrangente sobre Data Lake Storage Gen2, consulte a documentação do Data Lake Storage Gen2 sobre 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.