Guia de início rápido: criar uma API para o aplicativo Table com o SDK do Python e o Azure Cosmos DB
APLICA-SE A: 
Tabela
Este início rápido mostra como acessar a API do Azure Cosmos DB para Tabela a partir de um aplicativo Python. O Azure Cosmos DB for Table é um armazenamento de dados sem esquema que permite que os aplicativos armazenem dados NoSQL estruturados na nuvem. Como os dados são armazenados em um design sem esquema, novas propriedades (colunas) são adicionadas automaticamente à tabela quando um objeto com um novo atributo é adicionado à tabela. Os aplicativos Python podem acessar o Azure Cosmos DB for Table usando o pacote SDK de Tabelas de Dados do Azure para Python .
Pré-requisitos
O aplicativo de exemplo é escrito em Python 3.7 ou posterior, embora os princípios se apliquem a todos os aplicativos Python 3.7+. Você pode usar o Visual Studio Code como um IDE.
Se não tiver uma subscrição do Azure, crie uma conta gratuita antes de começar.
Aplicação de exemplo
O aplicativo de exemplo para este tutorial pode ser clonado ou baixado do repositório https://github.com/Azure-Samples/msdocs-azure-tables-sdk-python-flask.
git clone https://github.com/Azure-Samples/msdocs-azure-tables-sdk-python-flask.git
Uma pasta de exemplo 1-starter-app e 2-completed-app são incluídas no repositório de exemplo. O aplicativo 1-starter-tem algumas funcionalidades restantes para você completar com linhas marcadas como "#TODO". Os trechos de código mostrados neste artigo são as adições sugeridas para concluir o 1-starter-app.
O aplicativo de exemplo concluído usa dados meteorológicos como exemplo para demonstrar os recursos da API para Tabela. Os objetos que representam observações meteorológicas são armazenados e recuperados usando a API para Tabela, incluindo o armazenamento de objetos com propriedades extras para demonstrar os recursos sem esquema da API para Tabela. A imagem a seguir mostra o aplicativo local em execução em um navegador, exibindo os dados meteorológicos armazenados no Azure Cosmos DB for Table.
1 - Criar uma conta do Azure Cosmos DB
Primeiro, você precisa criar uma conta da API de Tabelas do Azure Cosmos DB que conterá a(s) tabela(s) usada(s) em seu aplicativo. Crie uma conta com o portal do Azure, a CLI do Azure ou o Azure PowerShell.
Faça logon no portal do Azure e siga estas etapas para criar uma conta do Azure Cosmos DB.
| Instruções | Captura de ecrã |
|---|---|
No portal do Azure:
|
|
| Na página do Azure Cosmos DB, selecione +Criar. | 
|
| Na página de opção Selecionar API, escolha a opção Tabela do Azure. | 
|
Na página Criar Conta do Azure Cosmos DB - Tabela do Azure, preencha o formulário da seguinte forma.
|
|
2 - Criar uma tabela
Em seguida, você precisa criar uma tabela em sua conta do Azure Cosmos DB para seu aplicativo usar. Ao contrário de um banco de dados tradicional, você só precisa especificar o nome da tabela, não as propriedades (colunas) na tabela. À medida que os dados são carregados na tabela, as propriedades (colunas) são criadas automaticamente conforme necessário.
No portal do Azure, conclua as etapas a seguir para criar uma tabela dentro de sua conta do Azure Cosmos DB.
| Instruções | Captura de ecrã |
|---|---|
No portal do Azure, navegue até a página de visão geral da conta do Azure Cosmos DB.
|
|
| Na página Visão geral, selecione +Adicionar tabela. A caixa de diálogo Nova Tabela desliza do lado direito da página. | 
|
Na caixa de diálogo Nova tabela, preencha o formulário da seguinte forma.
|
|
3 - Obter a cadeia de conexão do Azure Cosmos DB
Para acessar sua(s) tabela(s) no Azure Cosmos DB, seu aplicativo precisa da cadeia de conexão de tabela para a conta de Armazenamento do Cosmos DB. A cadeia de conexão pode ser recuperada usando o portal do Azure, a CLI do Azure ou o Azure PowerShell.
| Instruções | Captura de ecrã |
|---|---|
| No lado esquerdo da página da conta do Azure Cosmos DB, localize o item de menu chamado Cadeias de conexão sob o cabeçalho Configurações e selecione-o. Você será levado para uma página onde poderá recuperar a cadeia de conexão da conta do Azure Cosmos DB. | 
|
| Copie o valor PRIMARY CONNECTION STRING para usar em seu aplicativo. | 
|
4 - Instalar o SDK de Tabelas de Dados do Azure para Python
Depois de criar uma conta do Azure Cosmos DB, sua próxima etapa é instalar o SDK de Tabelas de Dados do Microsoft Azure para Python. Para obter detalhes sobre como instalar o SDK, consulte o arquivo README.md no repositório Data Tables SDK for Python no GitHub.
Instale a biblioteca de cliente do Azure Tables para Python com pip:
pip install azure-data-tables
Não se esqueça também de instalar o requirements.txt nas pastas 1-starter-app ou 2-completed-app .
5 - Configurar o cliente Table em um arquivo .env
Copie sua cadeia de conexão de conta do Azure Cosmos DB do portal do Azure e crie um objeto TableServiceClient usando sua cadeia de conexão copiada. Mude para a pasta 1-starter-app ou 2-completed-app . Independentemente do aplicativo com o qual você começa, você precisa definir variáveis de ambiente em um .env arquivo.
# Configuration Parameters
conn_str = "A connection string to an Azure Cosmos DB account."
table_name = "WeatherData"
project_root_path = "Project abs path"
O SDK do Azure se comunica com o Azure usando objetos de cliente para executar operações diferentes no Azure. O TableServiceClient objeto é o objeto usado para se comunicar com o Azure Cosmos DB for Table. Um aplicativo normalmente terá um único TableServiceClient geral, e terá um TableClient por tabela.
Por exemplo, o código a seguir cria um TableServiceClient objeto usando a cadeia de conexão da variável de ambiente.
self.conn_str = os.getenv("conn_str")
self.table_service = TableServiceClient.from_connection_string(self.conn_str)
6 - Implementar operações de tabela do Azure Cosmos DB
Todas as operações de tabela do Azure Cosmos DB para o aplicativo de exemplo são implementadas na TableServiceHelper classe localizada no arquivo auxiliar no diretório webapp . Você precisará importar a TableServiceClient classe na parte superior deste arquivo para trabalhar com objetos na biblioteca de cliente azure.data.tables para Python.
from azure.data.tables import TableServiceClient
No início da TableServiceHelper classe, crie um construtor e adicione uma variável membro para o TableClient objeto para permitir que o TableClient objeto seja injetado na classe.
def __init__(self, table_name=None, conn_str=None):
self.table_name = table_name if table_name else os.getenv("table_name")
self.conn_str = conn_str if conn_str else os.getenv("conn_str")
self.table_service = TableServiceClient.from_connection_string(self.conn_str)
self.table_client = self.table_service.get_table_client(self.table_name)
Filtrar linhas retornadas de uma tabela
Para filtrar as linhas retornadas de uma tabela, você pode passar uma cadeia de caracteres de filtro de estilo OData para o query_entities método. Por exemplo, se você quisesse obter todas as leituras do tempo para Chicago entre a meia-noite de 1º de julho de 2021 e a meia-noite de 2 de julho de 2021 (inclusive), você passaria na seguinte cadeia de filtros.
PartitionKey eq 'Chicago' and RowKey ge '2021-07-01 12:00 AM' and RowKey le '2021-07-02 12:00 AM'
Você pode exibir operadores de filtro OData relacionados no site azure-data-tables na seção Escrevendo filtros.
Quando o TableServiceHelper parâmetro request.args é passado para o query_entity método na classe, ele cria uma cadeia de caracteres de filtro para cada valor de propriedade não nulo. Em seguida, ele cria uma cadeia de caracteres de filtro combinada unindo todos os valores com uma cláusula "e". Essa cadeia de caracteres de filtro combinada é passada para o query_entities TableClient método no objeto e somente as linhas correspondentes à cadeia de caracteres de filtro são retornadas. Você pode usar um método semelhante em seu código para construir cadeias de caracteres de filtro adequadas, conforme exigido pelo seu aplicativo.
def query_entity(self, params):
filters = []
if params.get("partitionKey"):
filters.append("PartitionKey eq '{}'".format(params.get("partitionKey")))
if params.get("rowKeyDateStart") and params.get("rowKeyTimeStart"):
filters.append("RowKey ge '{} {}'".format(params.get("rowKeyDateStart"), params.get("rowKeyTimeStart")))
if params.get("rowKeyDateEnd") and params.get("rowKeyTimeEnd"):
filters.append("RowKey le '{} {}'".format(params.get("rowKeyDateEnd"), params.get("rowKeyTimeEnd")))
if params.get("minTemperature"):
filters.append("Temperature ge {}".format(params.get("minTemperature")))
if params.get("maxTemperature"):
filters.append("Temperature le {}".format(params.get("maxTemperature")))
if params.get("minPrecipitation"):
filters.append("Precipitation ge {}".format(params.get("minPrecipitation")))
if params.get("maxPrecipitation"):
filters.append("Precipitation le {}".format(params.get("maxPrecipitation")))
return list(self.table_client.query_entities(" and ".join(filters)))
Inserir dados usando um objeto TableEntity
A maneira mais simples de adicionar dados a uma tabela é usando um TableEntity objeto. Neste exemplo, os dados são mapeados de um objeto de modelo de entrada para um TableEntity objeto. As propriedades no objeto de entrada que representam o nome da estação meteorológica e a data/hora de observação são mapeadas para as PartitionKey propriedades e RowKey respectivamente, que juntas formam uma chave exclusiva para a linha na tabela. Em seguida, as propriedades extras no objeto de modelo de entrada são mapeadas para propriedades de dicionário no objeto TableEntity. Finalmente, o create_entity TableClient método no objeto é usado para inserir dados na tabela.
Modifique a insert_entity função no aplicativo de exemplo para conter o código a seguir.
def insert_entity(self):
entity = self.deserialize()
return self.table_client.create_entity(entity)
@staticmethod
def deserialize():
params = {key: request.form.get(key) for key in request.form.keys()}
params["PartitionKey"] = params.pop("StationName")
params["RowKey"] = "{} {}".format(params.pop("ObservationDate"), params.pop("ObservationTime"))
return params
Dados de upsert usando um objeto TableEntity
Se tentar inserir uma linha numa tabela com uma combinação de chave de partição/chave de linha que já existe nessa tabela, receberá um erro. Por esse motivo, muitas vezes é preferível usar o upsert_entity método em vez do create_entity método ao adicionar linhas a uma tabela. Se a combinação de chave de partição/chave de linha já existir na tabela, o upsert_entity método atualiza a linha existente. Caso contrário, a linha é adicionada à tabela.
def upsert_entity(self):
entity = self.deserialize()
return self.table_client.upsert_entity(entity)
@staticmethod
def deserialize():
params = {key: request.form.get(key) for key in request.form.keys()}
params["PartitionKey"] = params.pop("StationName")
params["RowKey"] = "{} {}".format(params.pop("ObservationDate"), params.pop("ObservationTime"))
return params
Inserir ou atualizar dados com propriedades variáveis
Uma das vantagens de usar o Azure Cosmos DB for Table é que, se um objeto que está sendo carregado em uma tabela contiver novas propriedades, essas propriedades serão adicionadas automaticamente à tabela e aos valores armazenados no Azure Cosmos DB. Não há necessidade de executar instruções DDL como ALTER TABLE para adicionar colunas como em um banco de dados tradicional.
Esse modelo dá flexibilidade ao seu aplicativo ao lidar com fontes de dados que podem adicionar ou modificar quais dados precisam ser capturados ao longo do tempo ou quando entradas diferentes fornecem dados diferentes para seu aplicativo. Na aplicação de exemplo, podemos simular uma estação meteorológica que envia não apenas os dados meteorológicos base, mas também alguns valores extras. Quando um objeto com essas novas propriedades é armazenado na tabela pela primeira vez, as propriedades correspondentes (colunas) são adicionadas automaticamente à tabela.
Para inserir ou atualizar esse objeto usando a API para Tabela, mapeie as propriedades do objeto expansível em um TableEntity objeto e use os create_entity métodos ou upsert_entity no TableClient objeto conforme apropriado.
No aplicativo de exemplo, a upsert_entity função também pode implementar a função de inserir ou atualizar dados com propriedades variáveis
def insert_entity(self):
entity = self.deserialize()
return self.table_client.create_entity(entity)
def upsert_entity(self):
entity = self.deserialize()
return self.table_client.upsert_entity(entity)
@staticmethod
def deserialize():
params = {key: request.form.get(key) for key in request.form.keys()}
params["PartitionKey"] = params.pop("StationName")
params["RowKey"] = "{} {}".format(params.pop("ObservationDate"), params.pop("ObservationTime"))
return params
Atualizar uma entidade
As entidades podem ser atualizadas chamando o update_entity método no TableClient objeto.
No aplicativo de exemplo, esse objeto é passado para o upsert_entity método na TableClient classe. Ele atualiza esse objeto de entidade e usa o upsert_entity método para salvar as atualizações no banco de dados.
def update_entity(self):
entity = self.update_deserialize()
return self.table_client.update_entity(entity)
@staticmethod
def update_deserialize():
params = {key: request.form.get(key) for key in request.form.keys()}
params["PartitionKey"] = params.pop("StationName")
params["RowKey"] = params.pop("ObservationDate")
return params
Remover uma entidade
Para remover uma entidade de uma tabela, chame o delete_entity TableClient método no objeto com a chave de partição e a chave de linha do objeto.
def delete_entity(self):
partition_key = request.form.get("StationName")
row_key = request.form.get("ObservationDate")
return self.table_client.delete_entity(partition_key, row_key)
7 - Execute o código
Execute o aplicativo de exemplo para interagir com o Azure Cosmos DB for Table. Por exemplo, a partir da pasta 2-completed-app, com os requisitos instalados, você pode usar:
python3 run.py webapp
Consulte o arquivo README.md na raiz do repositório de exemplo para obter mais informações sobre como executar o aplicativo de exemplo.
Na primeira vez que você executar o aplicativo, não haverá dados porque a tabela está vazia. Use qualquer um dos botões na parte superior do aplicativo para adicionar dados à tabela.
Selecionar o botão Inserir usando entidade da tabela abre uma caixa de diálogo que permite inserir ou atualizar uma nova linha usando um TableEntity objeto.
Selecionar o botão Inserir usando Dados Expansíveis exibe uma caixa de diálogo que permite inserir um objeto com propriedades personalizadas, demonstrando como o Azure Cosmos DB for Table adiciona automaticamente propriedades (colunas) à tabela quando necessário. Use o botão Adicionar campo personalizado para adicionar uma ou mais novas propriedades e demonstrar esse recurso.
Use o botão Inserir Dados de Exemplo para carregar alguns dados de exemplo em sua Tabela do Azure Cosmos DB.
Para a pasta de exemplo 1-starter-app , você precisará pelo menos completar o código da função para que
submit_transactiona inserção de dados de exemplo funcione.Os dados de exemplo são carregados de um arquivo sample_data.json . A variável
project_root_path.env informa ao aplicativo onde encontrar esse arquivo. Por exemplo, se você estiver executando o aplicativo a partir da pasta 1-starter-app ou 2-completed-app , definaproject_root_pathcomo "" (em branco).
Selecione o item Filtrar Resultados no menu superior para ser direcionado para a página Resultados do Filtro. Nesta página, preencha os critérios de filtro para demonstrar como uma cláusula de filtro pode ser criada e passada para o Azure Cosmos DB for Table.
Clean up resources (Limpar recursos)
Quando terminar o aplicativo de exemplo, remova todos os recursos do Azure relacionados a este artigo da sua conta do Azure. Você pode remover todos os recursos excluindo o grupo de recursos.
Um grupo de recursos pode ser excluído usando o portal do Azure fazendo o seguinte.
| Instruções | Captura de ecrã |
|---|---|
| Para ir para o grupo de recursos, na barra de pesquisa, digite o nome do grupo de recursos. Em seguida, na guia Grupos de Recursos , selecione o nome do grupo de recursos. | 
|
| Selecione Excluir grupo de recursos na barra de ferramentas na parte superior da página do grupo de recursos. | 
|
Uma caixa de diálogo aparecerá à direita da tela solicitando que você confirme a exclusão do grupo de recursos.
|
|
Próximos passos
Neste guia de introdução, aprendeu a criar uma conta do Azure Cosmos DB, a criar uma tabela com o Data Explorer e a executar uma aplicação. Agora você pode consultar seus dados usando a API para Tabela.
Comentários
Brevemente: Ao longo de 2024, vamos descontinuar progressivamente o GitHub Issues como mecanismo de feedback para conteúdos e substituí-lo por um novo sistema de feedback. Para obter mais informações, veja: https://aka.ms/ContentUserFeedback.
Submeter e ver comentários