Guia de início rápido: usar o Azure Cosmos DB para NoSQL com o SDK do Azure para Node.js

• Aplica-se a:

  ✅ NoSQL

• .NET
• Node.js
• Java
• Python
• Ir

Neste início rápido, você implanta um aplicativo básico do Azure Cosmos DB for Table usando o SDK do Azure para Node.js. O Azure Cosmos DB for Table é um armazenamento de dados sem esquema que permite que os aplicativos armazenem dados de tabela estruturada na nuvem. Você aprende a criar tabelas, linhas e executar tarefas básicas em seu recurso do Azure Cosmos DB usando o SDK do Azure para Node.js.

Documentação | de referência da API Código fonte | da biblioteca Pacote (npm) | Azure Developer CLI

Pré-requisitos

• Azure Developer CLI
• Área de trabalho do Docker
• Node.js 22 ou superior

Se não tiver uma conta do Azure, crie uma conta gratuita antes de começar.

Inicializar o projeto

Use a CLI do Desenvolvedor do Azure (azd) para criar uma conta do Azure Cosmos DB for Table e implantar um aplicativo de exemplo em contêiner. O aplicativo de exemplo usa a biblioteca de cliente para gerenciar, criar, ler e consultar dados de exemplo.

1. Abra um terminal em um diretório vazio.

2. Se você ainda não estiver autenticado, autentique-se na CLI do Desenvolvedor do Azure usando azd auth logino . Siga as etapas especificadas pela ferramenta para autenticar na CLI usando suas credenciais preferidas do Azure.

   azd auth login
   

3. Use azd init para inicializar o projeto.

   azd init --template cosmos-db-nosql-nodejs-quickstart
   

4. Durante a inicialização, configure um nome de ambiente exclusivo.

5. Implante a conta do Azure Cosmos DB usando azd upo . Os modelos Bicep também implantam um aplicativo Web de exemplo.

   azd up
   

6. Durante o processo de provisionamento, selecione sua assinatura, o local desejado e o grupo de recursos de destino. Aguarde a conclusão do processo de provisionamento. O processo pode levar aproximadamente cinco minutos.

7. Depois que o provisionamento dos recursos do Azure for concluído, uma URL para o aplicativo Web em execução será incluída na saída.

   Deploying services (azd deploy)
   
     (✓) Done: Deploying service web
   - Endpoint: <https://[container-app-sub-domain].azurecontainerapps.io>
   
   SUCCESS: Your application was provisioned and deployed to Azure in 5 minutes 0 seconds.
   

8. Use o URL no console para navegar até seu aplicativo Web no navegador. Observe a saída do aplicativo em execução.

Instalar a biblioteca de cliente

A biblioteca do cliente está disponível através do Gerenciador de Pacotes de Nó, como o @azure/cosmos pacote.

1. Abra um terminal e navegue até a /src pasta.

   cd ./src
   

2. Se ainda não estiver instalado, instale o pacote usando npm installo @azure/cosmos .

   npm install --save @azure/cosmos
   

3. Além disso, instale o @azure/identity pacote se ainda não estiver instalado.

   npm install --save @azure/identity
   

4. Abra e revise o arquivo src/package.json para validar se as azure-cosmos entradas e azure-identity existem.

Modelo de objeto

Nome	Descrição
CosmosClient	Essa classe é a classe de cliente principal e é usada para gerenciar metadados ou bancos de dados em toda a conta.
Database	Essa classe representa um banco de dados dentro da conta.
Container	Essa classe é usada principalmente para executar operações de leitura, atualização e exclusão no contêiner ou nos itens armazenados dentro do contêiner.
PartitionKey	Esta classe representa uma chave de partição lógica. Essa classe é necessária para muitas operações e consultas comuns.
SqlQuerySpec	Esta interface representa uma consulta SQL e quaisquer parâmetros de consulta.

Exemplos de código

