Guia de início rápido: biblioteca de cliente do Azure Cosmos DB para Apache Cassandra para Node.js

Aplica-se a: ✅ Apache Cassanda

Introdução à biblioteca de cliente do Azure Cosmos DB para 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 cliente Node.js, conectar-se à conta, executar operações comuns e consultar seus dados de exemplo finais.

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

Pré-requisitos

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

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

Node.js 22 ou superior

Preparação

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, obtenção de suas credenciais e, em seguida, preparação do ambiente de desenvolvimento.

Criar uma conta

Comece criando uma API para a conta Apache Cassandra. Depois de criar a conta, crie o keyspace e os recursos de 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"

Crie um novo espaço de chave usando az cosmosdb cassandra keyspace create o nome 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 Azure Cosmos DB na barra de pesquisa global.
Em Serviços, selecione Azure Cosmos DB.
No painel Azure Cosmos DB , selecione Criar e, em seguida, Azure Cosmos DB para Apache Cassandra na guia Outros .
Selecione Conta de banco de dados de unidade de solicitação (RU) para o tipo de conta.

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

	Valor
Tipo de carga de trabalho	Aprendizagem
Subscrição	Selecione sua assinatura do Azure
Grupo de Recursos	Criar um novo grupo de recursos ou selecionar um grupo de recursos existente
Nome da Conta	Forneça um nome globalmente exclusivo
Zonas de Disponibilidade	Desativar
Localização	Selecione uma região do Azure suportada para a sua subscrição

Sugestão

Você pode deixar quaisquer opções não especificadas para seus 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 o nível gratuito para minimizar seus custos.

No painel Rever + criar, aguarde até que a validação da sua conta conclua com sucesso e, em seguida, selecione Criar.
O Portal navega automaticamente para o painel Implantação. Aguarde até que a implementação seja concluída.
Quando a implantação estiver concluída, selecione Ir para o recurso para navegar até a nova API para a conta 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 espaço de chave	`cosmicworks`
Nome da tabela	`product`
Esquema da tabela	`(id text, name text, category text, quantity int, price decimal, clearance boolean, PRIMARY KEY (id))`

Sugestão

Você pode deixar quaisquer opções não especificadas para seus valores padrão.

Obter credenciais

Agora, obtenha a senha para a biblioteca do cliente usar 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}"

Registe o valor das propriedades contactPoint e username a partir da saída dos comandos anteriores. Os valores dessas propriedades são o ponto de contato e o nome de usuário que você usa 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"

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

Preparar o ambiente de desenvolvimento

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

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

Comece em um diretório vazio.
Inicialize um novo módulo.
```
npm init es6 --yes
```
Instale o pacote typescript a partir do Gestor de Pacotes Node (npm).
```
npm install --save-dev typescript
```
Instale o pacote tsx do npm.
```
npm install --save-dev tsx
```
Instale o pacote cassandra-driver 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 Cassandra Query Language (CQL) usado para executar consultas

Autenticar cliente

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

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

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 username, passworde contactPoint.
```
const username = '<username>';
const password = '<password>';
const contactPoint = '<contact-point>';
```
Crie outra variável de cadeia de caracteres para a região onde você criou sua conta do Azure Cosmos DB para Apache Cassandra. Nomeie esta 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 credencial e configuração criadas nas etapas anteriores.

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

Conecte-se de forma assíncrona ao cluster.
```
await client.connect();
```

Crie um novo mapeador direcionando o espaço de chave cosmicworks e a tabela product. Nomeie o mapeador Product.

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

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

Abra o arquivo index.ts em seu ambiente de desenvolvimento integrado (IDE).
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 username, passworde contactPoint.
```
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 onde você criou sua conta do Azure Cosmos DB para Apache Cassandra. Nomeie esta 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 garantem que você esteja usando o protocolo TLS (Transport Layer Security) 1.2.
```
let sslOptions = {
    secureProtocol: 'TLSv1_2_method'
};
```

Crie um ClientOptions objeto usando as variáveis de credencial e configuração 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 de forma assíncrona ao cluster.
```
await client.connect();
```

Crie um novo mapeador direcionando o espaço de chave cosmicworks e a tabela product. Nomeie o mapeador Product.

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

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

Advertência

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

Atualizar ou inserir dados

Em seguida, atualize novos dados para uma tabela. A atualização garante que os dados sejam criados ou substituídos adequadamente, dependendo se os mesmos dados já existem na tabela.

Crie 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 de forma assíncrona a função insert, 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;
}
```
Sugestão

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`

Crie 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 de forma assíncrona a função insert, 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.

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

Crie um objeto anônimo chamado filter. Neste objeto, inclua uma propriedade nomeada id com o mesmo valor do produto criado anteriormente neste guia.
```
const filter = {
    id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb'
};
```
Invoque a função do mapeador passando a variável get. Armazene o resultado em uma variável chamada 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
`;
```
Crie um objeto anônimo chamado params. Neste objeto, inclua uma propriedade nomeada category com o mesmo valor do produto criado anteriormente neste guia.
```
const params = {
    category: 'gear-surf-surfboards'
};
```
Invoque assincronamente 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);
```
Itere sobre os resultados da consulta invocando o foreach método 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
`;
```
Crie um objeto anônimo chamado params. Neste objeto, inclua uma propriedade nomeada category com o mesmo valor do produto criado anteriormente neste guia.
```
const params = {
    category: 'gear-surf-surfboards'
};
```
Invoque assincronamente a função execute passando as variáveis query e params como argumentos. Armazene o resultado em uma variável chamada result do tipo types.ResultSet.
```
let result: types.ResultSet = await client.execute(query, params);
```
Armazene a propriedade do rows resultado como uma variável denominada matchedProducts do tipo Product[].
```
let matchedProducts: Product[] = result.rows;
```

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

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

Execute o código

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

node index.js

npx tsx index.ts

Limpeza de recursos

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

Azure CLI
portal do Azure

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

Próximo passo

Visão geral do Azure Cosmos DB para Apache Cassandra

Comentários

Esta página foi útil?

Last updated on 2025-07-21