Início Rápido: compilar um aplicativo de API de Tabela com Node.js e Azure Cosmos DB
APLICA-SE AO: Table
Neste início rápido, você criará uma conta do Azure Cosmos DB for Table e usará o Data Explorer e um aplicativo Node.js clonado do GitHub para criar tabelas e entidades. O Azure Cosmos DB é um serviço de banco de dados multimodelo que permite criar e consultar rapidamente bancos de dados de documentos, tabelas, pares chave-valor e grafo com funcionalidades de escala horizontal e distribuição global.
Pré-requisitos
- Uma conta do Azure com uma assinatura ativa. Crie um gratuitamente.
- Node.js 0.10.29 e posterior.
- Git.
Aplicativo de exemplo
Você pode clonar ou baixar o aplicativo de exemplo deste tutorial no repositório https://github.com/Azure-Samples/msdocs-azure-data-tables-sdk-js. O repositório de amostras inclui um aplicativo de início e um aplicativo completo.
git clone https://github.com/Azure-Samples/msdocs-azure-data-tables-sdk-js
O aplicativo de exemplo usa dados meteorológicos para demonstrar os recursos da API de Tabela. Os objetos que representam as observações sobre o clima são armazenados e recuperados usando a API de Tabela, incluindo o armazenamento de objetos com propriedades adicionais para demonstrar os recursos sem esquema da API de Tabela.
1 – Criar uma conta do Azure Cosmos DB
Primeiro, você precisa criar uma conta da API de Tabela do Azure Cosmos DB, que conterá as tabelas usadas no aplicativo. Para isso, você pode usar 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.
2 – Criar uma tabela
Em seguida, você precisa criar uma tabela em sua conta do Azure Cosmos DB para que o aplicativo use. Ao contrário de um banco de dados tradicional, você só precisa especificar o nome da tabela e não as propriedades (colunas). À medida que os dados são carregados na tabela, as propriedades (colunas) são criadas automaticamente conforme necessário.
No portal do Azure, siga as etapas a seguir para criar uma tabela dentro de sua conta do Azure Cosmos DB.
3 – Obter a cadeia de conexão do Azure Cosmos DB
Para acessar as tabelas no Azure Cosmos DB, o aplicativo precisará da cadeia de conexão de tabela da conta de Armazenamento do CosmosDB. Você pode conseguir a cadeia de conexão usando o portal do Azure, a CLI do Azure ou o Azure PowerShell.
4 ─ Instalar o SDK de Tabelas de Dados do Azure para JS
Para acessar o Azure Cosmos DB for Table em um aplicativo Node.js, instale o pacote do SDK de Tabelas de Dados do Azure.
npm install @azure/data-tables
5 – Configurar o cliente de Tabela no arquivo env.js
Copie a cadeia de conexão do Azure Cosmos DB ou da conta de Armazenamento do portal do Azure e crie um objeto TableServiceClient usando a cadeia de conexão copiada. Alterne para a pasta 1-strater-app
ou 2-completed-app
. Em seguida, adicione o valor das variáveis de ambiente correspondentes no arquivo configure/env.js
.
const env = {
connectionString:"A connection string to an Azure Storage or Azure Cosmos DB account.",
tableName: "WeatherData",
};
O SDK do Azure se comunica com o Azure usando objetos de cliente para executar operações diferentes no Azure. A classe TableClient
é usada para se comunicar com o Azure Cosmos DB for Table. Normalmente, o aplicativo cria um único objeto serviceClient
por tabela para ser usado em todo o aplicativo.
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 o aplicativo de amostra são implementadas no objeto serviceClient
que está no arquivo tableClient.js
do diretório service.
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 objeto serviceClient
contém um método chamado listEntities
, que permite selecionar linhas da tabela. Como este exemplo não passa nenhum parâmetro ao método, todas as linhas da tabela são selecionadas.
const allRowsEntities = serviceClient.listEntities();
Filtrar as 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 ao método listEntities
. Por exemplo, para 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), você passaria a cadeia de caracteres de filtro a seguir.
PartitionKey eq 'Chicago' and RowKey ge '2021-07-01 12:00' and RowKey le '2021-07-02 12:00'
Todos os operadores de filtro OData estão disponíveis no site do OData, na seção Filtro, em Opção de consulta do sistema.
Quando o parâmetro request.args é passado ao método listEntities
na classe serviceClient
, 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 "and". A cadeia de caracteres de filtro combinada é passada ao método listEntities
no objeto serviceClient
, e somente as linhas correspondentes à cadeia de caracteres de filtro são retornadas. Você pode usar um método semelhante no código para criar cadeias de caracteres de filtro adequadas a seu aplicativo.
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 usando um objeto TableEntity
A maneira mais simples de adicionar dados a uma tabela é usar um objeto TableEntity
. Neste exemplo, mapeamos os dados de um objeto de modelo de entrada para um objeto TableEntity
. Mapeamos as propriedades no objeto de entrada que representam o nome da estação meteorológica e a data/hora de observação para as propriedades PartitionKey
e RowKey
, respectivamente, que juntas formam uma chave exclusiva para a linha na tabela. Em seguida, mapeamos as propriedades adicionais no objeto de modelo de entrada para propriedades de dicionário no objeto TableEntity. Por fim, usamos o método createEntity
do objeto serviceClient
para inserir dados na tabela.
Modifique a função insertEntity
do aplicativo de exemplo para conter o código a seguir.
const insertEntity = async function (entity) {
await serviceClient.createEntity(entity);
};
Executar upsert de dados usando um objeto TableEntity
Se você tentar inserir uma linha em uma tabela com uma combinação de chave de partição/chave de linha que já existe nessa tabela, ocorrerá um erro. Por isso, geralmente é melhor usar o método upsertEntity
em vez de o método createEntity
ao adicionar linhas a uma tabela. Se a combinação de chave/linha de partição determinada já existir na tabela, o método upsertEntity
atualizará a linha atual. Caso contrário, a linha será adicionada à tabela.
const upsertEntity = async function (entity) {
await serviceClient.upsertEntity(entity, "Merge");
};
Inserir ou executar upsert de dados com propriedades variáveis
Esta é uma das vantagens de usar o Azure Cosmos DB for Table: se o objeto carregado em uma tabela contiver propriedades novas, elas serão adicionadas automaticamente à tabela e os valores serão armazenados no Cosmos DB. Não é necessário executar instruções DDL como ALTER TABLE para adicionar colunas como em um banco de dados tradicional.
Com esse modelo, o aplicativo tem flexibilidade para lidar com fontes que adicionam dados ou modificam quais dados devem ser capturados ao longo do tempo, ou quando entradas diferentes fornecem dados diferentes ao aplicativo. No aplicativo de exemplo, podemos simular uma estação meteorológica que envia não apenas os dados meteorológicos base, mas também alguns outros valores. Quando um objeto com essas novas propriedades for armazenado na tabela pela primeira vez, as propriedades correspondentes (colunas) serão adicionadas automaticamente à tabela.
Para inserir ou executar upsert desse objeto usando a API de Tabela, mapeie as propriedades do objeto expansível para um objeto TableEntity
e use o método apropriado, createEntity
ou upsertEntity
, no objeto serviceClient
.
No aplicativo de exemplo, a função upsertEntity
também pode implementar a função de inserir ou executar upsert de 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
Para atualizar entidades, chame o método updateEntity
do objeto serviceClient
.
No aplicativo de exemplo, esse objeto é passado ao método upsertEntity
no objeto serviceClient
. Ele atualiza esse objeto de entidade e usa o método upsertEntity
para salvar as atualizações no banco de dados.
const updateEntity = async function (entity) {
await serviceClient.updateEntity(entity, "Replace");
};
7 – Executar o código
Execute o aplicativo de exemplo para interagir com o Azure Cosmos DB for Table. Na primeira vez que você executar o aplicativo, não haverá dados porque a tabela estará vazia. Use qualquer um dos botões na parte superior do aplicativo para adicionar dados à tabela.
Quando você seleciona o botão Inserir Usando Entidade de Tabela, é aberta uma caixa de diálogo para a inserção ou o upsert de uma nova linha usando um objeto TableEntity
.
Quando você seleciona o botão Inserir usando dados expansíveis, é aberta uma caixa de diálogo para a inserção de um objeto com propriedades personalizadas. Isso demonstra 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 propriedades novas e demonstrar essa funcionalidade.
Use o botão Inserir dados de exemplo para carregar alguns dados de exemplo na tabela do Azure Cosmos DB.
Selecione o item Filtrar Resultados no menu superior para abrir a página Resultados do Filtro. Nesta página, preencha os critérios de filtro para demonstrar como criar uma cláusula de filtro e passá-la ao Azure Cosmos DB for Table.
Limpar os recursos
Quando terminar o aplicativo de exemplo, remova todos os recursos do Azure relacionados a este artigo de sua conta do Azure. Para fazer isso, exclua o grupo de recursos.
Para excluir um grupo de recursos, siga as instruções a seguir no portal do Azure.
Próximas etapas
Neste início rápido, você aprendeu como criar uma conta do BD Cosmos do Azure, como criar uma tabela usando o Data Explorer e como executar um aplicativo. Agora você pode consultar os dados usando a API de Tabela.