• Autenticar o cliente
• Obter uma base de dados
• Obter um contentor
• Criar um item
• Obter um item
• Itens de consulta

O código de exemplo no modelo usa um banco de dados chamado cosmicworks e um contêiner chamado products. O products recipiente contém detalhes como nome, categoria, quantidade, um identificador exclusivo e um sinalizador de venda para cada produto. O contêiner usa a /category propriedade como uma chave de partição lógica.

Autenticar o cliente

Este exemplo cria uma nova instância do CosmosClient tipo e autentica usando uma DefaultAzureCredential instância.

const credential = new DefaultAzureCredential();

const client = new CosmosClient({
    '<azure-cosmos-db-nosql-account-endpoint>',
    aadCredentials: credential
});

const credential: TokenCredential = new DefaultAzureCredential();

const client = new CosmosClient({
    '<azure-cosmos-db-nosql-account-endpoint>',
    aadCredentials: credential
});

Obter uma base de dados

Use client.database para recuperar o banco de dados existente chamado cosmicworks.

const database = client.database('cosmicworks');

const database: Database = client.database('cosmicworks');

Obter um contentor

Recupere o contêiner existente products usando database.containero .

const container = database.container('products');

const container: Container = database.container('products');

Criar um item

Crie um novo objeto com todos os membros que você deseja serializar em JSON. Neste exemplo, o tipo tem um identificador exclusivo e campos para categoria, nome, quantidade, preço e venda. Crie um item no contêiner usando container.items.upserto . Este método "upserts" o item efetivamente substituindo o item se ele já existe.

const item = {
    'id': 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
    'category': 'gear-surf-surfboards',
    'name': 'Yamba Surfboard',
    'quantity': 12,
    'price': 850.00,
    'clearance': false
};

let response = await container.items.upsert(item);

const item: Product = {
    'id': 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
    'category': 'gear-surf-surfboards',
    'name': 'Yamba Surfboard',
    'quantity': 12,
    'price': 850.00,
    'clearance': false
};

let response: ItemResponse<Product> = await container.items.upsert<Product>(item);

Ler um item

Execute uma operação de leitura pontual usando os campos identificador exclusivo (id) e chave de partição. Use container.item para obter um ponteiro para um item e item.read para recuperar eficientemente o item específico.

const id = 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb';
const partitionKey = 'gear-surf-surfboards';

let response = await container.item(id, partitionKey).read();
let read_item = response.resource;

const id = 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb';
const partitionKey = 'gear-surf-surfboards';

let response: ItemResponse<Product> = await container.item(id, partitionKey).read<Product>();
let read_item: Product = response.resource!;

Itens de consulta

Execute uma consulta sobre vários itens em um contêiner usando container.items.queryo . Encontre todos os itens dentro de uma categoria especificada usando esta consulta parametrizada:

SELECT * FROM products p WHERE p.category = @category

Obtenha todos os resultados da consulta usando query.fetchAll. Percorra os resultados da consulta.

const querySpec = {
    query: 'SELECT * FROM products p WHERE p.category = @category',
    parameters: [
        {
            name: '@category',
            value: 'gear-surf-surfboards'
        }
    ]
};

let response = await container.items.query(querySpec).fetchAll();
for (let item of response.resources) {
    // Do something
}

const querySpec: SqlQuerySpec = {
    query: 'SELECT * FROM products p WHERE p.category = @category',
    parameters: [
        {
            name: '@category',
            value: 'gear-surf-surfboards'
        }
    ]
};

let response: FeedResponse<Product> = await container.items.query<Product>(querySpec).fetchAll();
for (let item of response.resources) {
    // Do something
}

Clean up resources (Limpar recursos)

Quando você não precisar mais do aplicativo ou recursos de exemplo, remova a implantação correspondente e todos os recursos.

azd down

Conteúdos relacionados

• Guia de início rápido do .NET
• Início Rápido do Java
• Início Rápido do Python
• Ir Guia de início rápido