Início Rápido: Biblioteca do Azure Cosmos DB for NoSQL para Node.js

APLICA-SE A: NoSQL

• .NET
• Node.js
• Java
• Python
• Go

Comece a usar a biblioteca de clientes do Azure Cosmos DB for NoSQL para Node.js, a fim de consultar dados nos seus contêineres e realizar operações comuns em itens individuais. Siga estas etapas para implantar uma solução mínima no seu ambiente usando o Azure Developer CLI.

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

Pré-requisitos

• Uma conta do Azure com uma assinatura ativa. Crie uma conta gratuitamente.
• Conta do GitHub

• Uma conta do Azure com uma assinatura ativa. Crie uma conta gratuitamente.
• CLI do Desenvolvedor do Azure
• Docker Desktop

Configurando

Implante o contêiner de desenvolvimento deste projeto no seu ambiente. Depois, use o Azure Developer CLI (azd) para criar uma conta do Azure Cosmos DB for NoSQL e implantar um aplicativo de exemplo conteinerizado. O aplicativo de exemplo usa a biblioteca de clientes para gerenciar, criar, ler e consultar dados de exemplo.

Importante

As contas do GitHub incluem um direito a horas de armazenamento e núcleo sem nenhum custo. Para obter mais informações, confira Horas de armazenamento e núcleo incluídas nas contas do GitHub.

1. Abra um terminal no diretório raiz do projeto.

2. Autentique-se no Azure Developer CLI usando azd auth login. Siga as etapas especificadas pela ferramenta para se autenticar na CLI usando suas credenciais preferenciais do Azure.

   azd auth login
   

3. Execute azd init para inicializar o projeto.

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

   Observação

   Este início rápido usa o repositório GitHub do modelo azure-samples/cosmos-db-mongodb-dotnet-quickstart. A Azure Developer CLI clonará automaticamente esse projeto em seu computador se ele ainda não estiver lá.

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

   Dica

   O nome do ambiente também será usado como o nome do grupo de recursos de destino. Neste início rápido, considere o uso de msdocs-cosmos-db.

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

   azd up
   

6. Durante o processo de provisionamento, selecione sua assinatura e o local desejado. Aguarde o processo de provisionamento ser concluído. 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 a URL no console para navegar até seu aplicativo Web no navegador. Observe a saída do aplicativo em execução.

   

Instalar a biblioteca de clientes

A biblioteca de clientes está disponível por meio do Gerenciador de Pacotes do Node, como o pacote @azure/cosmos.

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

   cd ./src
   

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

   npm install --save @azure/cosmos
   

3. Instale também o pacote @azure/identity, caso ainda não esteja instalado.

   npm install --save @azure/identity
   

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

Modelo de objeto

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

Exemplos de código

• Autenticar o cliente
• Obter um banco de dados
• Obter um contêiner
• Criar um item
• Obter um item
• Itens de consulta

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

Autenticar o cliente

As solicitações do aplicativo para a maioria dos serviços do Azure precisam ser autorizadas. Use o tipo DefaultAzureCredential como a maneira preferencial de implementar uma conexão sem senha entre seus aplicativos e o Azure Cosmos DB for NoSQL. DefaultAzureCredential dá suporte a vários métodos de autenticação e determina quais métodos devem ser usados no runtime.

Importante

Você também pode autorizar solicitações para serviços do Azure usando senhas, cadeias de conexão ou outras credenciais diretamente. No entanto, essa abordagem deve ser usada com cautela. Os desenvolvedores devem ser diligentes para nunca expor esses segredos em um local não seguro. Qualquer pessoa que tenha acesso à senha ou à chave secreta poderá se autenticar no serviço de banco de dados. A DefaultAzureCredential oferece benefícios aprimorados de gerenciamento e segurança em relação à chave de conta para permitir a autenticação sem senha, sem o risco de armazenar as chaves.

Esta amostra cria uma instância do tipo CosmosClient e faz a autenticação usando uma instância de DefaultAzureCredential.

JavaScript

const credential = new DefaultAzureCredential();

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

TypeScript

const credential = new DefaultAzureCredential();

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

Obter um banco de dados

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

JavaScript

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

TypeScript

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

Obter um contêiner

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

JavaScript

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

TypeScript

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

Criar um item

Crie um objeto com todos os membros que você deseja serializar em JSON. Neste exemplo, o tipo tem um identificador exclusivo, além de campos para categoria, nome, quantidade, preço e venda. Crie um item no contêiner usando container.items.upsert. Esse método executa upsert no item, substituindo o item efetivamente caso ele já exista.

JavaScript

const item = {
    'id': '70b63682-b93a-4c77-aad2-65501347265f',
    'category': 'gear-surf-surfboards',
    'name': 'Yamba Surfboard',
    'quantity': 12,
    'price': 850.00,
    'clearance': false
};

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

TypeScript

const item: Product = {
    'id': '70b63682-b93a-4c77-aad2-65501347265f',
    '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

Realize uma operação de leitura de ponto usando o identificador exclusivo (id) e os campos de chave de partição. Use container.item para obter um ponteiro para um item e item.read para recuperar com eficiência o item específico.

JavaScript

const id = '70b63682-b93a-4c77-aad2-65501347265f';
const partitionKey = 'gear-surf-surfboards';

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

TypeScript

const id = '70b63682-b93a-4c77-aad2-65501347265f';
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

Realize uma consulta em vários itens de um contêiner usando container.items.query. Localize todos os itens de uma categoria especificada usando esta consulta parametrizada:

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

Busce todos os resultados da consulta usando query.fetchAll. Execute um loop pelos resultados da consulta.

JavaScript

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
}

TypeScript

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
}

Conteúdo relacionado

• Início Rápido do .NET
• Início Rápido do Java
• Início Rápido do Python
• Início Rápido do Go