Biblioteca de clientes das Tabelas do Azure para Python – versão 12.4.4

  • Artigo

As Tabelas do Azure são um serviço de armazenamento de dados NoSQL que pode ser acessado de qualquer lugar do mundo por meio de chamadas autenticadas usando HTTP ou HTTPS. As tabelas são dimensionadas conforme necessário para dar suporte à quantidade de dados inseridos e permitir o armazenamento de dados com acesso não complexo. O cliente tabelas do Azure pode ser usado para acessar contas do Armazenamento do Azure ou do Cosmos. Este documento aborda azure-data-tables.

Observe que esse pacote é uma substituição para azure-cosmosdb-tables a qual agora foi preterido. Consulte o guia de migração para obter mais detalhes.

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

Aviso de isenção de responsabilidade

O suporte a pacotes python do SDK do Azure para Python 2.7 terminou em 01 de janeiro de 2022. Para obter mais informações e perguntas, consulte https://github.com/Azure/azure-sdk-for-python/issues/20691Python 3.7 ou posterior é necessário para usar esse pacote. Para obter mais detalhes, consulte a política de suporte do SDK do Azure para Python.

Introdução

O SDK de Tabelas do Azure pode acessar uma conta do Armazenamento do Azure ou do CosmosDB.

Pré-requisitos

Criar conta

Instalar o pacote

Instale a biblioteca de clientes das Tabelas do Azure para Python com pip:

pip install azure-data-tables

Crie o cliente

A biblioteca tabelas do Azure permite que você interaja com dois tipos de recursos:

  • as tabelas em sua conta
  • as entidades dentro dessas tabelas. 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 ponto de extremidade de serviço de tabela da conta e de uma credencial que permita acessar a conta. O endpoint pode ser encontrado na página da sua conta de armazenamento no Portal do Azure na seção "Chaves de Acesso" ou executando o seguinte comando da CLI do Azure:
# Get the table service URL for the account
az storage account show -n mystorageaccount -g MyResourceGroup --query "primaryEndpoints.table"

Depois que você tiver a URL da conta, ela poderá ser usada para criar o cliente de serviço:

from azure.data.tables import TableServiceClient
service = TableServiceClient(endpoint="https://<my_account_name>.table.core.windows.net/", credential=credential)

Para obter mais informações sobre URLs de serviço de tabela e como configurar nomes de domínio personalizados para o Armazenamento do Azure marcar a documentação oficial

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. A biblioteca Tabelas dá suporte às seguintes autorizações:

  • Chave compartilhada
  • Cadeia de conexão
  • Token de Assinatura de Acesso Compartilhado
Criando o cliente a partir de uma chave compartilhada

Para usar uma chave compartilhada de conta (também conhecida como chave de conta ou chave de acesso), forneça a chave como uma cadeia de caracteres. Isso pode ser encontrado em sua conta de armazenamento 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.core.credentials import AzureNamedKeyCredential
from azure.data.tables import TableServiceClient

credential = AzureNamedKeyCredential("my_account_name", "my_access_key")

service = TableServiceClient(endpoint="https://<my_account_name>.table.core.windows.net", credential=credential)
Criando o cliente a partir de uma cadeia de conexão

Dependendo do caso de uso e do método de autorização, talvez você prefira inicializar uma instância do cliente com uma cadeia de conexão em vez de fornecer a URL da conta e a credencial separadamente. Para fazer isso, passe a cadeia de conexão para o método de classe do from_connection_string cliente. A cadeia de conexão pode ser encontrada em sua conta de armazenamento no Portal do Azure na seção "Chaves de Acesso" ou com o seguinte comando da CLI do Azure:

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

from azure.data.tables import TableServiceClient
connection_string = "DefaultEndpointsProtocol=https;AccountName=<my_account_name>;AccountKey=<my_account_key>;EndpointSuffix=core.windows.net"
service = TableServiceClient.from_connection_string(conn_str=connection_string)
Criando o cliente com base em um token SAS

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 do Portal do Azure em Assinatura de acesso compartilhado ou usar uma das generate_*_sas() funções para criar um token sas para a conta ou tabela:

