Início Rápido: Criar uma API para a aplicação Tabela com Node.js e o Azure Cosmos DB
APLICA-SE A:
Tabela
Neste início rápido, vai criar uma conta do Azure Cosmos DB para Tabela e utilizar Data Explorer e uma aplicação Node.js clonada a partir do GitHub para criar tabelas e entidades. O Azure Cosmos DB é um serviço de base de dados de vários modelos que lhe permite criar e consultar rapidamente as bases de dados de documentos, tabelas, chave-valor e grafos com capacidades globais de distribuição e dimensionamento horizontal.
Pré-requisitos
- Uma conta do Azure com uma subscrição ativa. Crie um gratuitamente.
- Node.js 0,10.29+ .
- Git.
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-data-tables-sdk-js. Tanto uma aplicação inicial como uma aplicação concluída estão incluídas no repositório de exemplo.
git clone https://github.com/Azure-Samples/msdocs-azure-data-tables-sdk-js
A aplicação de exemplo 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.
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. Isto pode ser feito com a 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) serã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. Pode navegar para a página de descrição geral da sua conta do Azure Cosmos DB ao escrever o nome (cosmos-msdocs-tables-sdk-demo-XYZ) da sua conta do Azure Cosmos DB na barra de pesquisa superior e procurar no cabeçalho de recursos. Selecione o nome da sua conta do Azure Cosmos DB para aceder à página de descrição geral. | 
|
| Na página descrição geral, selecione +Adicionar Tabela. A caixa de diálogo Nova Tabela irá deslizar 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 precisará da cadeia de ligação da tabela para a conta de Armazenamento do CosmosDB. 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 Cadeia 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 JS
Para aceder ao Azure Cosmos DB for Table a partir de uma aplicação nodejs, instale o pacote do SDK de Tabelas de Dados do Azure .
npm install @azure/data-tables
5 - Configurar o cliente Tabela no ficheiro env.js
Copie a cadeia de ligação da conta de armazenamento ou do Azure Cosmos DB a partir do portal do Azure e crie um objeto TableServiceClient com a cadeia de ligação copiada. Mude para pasta 1-strater-app ou 2-completed-app. Em seguida, adicione o valor das variáveis de ambiente correspondentes no configure/env.js ficheiro.
const env = {
connectionString:"A connection string to an Azure Storage or Azure Cosmos DB account.",
tableName: "WeatherData",
};
O SDK do Azure comunica com o Azure com objetos de cliente para executar operações diferentes no Azure. A TableClient classe é a classe utilizada para comunicar com o Azure Cosmos DB para Tabela. Normalmente, uma aplicação cria um único serviceClient objeto por tabela para ser utilizada em toda a aplicação.
const { TableClient } = require("@azure/data-tables");
const env = require("../configure/env");
const serviceClient = TableClient.fromConnectionString(
env.connectionString,
env.tableName
);
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 no serviceClient objeto localizado no ficheiro no tableClient.js diretório de serviço .
const { TableClient } = require("@azure/data-tables");
const env = require("../configure/env");
const serviceClient = TableClient.fromConnectionString(
env.connectionString,
env.tableName
);
Obter linhas de uma tabela
O serviceClient objeto contém um método com o nome listEntities que lhe permite selecionar linhas da tabela. Neste exemplo, uma vez que não estão a ser transmitidos parâmetros ao método, todas as linhas serão selecionadas a partir da tabela.
const allRowsEntities = serviceClient.listEntities();
Filtrar linhas devolvidas de uma tabela
Para filtrar as linhas devolvidas a partir de uma tabela, pode transmitir uma cadeia de filtro de estilo OData para o listEntities método . Por exemplo, se quisesse obter todas as leituras meteorológicas para 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' and RowKey le '2021-07-02 12:00'
Pode ver todos os operadores de filtro OData no site OData na secção Filtrar Opção de Consulta do Sistema.
Quando o parâmetro request.args é transmitido para o listEntities método na serviceClient 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 listEntities método no serviceClient objeto e só serã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.
const filterEntities = async function (option) {
/*
You can query data according to existing fields
option provides some conditions to query,eg partitionKey, rowKeyDateTimeStart, rowKeyDateTimeEnd
minTemperature, maxTemperature, minPrecipitation, maxPrecipitation
*/
const filterEntitiesArray = [];
const filters = [];
if (option.partitionKey) {
filters.push(`PartitionKey eq '${option.partitionKey}'`);
}
if (option.rowKeyDateTimeStart) {
filters.push(`RowKey ge '${option.rowKeyDateTimeStart}'`);
}
if (option.rowKeyDateTimeEnd) {
filters.push(`RowKey le '${option.rowKeyDateTimeEnd}'`);
}
if (option.minTemperature !== null) {
filters.push(`Temperature ge ${option.minTemperature}`);
}
if (option.maxTemperature !== null) {
filters.push(`Temperature le ${option.maxTemperature}`);
}
if (option.minPrecipitation !== null) {
filters.push(`Precipitation ge ${option.minPrecipitation}`);
}
if (option.maxPrecipitation !== null) {
filters.push(`Precipitation le ${option.maxPrecipitation}`);
}
const res = serviceClient.listEntities({
queryOptions: {
filter: filters.join(" and "),
},
});
for await (const entity of res) {
filterEntitiesArray.push(entity);
}
return filterEntitiesArray;
};
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 createEntity método no serviceClient objeto é utilizado para inserir dados na tabela.
Modifique a insertEntity função na aplicação de exemplo para conter o seguinte código.
const insertEntity = async function (entity) {
await serviceClient.createEntity(entity);
};
Upsert data using a TableEntity object (Upsert data using a TableEntity object) (Upsert data using a 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 este motivo, muitas vezes é preferível utilizar o upsertEntity em vez do createEntity método ao adicionar linhas a uma tabela. Se a combinação de teclas de linha/chave de partição especificada já existir na tabela, o upsertEntity método atualizará a linha existente. Caso contrário, a linha será adicionada à tabela.
const upsertEntity = async function (entity) {
await serviceClient.upsertEntity(entity, "Merge");
};
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 diferentes entradas 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 base, mas também alguns valores adicionais. Quando um objeto com estas novas propriedades é armazenado na tabela pela primeira vez, as propriedades correspondentes (colunas) serão automaticamente adicionadas à tabela.
Para inserir ou aumentar esse objeto com a API para Tabela, mapeie as propriedades do objeto expansível para um TableEntity objeto e utilize os createEntity métodos ou upsertEntity no serviceClient objeto conforme adequado.
Na aplicação de exemplo, a upsertEntity função também pode implementar a função de inserir ou atualizar dados com propriedades variáveis
const insertEntity = async function (entity) {
await serviceClient.createEntity(entity);
};
const upsertEntity = async function (entity) {
await serviceClient.upsertEntity(entity, "Merge");
};
Atualizar uma entidade
As entidades podem ser atualizadas ao chamar o updateEntity método no serviceClient objeto.
Na aplicação de exemplo, este objeto é transmitido para o upsertEntity método no serviceClient objeto. Atualiza esse objeto de entidade e utiliza o upsertEntity método para guardar as atualizações na base de dados.
const updateEntity = async function (entity) {
await serviceClient.updateEntity(entity, "Replace");
};
7 - Executar o código
Execute a aplicação de exemplo para interagir com o Azure Cosmos DB para Tabela. 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 aumentar a inserção de 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.
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 terminar a aplicação de exemplo, deve remover todos os recursos do Azure relacionados com este artigo da sua conta do Azure. Pode fazê-lo ao eliminar o grupo de recursos.
Um grupo de recursos pode ser eliminado com o 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.