Partilhar via

Biblioteca de cliente de 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 acedido a partir de qualquer parte do mundo através de chamadas autenticadas através de HTTP ou HTTPS. As tabelas dimensionam conforme necessário para suportar a quantidade de dados inseridos e permitem o armazenamento de dados com acesso não complexo. O cliente de Tabelas do Azure pode ser utilizado para aceder ao Armazenamento do Azure ou a contas do Cosmos. Este documento abrange azure-data-tables.

Tenha em atenção que este pacote é um substituto para azure-cosmosdb-tables o qual foi preterido. Veja o guia de migração para obter mais detalhes.

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

Exclusão de Responsabilidade

O suporte de pacotes Python do SDK do Azure para Python 2.7 terminou a 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 utilizar este pacote. Para obter mais detalhes, veja Azure SDK for Python version support policy (Política de suporte de versões do Azure SDK para Python).

Introdução

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

Pré-requisitos

Criar conta

Instalar o pacote

Instale a biblioteca de cliente tabelas do Azure para Python com pip:

pip install azure-data-tables

Criar o cliente

A biblioteca de Tabelas do Azure permite-lhe interagir com dois tipos de recursos:

  • as tabelas na sua conta
  • as entidades nessas tabelas. 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 ponto final de serviço da tabela da conta e de uma credencial que lhe permita aceder à conta. Pode endpoint encontrar na página da sua conta de armazenamento no Portal do Azure na secção "Chaves de Acesso" ou ao executar 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"

Assim que tiver o URL da conta, este pode ser utilizado 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 os URLs do serviço de tabela e como configurar nomes de domínio personalizados para o Armazenamento do Azure, consulte a documentação oficial

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. A biblioteca Tabelas suporta as seguintes autorizações:

  • Chave Partilhada
  • Cadeia de Ligação
  • Token de Assinatura de Acesso Partilhado
Criar o cliente a partir de uma chave partilhada

Para utilizar uma chave partilhada de conta (também conhecida como chave de conta ou chave de acesso), forneça a chave como uma cadeia. Isto pode ser encontrado na sua conta de armazenamento 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.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)
Criar o cliente a partir de uma 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 uma cadeia de ligação em vez de fornecer o URL e a credencial da conta separadamente. Para tal, transmita a cadeia de ligação para o método de classe do from_connection_string cliente. A cadeia de ligação pode ser encontrada na sua conta de armazenamento no Portal do Azure na secçã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)
Criar o cliente a partir de um token de SAS

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

Conceitos-chave

Utilizações comuns do serviço Tabela incluídas:

  • Armazenamento de TBs de dados estruturados com capacidade para servirem aplicações de dimensionamento da Web
  • Armazenar conjuntos de dados que não necessitam de associações complexas, chaves externas ou procedimentos armazenados e que podem ser des normalizados para acesso rápido
  • Consulta rápida de dados com um índice em cluster
  • Aceder a dados com 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 na conta, que contém um conjunto de entidades
  • Uma entidade dentro de uma tabela, como um dicionário

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

Clientes

São fornecidos dois clientes diferentes para interagir com os vários componentes do Serviço de Tabelas:

  1. TableServiceClient -
    • Obter e definir a definição da conta
    • Consultar, criar e eliminar tabelas na conta.
    • Obtenha um TableClient para aceder a uma tabela específica com o get_table_client método .
  2. TableClient -
    • Interage com uma tabela específica (que ainda não precisa de existir).
    • Crie, elimine, consulte e aumente as entidades na tabela especificada.
    • Crie ou elimine a própria tabela especificada.

Entidades

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

entity = {
    'PartitionKey': 'color',
    'RowKey': 'brand',
    'text': 'Marker',
    'color': 'Purple',
    'price': '5'
}
  • create_entity - Adicione uma entidade à tabela.
  • delete_entity - Elimine uma entidade da tabela.
  • update_entity - Atualize as informações de uma entidade ao intercalar ou substituir a entidade existente.
    • UpdateMode.MERGE irá adicionar novas propriedades a uma entidade existente que não eliminará as propriedades existentes
    • UpdateMode.REPLACE substituirá a entidade existente pelo determinado, eliminando quaisquer propriedades existentes não incluídas na entidade submetida
  • query_entities - Consultar entidades existentes numa tabela com filtros OData.
  • get_entity - Obtenha uma entidade específica de uma tabela por partição e chave de linha.
  • upsert_entity - Intercale ou substitua uma entidade numa tabela ou, se a entidade não existir, insere a entidade.
    • UpdateMode.MERGE irá adicionar novas propriedades a uma entidade existente que não eliminará as propriedades existentes
    • UpdateMode.REPLACE substituirá a entidade existente pelo determinado, eliminando quaisquer propriedades existentes não incluídas na entidade submetida

Exemplos

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

Criar uma tabela

Crie uma tabela na sua conta e obtenha uma TableClient para realizar operações na tabela criada recentemente:

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)

Criação de 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)

Consultar entidades

Consultar 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

Os argumentos de palavra-chave opcionais podem ser transmitidos ao 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, registos, protocolos de transporte e muito mais.

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): opcionalmente, define o valor de tempo limite de ligação e leitura, em 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.
  • cabeçalhos (dict): transmita cabeçalhos personalizados como chave, pares de valores. Por exemplo, headers={'CustomValue': value}

Resolução de problemas

Geral

Os clientes das Tabelas do Azure geram exceções definidas no Azure Core. Quando interage com a biblioteca de tabelas do Azure com o SDK python, os erros devolvidos pelo serviço respondem aos mesmos códigos de estado HTTP para pedidos de API REST . As operações do serviço Tabela irão gerar uma HttpResponseError falha com códigos de erro úteis.

Por exemplo, se tentar criar uma tabela que já existe, é devolvido um 409 erro que indica "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))

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.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 ativar o registo detalhado para uma única operação, mesmo quando não está ativado para o cliente:

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

Passos seguintes

Introdução aos nossos exemplos de Tabela.

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

Cenários Comuns

Estes exemplos de código mostram operações de cenário comuns com a biblioteca de cliente tabelas do Azure. As versões assíncronas dos exemplos (os ficheiros de exemplo python anexados com _async) mostram operações assíncronas.

Documentação adicional

Para obter documentação mais extensa sobre as Tabelas do Azure, veja a documentação das Tabelas do Azure sobre docs.microsoft.com.

Problemas Conhecidos

Pode encontrar aqui uma lista dos problemas atualmente conhecidos relacionados com os pontos finais da tabela do Cosmos DB.

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.

Impressões