Início Rápido: Biblioteca de clientes do Azure Cosmos DB for Apache Cassandra para Node.js

Aplica-se a: ✅ Apache Cassanda

Introdução à biblioteca de clientes do Azure Cosmos DB for Apache Cassandra para Node.js armazenar, gerenciar e consultar dados não estruturados. Siga as etapas neste guia para criar uma nova conta, instalar uma biblioteca de clientes Node.js, conectar-se à conta, executar operações comuns e consultar seus dados de exemplo finais.

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

Pré-requisitos

Uma assinatura do Azure
- Se você não tiver uma assinatura do Azure, crie uma conta gratuita antes de começar.

A versão mais recente da CLI do Azure no Azure Cloud Shell.
- Se você preferir executar comandos de referência da CLI localmente, entre na CLI do Azure usando o az login comando.

Node.js 22 ou mais recente

Configurando

Primeiro, configure a conta e o ambiente de desenvolvimento para este guia. Esta seção orienta você pelo processo de criação de uma conta, obtendo suas credenciais e, em seguida, preparando seu ambiente de desenvolvimento.

Criar uma conta

Comece criando uma conta da API para Apache Cassandra. Depois que a conta for criada, crie o keyspace e os recursos da tabela.

Azure CLI
Portal do Azure

Se você ainda não tiver um grupo de recursos de destino, use o az group create comando para criar um novo grupo de recursos em sua assinatura.
```
az group create \
    --name "<resource-group-name>" \
    --location "<location>"
```

Use o az cosmosdb create comando para criar uma nova conta do Azure Cosmos DB para Apache Cassandra com configurações padrão.

az cosmosdb create \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --locations "regionName=<location>" \
    --capabilities "EnableCassandra"

Criar um novo keyspace com az cosmosdb cassandra keyspace create chamado cosmicworks.

az cosmosdb cassandra keyspace create \
    --resource-group "<resource-group-name>" \
    --account-name "<account-name>" \
    --name "cosmicworks"

Crie um novo objeto JSON para representar seu esquema usando um comando Bash de várias linhas. Em seguida, use o az cosmosdb cassandra table create comando para criar uma nova tabela chamada products.

schemaJson=$(cat <<EOF
{
  "columns": [
    {
      "name": "id",
      "type": "text"
    },
    {
      "name": "name",
      "type": "text"
    },
    {
      "name": "category",
      "type": "text"
    },
    {
      "name": "quantity",
      "type": "int"
    },
    {
      "name": "price",
      "type": "decimal"
    },
    {
      "name": "clearance",
      "type": "boolean"
    }
  ],
  "partitionKeys": [
    {
      "name": "id"
    }
  ]
}
EOF
)

az cosmosdb cassandra table create \
    --resource-group "<resource-group-name>" \
    --account-name "<account-name>" \
    --keyspace-name "cosmicworks" \
    --name "product" \
    --schema "$schemaJson"