from datetime import datetime, timedelta
from azure.data.tables import TableServiceClient, generate_account_sas, ResourceTypes, AccountSasPermissions
from azure.core.credentials import AzureNamedKeyCredential, AzureSasCredential

credential = AzureNamedKeyCredential("my_account_name", "my_access_key")
sas_token = generate_account_sas(
    credential,
    resource_types=ResourceTypes(service=True),
    permission=AccountSasPermissions(read=True),
    expiry=datetime.utcnow() + timedelta(hours=1),
)

table_service_client = TableServiceClient(endpoint="https://<my_account_name>.table.core.windows.net", credential=AzureSasCredential(sas_token))

Principais conceitos

Usos comuns do serviço Tabela incluídos:

  • Armazenamento de TBs de dados estruturados capazes de atender a aplicativos de dimensionamento da Web
  • Armazenar conjuntos de dados que não exigem junções complexas, chaves estrangeiras ou procedimentos armazenados e podem ser des normalizados para acesso rápido
  • Consulta rápida de dados usando um índice clusterizado
  • Acessando dados usando o protocolo OData e expressões de filtro LINQ

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

  • A conta
  • Uma tabela dentro da conta, que contém um conjunto de entidades
  • Uma entidade dentro de uma tabela, como um dicionário

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

Clientes

Dois clientes diferentes são fornecidos para interagir com os vários componentes do Serviço de Tabela:

  1. TableServiceClient -
    • Obter e definir a configuração da conta
    • Consultar, criar e excluir tabelas dentro da conta.
    • Obtenha um TableClient para acessar uma tabela específica usando o get_table_client método .
  2. TableClient -
    • Interage com uma tabela específica (que ainda não precisa existir).
    • Criar, excluir, consultar e upsert entidades dentro da tabela especificada.
    • Crie ou exclua a tabela especificada em si.

Entities

As entidades são semelhantes às linhas. Uma entidade tem um PartitionKey, um RowKeye um conjunto de propriedades. Uma propriedade é um par de valores de nome, semelhante a uma coluna. Todas as entidades em uma tabela não precisam ter as mesmas propriedades. As entidades podem ser representadas como dicionários como este como um exemplo:

entity = {
    'PartitionKey': 'color',
    'RowKey': 'brand',
    'text': 'Marker',
    'color': 'Purple',
    'price': '5'
}
  • create_entity – Adicionar uma entidade à tabela.
  • delete_entity – exclua uma entidade da tabela.
  • update_entity – atualize as informações de uma entidade mesclando ou substituindo a entidade existente.
    • UpdateMode.MERGE adicionará novas propriedades a uma entidade existente que não excluirá uma propriedade existente
    • UpdateMode.REPLACE substituirá a entidade existente pela determinada, excluindo todas as propriedades existentes não incluídas na entidade enviada
  • query_entities – Consultar entidades existentes em uma tabela usando filtros OData.
  • get_entity – Obter uma entidade específica de uma tabela por partição e chave de linha.
  • upsert_entity - Mesclar ou substituir uma entidade em uma tabela ou, se a entidade não existir, insere a entidade.
    • UpdateMode.MERGE adicionará novas propriedades a uma entidade existente que não excluirá uma propriedade existente
    • UpdateMode.REPLACE substituirá a entidade existente pela determinada, excluindo todas as propriedades existentes não incluídas na entidade enviada

Exemplos

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

Criar uma tabela

Crie uma tabela em sua conta e obtenha uma TableClient para executar operações na tabela recém-criada:

from azure.data.tables import TableServiceClient
table_service_client = TableServiceClient.from_connection_string(conn_str="<connection_string>")
table_name = "myTable"
table_client = table_service_client.create_table(table_name=table_name)

