Guia de início rápido: criar uma API para o aplicativo Table com o Node.js e o Azure Cosmos DB
APLICA-SE A: 
Tabela
Neste início rápido, você cria uma conta do Azure Cosmos DB para Tabela e usa 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, chave-valor e gráficos com recursos de distribuição global e escala 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
O aplicativo de exemplo para este tutorial pode ser clonado ou baixado do repositório https://github.com/Azure-Samples/msdocs-azure-data-tables-sdk-js. Tanto um aplicativo inicial quanto um aplicativo concluído são incluídos no repositório de exemplo.
git clone https://github.com/Azure-Samples/msdocs-azure-data-tables-sdk-js
O aplicativo de exemplo 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 adicionais para demonstrar os recursos sem esquema da API para Tabela.
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. Isso pode ser feito usando 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) serã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. Você pode navegar até a página de visão geral da sua conta do Azure Cosmos DB digitando o nome (cosmos-msdocs-tables-sdk-demo-XYZ) da sua conta do Azure Cosmos DB na barra de pesquisa superior e procurando sob o título de recursos. Selecione o nome da sua conta do Azure Cosmos DB para ir para a página de visão geral. | 
|
| Na página de visão geral, selecione +Adicionar tabela. A caixa de diálogo Nova Tabela 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 conexão do Azure Cosmos DB
Para acessar sua(s) tabela(s) no Azure Cosmos DB, seu aplicativo precisará da cadeia de conexão de tabela para a conta de Armazenamento do CosmosDB. 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 Cadeia 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 para a 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 JS
Para acessar o Azure Cosmos DB for Table a partir de um aplicativo nodejs, instale o pacote SDK das Tabelas de Dados do Azure.
npm install @azure/data-tables
5 - Configurar o cliente Table no arquivo env.js
Copie sua cadeia de conexão do Azure Cosmos DB ou da conta de armazenamento do portal do Azure e crie um objeto TableServiceClient usando sua 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 configure/env.js arquivo.
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 TableClient classe é a classe usada para se comunicar com o Azure Cosmos DB for Table. Um aplicativo normalmente criará um único serviceClient objeto 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 exemplo são implementadas no serviceClient objeto localizado no tableClient.js arquivo no 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 chamado listEntities que permite selecionar linhas da tabela. Neste exemplo, como nenhum parâmetro está sendo passado para o método, todas as linhas serão selecionadas na tabela.
const allRowsEntities = serviceClient.listEntities();
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 listEntities 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' and RowKey le '2021-07-02 12:00'
Você pode exibir todos os operadores de filtro OData no site OData na seção Opção de consulta do sistema de filtro.
Quando o serviceClient parâmetro request.args é passado para o listEntities 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 listEntitiesserviceClient método no objeto e somente as linhas correspondentes à cadeia de caracteres de filtro serã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.
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 é 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 adicionais no objeto de modelo de entrada são mapeadas para propriedades de dicionário no objeto TableEntity. Finalmente, o createEntityserviceClient método no objeto é usado para inserir dados na tabela.
Modifique a insertEntity função no aplicativo de exemplo para conter o código a seguir.
const insertEntity = async function (entity) {
await serviceClient.createEntity(entity);
};
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 upsertEntity método em vez do createEntity 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 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 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 adicionais. Quando um objeto com essas novas propriedades é armazenado na tabela pela primeira vez, as propriedades correspondentes (colunas) serã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 createEntity métodos ou upsertEntity no serviceClient objeto conforme apropriado.
No aplicativo 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 chamando o updateEntity método no serviceClient objeto.
No aplicativo de exemplo, esse objeto é passado para o upsertEntity método no serviceClient objeto. Ele atualiza esse objeto de entidade e usa o upsertEntity método para salvar as atualizações no banco de dados.
const updateEntity = async function (entity) {
await serviceClient.updateEntity(entity, "Replace");
};
7 - Execute 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 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.
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 fazer isso 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