Início Rápido: Criar uma API para a aplicação Tabela com o SDK python e o Azure Cosmos DB
APLICA-SE A:
Tabela
Este início rápido mostra como aceder à API do Azure Cosmos DB para Tabela a partir de uma aplicação Python. O Azure Cosmos DB for Table é um arquivo de dados sem esquema que permite que as aplicações armazenem dados NoSQL estruturados na cloud. Uma vez que os dados são armazenados numa estrutura sem esquema, as novas propriedades (colunas) são adicionadas automaticamente à tabela quando um objeto com um novo atributo é adicionado à tabela. As aplicações Python podem aceder ao Azure Cosmos DB para Tabela com o SDK de Tabelas de Dados do Azure para o pacote Python.
Pré-requisitos
A aplicação de exemplo é escrita no Python 3.7 ou posterior, embora os princípios se apliquem a todas as aplicações python 3.7+ . Pode utilizar 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
A aplicação de exemplo para este tutorial pode ser clonada ou transferida a partir 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 de 1 aplicação inicial e de 2 aplicações concluídas está incluída no repositório de exemplo. A aplicação 1-starter tem algumas funcionalidades restantes para concluir com linhas marcadas como "#TODO". Os fragmentos de código apresentados neste artigo são as adições sugeridas para concluir a aplicação de 1 inicial.
A aplicação de exemplo concluída utiliza dados meteorológicos como exemplo para demonstrar as capacidades da API para Tabela. Os objetos que representam observações meteorológicas são armazenados e obtidos com a API para Tabela, incluindo o armazenamento de objetos com propriedades adicionais para demonstrar as capacidades sem esquema da API para Tabela. A imagem seguinte mostra a aplicação local em execução num browser, apresentando os dados meteorológicos armazenados no Azure Cosmos DB para Tabela.
1 - Criar uma conta do Azure Cosmos DB
Primeiro, tem de criar uma conta da API de Tabelas do Azure Cosmos DB que contenha as tabelas utilizadas na sua aplicação. Crie uma conta com o portal do Azure, a CLI do Azure ou Azure PowerShell.
Inicie sessão no portal do Azure e siga estes passos 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, selecione 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, tem de criar uma tabela na sua conta do Azure Cosmos DB para a sua aplicação utilizar. Ao contrário de uma base de dados tradicional, só precisa de especificar o nome da tabela e não as propriedades (colunas) na tabela. À medida que os dados são carregados para a tabela, as propriedades (colunas) são criadas automaticamente conforme necessário.
No portal do Azure, conclua os seguintes passos para criar uma tabela dentro da sua conta do Azure Cosmos DB.
| Instruções | Captura de ecrã |
|---|---|
No portal do Azure, navegue para a página de descrição geral da conta do Azure Cosmos DB.
|
|
| Na página Descrição geral , selecione +Adicionar Tabela. A caixa de diálogo Nova Tabela desliza para fora 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 ligação do Azure Cosmos DB
Para aceder às suas tabelas no Azure Cosmos DB, a sua aplicação precisa da cadeia de ligação da tabela para a conta de Armazenamento do Cosmos DB. A cadeia de ligação pode ser obtida com a portal do Azure, a CLI do Azure ou a Azure PowerShell.
| Instruções | Captura de ecrã |
|---|---|
| No lado esquerdo da página da conta do Azure Cosmos DB, localize o item de menu denominado Cadeias de ligação no cabeçalho Definições e selecione-o. Será levado para uma página onde pode obter a cadeia de ligação da conta do Azure Cosmos DB. | 
|
| Copie o valor CADEIA DE LIGAÇÃO PRIMÁRIA para utilizar na sua aplicação. | 
|
4 - Instalar o SDK de Tabelas de Dados do Azure para Python
Depois de criar uma conta do Azure Cosmos DB, o próximo passo é instalar o SDK de Tabelas de Dados do Microsoft Azure para Python. Para obter detalhes sobre como instalar o SDK, veja o ficheiro README.md no repositório SDK de Tabelas de Dados para Python no GitHub.
Instale a biblioteca de cliente de Tabelas do Azure para Python com pip:
pip install azure-data-tables
Não se esqueça de instalar também o requirements.txt nas pastas 1-starter-app ou 2-completed-app .
5 - Configurar o cliente Tabela num ficheiro .env
Copie a cadeia de ligação da conta do Azure Cosmos DB do portal do Azure e crie um objeto TableServiceClient com a cadeia de ligação copiada. Mude para a pasta 1-starter-app ou 2-completed-app . Independentemente da aplicação com que começar, tem de definir variáveis de ambiente num .env ficheiro.
# 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 comunica com o Azure com objetos de cliente para executar operações diferentes no Azure. O TableServiceClient objeto é o objeto utilizado para comunicar com o Azure Cosmos DB para Tabela. Normalmente, uma aplicação terá um único TableServiceClient global e terá uma TableClient por tabela.
Por exemplo, o código seguinte cria um TableServiceClient objeto com a cadeia de ligaçã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 a aplicação de exemplo são implementadas na TableServiceHelper classe localizada no ficheiro auxiliar no diretório da aplicação Web . Terá de importar a TableServiceClient classe na parte superior deste ficheiro 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 de 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 devolvidas de uma tabela
Para filtrar as linhas devolvidas de uma tabela, pode transmitir uma cadeia de filtro de estilo OData para o query_entities método . Por exemplo, se quisesse obter todas as leituras meteorológicas de Chicago entre a meia-noite de 1 de julho de 2021 e a meia-noite de 2 de julho de 2021 (inclusive), passaria a seguinte cadeia de filtro.
PartitionKey eq 'Chicago' and RowKey ge '2021-07-01 12:00 AM' and RowKey le '2021-07-02 12:00 AM'
Pode ver operadores de filtro OData relacionados no site azure-data-tables na secção Filtros de Escrita.
Quando o parâmetro request.args é transmitido para o query_entity método na TableServiceHelper classe , cria uma cadeia de filtro para cada valor de propriedade não nulo. Em seguida, cria uma cadeia de filtro combinada ao associar todos os valores com uma cláusula "e". Esta cadeia de filtro combinada é transmitida ao query_entities método no TableClient objeto e só são devolvidas linhas que correspondam à cadeia de filtro. Pode utilizar um método semelhante no seu código para construir cadeias de filtro adequadas, conforme exigido pela sua aplicação.
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 com um objeto TableEntity
A forma mais simples de adicionar dados a uma tabela é através de 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 representa o nome da estação meteorológica e a data/hora de observação são mapeadas para as PartitionKey propriedades e RowKey , respetivamente, que, em conjunto, formam uma chave exclusiva para a linha na tabela. Em seguida, as propriedades adicionais no objeto do modelo de entrada são mapeadas para as propriedades do dicionário no objeto TableEntity. Por fim, o create_entity método no TableClient objeto é utilizado para inserir dados na tabela.
Modifique a insert_entity função na aplicação de exemplo para conter o seguinte código.
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
Upsert data using a TableEntity object (Upsert data using a TableEntity object)
Se tentar inserir uma linha numa tabela com uma combinação de teclas de chave de partição/linha que já existe nessa tabela, receberá um erro. Por este motivo, é frequentemente preferível utilizar o upsert_entity 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 especificada 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 upsertar dados com propriedades variáveis
Uma das vantagens de utilizar o Azure Cosmos DB para Tabela é que, se um objeto a ser carregado para uma tabela contiver novas propriedades, essas propriedades são adicionadas automaticamente à tabela e aos valores armazenados no Azure Cosmos DB. Não é necessário executar instruções DDL como ALTER TABLE para adicionar colunas como numa base de dados tradicional.
Este modelo dá flexibilidade à sua aplicação ao lidar com origens de dados que podem adicionar ou modificar os dados que precisam de ser capturados ao longo do tempo ou quando entradas diferentes fornecem dados diferentes à sua aplicação. Na aplicação de exemplo, podemos simular uma estação meteorológica que envia não só os dados meteorológicos de base, mas também alguns valores adicionais. Quando um objeto com estas novas propriedades é armazenado na tabela pela primeira vez, as propriedades correspondentes (colunas) são adicionadas automaticamente à tabela.
Para inserir ou upser tal objeto com a API para Tabela, mapeie as propriedades do objeto expansível para um TableEntity objeto e utilize os create_entity métodos ou upsert_entity no TableClient objeto conforme adequado.
Na aplicação de exemplo, a upsert_entity função também pode implementar a função de inserir ou upsertar 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 ao chamar o update_entity método no TableClient objeto.
Na aplicação de exemplo, este objeto é transmitido para o upsert_entity método na TableClient classe . Atualiza esse objeto de entidade e utiliza o upsert_entity método para guardar as atualizações na base 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 método no TableClient 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 - Executar o código
Execute a aplicação de exemplo para interagir com o Azure Cosmos DB para Tabela. Por exemplo, a partir da pasta 2 aplicações concluídas , com os requisitos instalados, pode utilizar:
python3 run.py webapp
Veja o ficheiro README.md na raiz do repositório de exemplo para obter mais informações sobre como executar a aplicação de exemplo.
Quando executar a aplicação pela primeira vez, não haverá dados porque a tabela está vazia. Utilize qualquer um dos botões na parte superior da aplicação para adicionar dados à tabela.
Selecionar o botão Inserir com a Entidade de Tabela abre uma caixa de diálogo que lhe permite inserir ou inserir uma nova linha com um TableEntity objeto.
Selecionar o botão Inserir com Dados Expansíveis apresenta uma caixa de diálogo que lhe permite inserir um objeto com propriedades personalizadas, demonstrando como o Azure Cosmos DB para Tabela adiciona automaticamente propriedades (colunas) à tabela quando necessário. Utilize o botão Adicionar Campo Personalizado para adicionar uma ou mais novas propriedades e demonstrar esta capacidade.
Utilize o botão Inserir Dados de Exemplo para carregar alguns dados de exemplo para a tabela do Azure Cosmos DB.
Para a pasta de exemplo 1-starter-app , terá de, pelo menos, concluir o código da
submit_transactionfunção para que a inserção de dados de exemplo funcione.Os dados de exemplo são carregados a partir de um ficheiro sample_data.json . A variável
project_root_path.env indica à aplicação onde encontrar este ficheiro. Por exemplo, se estiver a executar a aplicação a partir da pasta 1-starter-app ou 2-completed-app , definaproject_root_pathcomo "" (em branco).
Selecione o item Filtrar Resultados no menu superior a ser levado para a página Filtrar Resultados. Nesta página, preencha os critérios de filtro para demonstrar como uma cláusula de filtro pode ser criada e transmitida para o Azure Cosmos DB para Tabela.
Limpar os recursos
Quando tiver terminado a aplicação de exemplo, deverá remover todos os recursos do Azure relacionados com este artigo da sua conta do Azure. Pode remover todos os recursos ao eliminar o grupo de recursos.
Um grupo de recursos pode ser eliminado com a portal do Azure ao fazer o seguinte.
| Instruções | Captura de ecrã |
|---|---|
| Para aceder ao grupo de recursos, na barra de pesquisa, escreva o nome do grupo de recursos. Em seguida, no separador Grupos de Recursos , selecione o nome do grupo de recursos. | 
|
| Selecione Eliminar grupo de recursos na barra de ferramentas na parte superior da página do grupo de recursos. | 
|
Será apresentada uma caixa de diálogo à direita do ecrã a pedir-lhe para confirmar a eliminação do grupo de recursos.
|
|
Passos seguintes
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, pode consultar os seus dados com a API para Tabela.