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

• .NET
• Node.js
• Java
• Píton
• Ir
• Ferrugem

Neste início rápido, você implanta um aplicativo básico do Azure Cosmos DB para NoSQL usando o SDK do Azure para Node.js. O Azure Cosmos DB para NoSQL é um armazenamento de dados sem esquema que permite que os aplicativos armazenem dados não estruturados na nuvem. Consulte dados em seus contêineres e execute operações comuns em itens individuais 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 para NoSQL 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 não estiver autenticado, efetue a autenticação na linha de comando do desenvolvedor do Azure usando azd auth login. 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 up. Os modelos Bicep também implantam uma aplicação 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 Node Package Manager, como pacote @azure/cosmos.

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

   cd ./src
   

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

   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.

Importar bibliotecas

Importe os tipos DefaultAzureCredential e CosmosClient para o código da sua aplicação.

import { DefaultAzureCredential } from '@azure/identity';
import { CosmosClient } from '@azure/cosmos';

Importe todos os tipos necessários para o código da sua aplicação.

import { PagedAsyncIterableIterator } from '@azure/core-paging';
import { DefaultAzureCredential, TokenCredential } from '@azure/identity';
import { Container, CosmosClient, Database, FeedResponse, ItemResponse, SqlQuerySpec } from '@azure/cosmos';

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({
    endpoint: '<azure-cosmos-db-nosql-account-endpoint>',
    aadCredentials: credential
});

const credential: TokenCredential = new DefaultAzureCredential();

const client = new CosmosClient({
    endpoint: '<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');

Obtenha um contentor

Recupere o contentor existente products usando database.container.

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.upsert. Este método atualiza ou insere o item, substituindo-o se ele já existir.

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 num recipiente usando container.items.query. 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
}

Explore os seus dados

Use a extensão do Visual Studio Code para Azure Cosmos DB para explorar os seus dados NoSQL. Você pode executar operações principais do banco de dados, incluindo, mas não limitado a:

• Executando consultas usando um álbum de recortes ou o editor de consultas
• Modificando, atualizando, criando e excluindo itens
• Importando dados em massa de outras fontes
• Gerenciando bancos de dados e contêineres

Para obter mais informações, consulte Como usar a extensão de código do Visual Studio para explorar o Azure Cosmos DB para dados NoSQL.

Limpar recursos

Quando já não precisar da aplicação ou dos recursos de exemplo, remova a implementaçã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
• Go Guia de Início Rápido
• Guia de início rápido de Rust