Entre no portal do Azure (https://portal.azure.com).
Insira o Azure Cosmos DB na barra de pesquisa global.
Em Serviços, selecione Azure Cosmos DB.
No painel do Azure Cosmos DB , selecione Criar e, em seguida, Azure Cosmos DB para Apache Cassandra na guia Outros .
Selecione a conta de banco de dados de unidade de solicitação (RU) como tipo de conta.

No painel Noções básicas, configure as seguintes opções e, em seguida, escolha Revisar + criar:

	Valor
Tipo de carga de trabalho	Aprendizagem
Subscrição	Selecione sua Assinatura do Azure.
Grupo de Recursos	Crie um novo grupo de recursos ou escolha um grupo de recursos existente
Nome da Conta	Forneça um nome global exclusivo
zonas de disponibilidade	Desabilitar
Localidade	Escolha uma região do Azure compatível com sua assinatura

Dica

Você pode deixar as opções não especificadas com os valores padrão. Você também pode configurar a conta para limitar a taxa de transferência total da conta a 1.000 unidades de solicitação por segundo (RU/s) ou habilitar a camada gratuita para minimizar seus custos.

No painel Revisar + criar , aguarde a conclusão bem-sucedida da validação da conta e escolha Criar.
O portal navega automaticamente para o painel Implantação. Aguarde até que a implantação seja concluída.
Depois que a implantação for concluída, selecione Ir para o recurso para navegar até a nova conta da API para Apache Cassandra.
No menu de recursos, selecione a opção Data Explorer .
No Data Explorer, selecione + Nova Tabela.

Na caixa de diálogo Adicionar Tabela , configure as seguintes opções e selecione OK:

	Valor
Keyspace	Criar novo
Nome do keyspace	`cosmicworks`
Nome da tabela	`product`
Esquema de tabela	`(id text, name text, category text, quantity int, price decimal, clearance boolean, PRIMARY KEY (id))`

Dica

Você pode deixar as opções não especificadas com os valores padrão.

Obter credenciais

Agora, obtenha a senha da biblioteca de clientes a ser usada para criar uma conexão com a conta criada recentemente.

Azure CLI
Portal do Azure

Use az cosmosdb show para obter o ponto de contato e o nome de usuário da conta.

az cosmosdb show \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --query "{username:name,contactPoint:documentEndpoint}"

Registre o valor das propriedades contactPoint e username da saída dos comandos anteriores. Os valores dessas propriedades são o ponto de contato e o nome de usuário que você usará posteriormente neste guia para se conectar à conta com a biblioteca.

Use az cosmosdb keys list para obter as chaves da conta.

az cosmosdb keys list \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --type "keys"

Registre o valor da propriedade primaryMasterKey da saída dos comandos anteriores. O valor dessa propriedade é a senha que você usará posteriormente neste guia para se conectar à conta com a biblioteca.

Prepare o ambiente de desenvolvimento

Em seguida, configure seu ambiente de desenvolvimento com um novo projeto e a biblioteca de clientes. Esta etapa é o último pré-requisito necessário antes de passar para o restante deste guia.

Inicie em uma pasta vazia.
Inicialize um novo módulo.
```
npm init es6 --yes
```
Instale o cassandra-driver pacote do Gerenciador de Pacotes do Node (npm).
```
npm install --save cassandra-driver
```
Crie o arquivo index.js .

Inicie em um diretório vazio.
Inicialize um novo módulo.
```
npm init es6 --yes
```
Instale o typescript pacote do Gerenciador de Pacotes do Node (npm).
```
npm install --save-dev typescript
```
Instale o tsx pacote a partir do npm.
```
npm install --save-dev tsx
```
Instale o cassandra-driver pacote a partir do npm.
```
npm install --save cassandra-driver
```

Inicialize o projeto TypeScript usando o compilador (tsc).

npx tsc --init --target es2017 --module es2022 --moduleResolution nodenext

Crie o arquivo index.ts .

Modelo de objeto

	Descrição
`Client`	Representa uma conexão específica com um cluster
`Mapper`	Cliente CQL (Cassandra Query Language) usado para executar consultas

Autenticar cliente

Comece autenticando o cliente usando as credenciais coletadas anteriormente neste guia.

Abra o arquivo index.js no IDE (ambiente de desenvolvimento integrado).

Importe os seguintes tipos do cassandra-driver módulo:

cassandra
cassandra.Client
cassandra.mapping.Mapper
cassandra.auth.PlainTextAuthProvider

import cassandra from 'cassandra-driver';

const { Client } = cassandra;
const { Mapper } = cassandra.mapping;
const { PlainTextAuthProvider } = cassandra.auth;

Crie variáveis constantes de cadeia de caracteres para as credenciais coletadas anteriormente neste guia. Nomeie as variáveis usernamee passwordcontactPoint.
```
const username = '<username>';
const password = '<password>';
const contactPoint = '<contact-point>';
```
Crie outra variável de cadeia de caracteres para a região em que você criou sua conta do Azure Cosmos DB para Apache Cassandra. Nomeie essa variável region.
```
const region = '<azure-region>';
```
Crie um novo PlainTextAuthProvider objeto com as credenciais especificadas nas etapas anteriores.
```
let authProvider = new PlainTextAuthProvider(
    username,
    password
);
```

Crie um Client objeto usando as variáveis de configuração e credencial criadas nas etapas anteriores.

let client = new Client({
    contactPoints: [`${contactPoint}:10350`],
    authProvider: authProvider,
    localDataCenter: region,
    sslOptions: {
        secureProtocol: 'TLSv1_2_method'
    },
});

Conecte-se assíncronamente ao cluster.
```
await client.connect();
```

Crie um novo mapeador para o keyspace cosmicworks e a tabela product. Nomeie o mapeador Product.

const mapper = new Mapper(client, {
    models: {
        'Product': {
            tables: ['product'],
            keyspace: 'cosmicworks'
        }
    }
});

Gere uma instância de mapeador usando a forModel função e o nome do Product mapeador.
```
const productMapper = mapper.forModel('Product');
```

Abra o arquivo index.ts no IDE (ambiente de desenvolvimento integrado).
Importe os seguintes tipos do cassandra-driver módulo:
- cassandra.auth
- cassandra.mapping
- cassandra.types
- cassandra.Client
- cassandra.ClientOptions
- cassandra.mapping.Mapper
- cassandra.auth.PlainTextAuthProvider
```
import { auth, mapping, types, Client, ClientOptions } from 'cassandra-driver';

const { Mapper } = mapping;
const { PlainTextAuthProvider } = auth;
```
Crie variáveis constantes de cadeia de caracteres para as credenciais coletadas anteriormente neste guia. Nomeie as variáveis usernamee passwordcontactPoint.
```
const username: string = '<username>';
const password: string = '<password>';
const contactPoint: string = '<contact-point>';
```
Crie outra variável de cadeia de caracteres para a região em que você criou sua conta do Azure Cosmos DB para Apache Cassandra. Nomeie essa variável region.
```
const region: string = '<azure-region>';
```
Crie um novo PlainTextAuthProvider objeto com as credenciais especificadas nas etapas anteriores.
```
let authProvider = new PlainTextAuthProvider(
    username,
    password
);
```
Crie um objeto anônimo com opções que garantam que você esteja usando o protocolo TLS (segurança da camada de transporte) 1.2.
```
let sslOptions = {
    secureProtocol: 'TLSv1_2_method'
};
```

Crie um ClientOptions objeto usando as variáveis de configuração e credencial criadas nas etapas anteriores.

let clientOptions: ClientOptions = {
    contactPoints: [`${contactPoint}:10350`],
    authProvider: authProvider,
    localDataCenter: region,
    sslOptions: sslOptions
};

Crie um Client objeto usando a clientOptions variável no construtor.
```
let client = new Client(clientOptions);
```
Conecte-se assíncronamente ao cluster.
```
await client.connect();
```

Crie um novo mapeador para o keyspace cosmicworks e a tabela product. Nomeie o mapeador Product.

const mapper = new Mapper( client, {
    models: {
        'Product': {
            tables: ['product'],
            keyspace: 'cosmicworks'
        }
    }
});

Gere uma instância de mapeador usando a forModel função e o nome do Product mapeador.
```
const productMapper = mapper.forModel('Product');
```

Aviso

A validação completa da TLS (segurança da camada de transporte) está desabilitada neste guia para simplificar a autenticação. Para implantações de produção, habilite totalmente a validação.

Inserir ou atualizar dados

Em seguida, insira novos dados em uma tabela. O upserting garante que os dados sejam criados ou substituídos adequadamente, dependendo se os mesmos dados já existem na tabela.

Criar um novo objeto em uma variável chamada product.

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

Invoque a função insert de forma assíncrona, passando a variável product criada na etapa anterior.
```
await productMapper.insert(product);
```

Defina uma nova interface nomeada Product com campos correspondentes à tabela criada anteriormente neste guia.

Tipo

Id string

Name string

Category string

Quantity int

Price decimal

Clearance bool
```
interface Product {
    id: string;
    name: string;
    category: string;
    quantity: number;
    price: number;
    clearance: boolean;
}
```
Dica

No Node.js, você pode criar esse tipo em outro arquivo ou criá-lo no final do arquivo existente.

	Tipo
`Id`	`string`
`Name`	`string`
`Category`	`string`
`Quantity`	`int`
`Price`	`decimal`
`Clearance`	`bool`

Criar um novo objeto do tipo Product. Armazene o objeto em uma variável chamada product.

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

Invoque a função insert de forma assíncrona, passando a variável product criada na etapa anterior.
```
await productMapper.insert(product);
```

Ler dados

Em seguida, leia os dados que foram inseridos anteriormente na tabela.

Criar um objeto anônimo chamado filter. Neste objeto, inclua uma propriedade nomeada id com o mesmo valor que o produto criado anteriormente neste guia.
```
const filter = {
    id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb'
};
```
Invoque a função get do mapeador passando a variável filter. Armazene o resultado em uma variável chamada matchedProduct.
```
let matchedProduct = await productMapper.get(filter);
```

Criar um objeto anônimo chamado filter. Neste objeto, inclua uma propriedade nomeada id com o mesmo valor que o produto criado anteriormente neste guia.
```
const filter = {
    id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb'
};
```
Invoque a função get do mapeador passando a variável filter. Armazene o resultado em uma variável nomeada matchedProduct do tipo Product.
```
let matchedProduct: Product = await productMapper.get(filter);
```

Consultar dados

Por fim, use uma consulta para localizar todos os dados que correspondem a um filtro específico na tabela.

Crie uma nova variável de cadeia de caracteres nomeada query com uma consulta CQL que corresponda a itens com o mesmo category campo.
```
const query = `
SELECT
    *
FROM
    cosmicworks.product
WHERE
    category = :category
ALLOW FILTERING
`;
```
Criar um objeto anônimo chamado params. Neste objeto, inclua uma propriedade nomeada category com o mesmo valor que o produto criado anteriormente neste guia.
```
const params = {
    category: 'gear-surf-surfboards'
};
```
Invoque de forma assíncrona a função execute, passando as variáveis query e params como argumentos. Armazene a propriedade do rows resultado como uma variável chamada matchedProducts.
```
let { rows: matchedProducts } = await client.execute(query, params);
```
Iterar sobre os resultados da consulta invocando o método foreach na matriz de produtos.
```
matchedProducts.forEach(product => {
    // Do something here with each result
});
```

Crie uma nova variável de cadeia de caracteres nomeada query com uma consulta CQL que corresponda a itens com o mesmo category campo.
```
const query: string = `
SELECT
    *
FROM
    cosmicworks.product
WHERE
    category = :category
ALLOW FILTERING
`;
```
Criar um objeto anônimo chamado params. Neste objeto, inclua uma propriedade nomeada category com o mesmo valor que o produto criado anteriormente neste guia.
```
const params = {
    category: 'gear-surf-surfboards'
};
```
Invoque de forma assíncrona a função execute, passando as variáveis query e params como argumentos. Armazene o resultado em uma variável nomeada result do tipo types.ResultSet.
```
let result: types.ResultSet = await client.execute(query, params);
```
Armazene a propriedade do rows resultado como uma variável nomeada matchedProducts do tipo Product[].
```
let matchedProducts: Product[] = result.rows;
```

Iterar sobre os resultados da consulta invocando o método foreach na matriz de produtos.

matchedProducts.forEach((product: Product) => {
    // Do something here with each result
});

Executar o código

Execute o aplicativo recém-criado usando um terminal no diretório do aplicativo.

node index.js

npx tsx index.ts

Limpar os recursos

Quando você não precisar mais da conta, remova a conta de sua assinatura do Azure excluindo o recurso.

Azure CLI
Portal do Azure

az cosmosdb delete \
    --resource-group "<resource-group-name>" \
    --name "<account-name>"

Próxima etapa

Visão geral do Azure Cosmos DB para Apache Cassandra

Comentários

Esta página foi útil?

Last updated on 2025-07-22