Como criar entidades

Criar entidades na tabela:

from azure.data.tables import TableServiceClient
from datetime import datetime

PRODUCT_ID = u'001234'
PRODUCT_NAME = u'RedMarker'

my_entity = {
    u'PartitionKey': PRODUCT_NAME,
    u'RowKey': PRODUCT_ID,
    u'Stock': 15,
    u'Price': 9.99,
    u'Comments': u"great product",
    u'OnSale': True,
    u'ReducedPrice': 7.99,
    u'PurchaseDate': datetime(1973, 10, 4),
    u'BinaryRepresentation': b'product_name'
}

table_service_client = TableServiceClient.from_connection_string(conn_str="<connection_string>")
table_client = table_service_client.get_table_client(table_name="myTable")

entity = table_client.create_entity(entity=my_entity)

Consultando entidades

Consultando entidades na tabela:

from azure.data.tables import TableClient
my_filter = "PartitionKey eq 'RedMarker'"
table_client = TableClient.from_connection_string(conn_str="<connection_string>", table_name="myTable")
entities = table_client.query_entities(my_filter)
for entity in entities:
    for key in entity.keys():
        print("Key: {}, Value: {}".format(key, entity[key]))

Configuração opcional

Argumentos opcionais de palavra-chave podem ser passados no nível do cliente e por operação. A documentação de referência do azure-core descreve as configurações disponíveis para repetições, registro em log, protocolos de transporte e muito mais.

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 a secundária, se possível. Isso só deve ser habilitado de contas RA-GRS usadas e dados potencialmente obsoletos podem ser tratados. Assume o padrão de False.

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

Outras configurações opcionais palavra-chave argumentos que podem ser especificados no cliente ou por operação.

Argumentos de palavra-chave do cliente:

  • connection_timeout (int): opcionalmente, define o valor de tempo limite de conexão e leitura, em 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.
  • 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 Tabelas do Azure geram exceções definidas no Azure Core. Quando você interage com a biblioteca de tabelas do Azure usando o SDK do Python, os erros retornados pelo serviço respondem aos mesmos códigos de status HTTP para solicitações da API REST. As operações de serviço Tabela lançarão um em caso de HttpResponseError falha com códigos de erro úteis.

Por exemplo, se você tentar criar uma tabela que já existe, um 409 erro será retornado indicando "Conflito".

from azure.data.tables import TableServiceClient
from azure.core.exceptions import HttpResponseError
table_name = 'YourTableName'

service_client = TableServiceClient.from_connection_string(connection_string)

# Create the table if it does not already exist
tc = service_client.create_table_if_not_exists(table_name)

try:
    service_client.create_table(table_name)
except HttpResponseError:
    print("Table with name {} already exists".format(table_name))

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.data.tables import TableServiceClient
# Create a logger for the 'azure' SDK
logger = logging.getLogger('azure')
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 = TableServiceClient.from_connection_string("your_connection_string", logging_enable=True)

Da mesma forma, logging_enable pode habilitar o log detalhado para uma única operação, mesmo quando não estiver habilitada para o cliente:

service_client.create_entity(entity=my_entity, logging_enable=True)

Próximas etapas

Introdução aos nossos exemplos de Tabela.

Vários exemplos do SDK do Python de Tabelas do Azure 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 Tabelas.

Cenários comuns

Esses exemplos de código mostram operações de cenário comuns com a biblioteca de clientes das Tabelas do Azure. As versões assíncronas dos exemplos (os arquivos de exemplo do Python acrescentados com _async) mostram operações assíncronas.

Documentação adicional

Para obter uma documentação mais abrangente sobre tabelas do Azure, consulte a documentação das Tabelas do Azure sobre docs.microsoft.com.

Problemas conhecidos

Uma lista de problemas conhecidos no momento relacionados aos pontos de extremidade de tabela do Cosmos DB pode ser encontrada aqui.

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.

Impressões