빠른 시작: Node.js 위한 Apache Cassandra용 Azure Cosmos DB 클라이언트 라이브러리

적용 대상: ✅ Apache Cassanda

구조화되지 않은 데이터를 저장, 관리 및 쿼리할 Node.js Azure Cosmos DB for Apache Cassandra 클라이언트 라이브러리를 시작합니다. 이 가이드의 단계에 따라 새 계정을 만들고, Node.js 클라이언트 라이브러리를 설치하고, 계정에 연결하고, 일반적인 작업을 수행하고, 최종 샘플 데이터를 쿼리합니다.

API 참조 설명서 | 라이브러리 소스 코드 | 패키지(npm)

필수 조건

Azure 구독
- Azure 구독이 없는 경우, 시작하기 전에 무료 계정을 만드십시오.

Azure Cloud Shell에서 최신 버전의 Azure CLI입니다.
- CLI 참조 명령을 로컬로 실행하려면 명령을 사용하여 Azure CLI에 로그인합니다 az login .

Node.js 22 이상

설치

먼저 이 가이드에 대한 계정 및 개발 환경을 설정합니다. 이 섹션에서는 계정을 만들고 자격 증명을 얻은 다음 개발 환경을 준비하는 프로세스를 안내합니다.

계정 만들기

먼저 Apache Cassandra 계정에 대한 API를 만듭니다. 계정이 만들어지면 키스페이스 및 테이블 리소스를 만듭니다.

Azure CLI
Azure Portal

대상 리소스 그룹이 아직 없는 경우 이 명령을 사용하여 az group create 구독에 새 리소스 그룹을 만듭니다.
```
az group create \
    --name "<resource-group-name>" \
    --location "<location>"
```

이 az cosmosdb create 명령을 사용하여 기본 설정으로 Apache Cassandra용 새 Azure Cosmos DB 계정을 만듭니다.

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

az cosmosdb cassandra keyspace create을 사용하여 cosmicworks라는 새 키스페이스를 생성합니다.

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

여러 줄 Bash 명령을 사용하여 스키마를 나타내는 새 JSON 개체를 만듭니다. 그런 다음, az cosmosdb cassandra table create 명령을 사용하여 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"

Azure Portal에 로그인합니다(https://portal.azure.com).
전역 검색 창에 Azure Cosmos DB를 입력합니다.
서비스 내에서 Azure Cosmos DB를 선택합니다.
Azure Cosmos DB 창에서 만들기를 선택한 다음, 다른 탭 내에서 Apache Cassandra용 Azure Cosmos DB를 선택합니다.
계정 유형에 대한 RU(요청 단위) 데이터베이스 계정을 선택합니다.

기본 창에서 다음 옵션을 구성한 다음 검토 + 만들기를 선택합니다.

	가치
워크로드 유형	학습
구독	Azure 구독 선택
리소스 그룹	새 리소스 그룹을 만들거나 기존 리소스 그룹을 선택합니다.
계정 이름	전역적으로 고유한 이름 입력
가용성 영역	비활성화
위치	구독에 대해 지원되는 Azure 지역 선택

팁 (조언)

지정하지 않은 옵션은 기본값으로 그대로 둘 수 있습니다. 총 계정 처리량을 초당 1,000개 요청 단위(RU/s)로 제한하거나 무료 계층을 사용하도록 계정을 구성하여 비용을 최소화할 수도 있습니다.

검토 + 만들기 창에서 계정 유효성 검사가 성공적으로 완료될 때까지 기다린 다음 만들기를 선택합니다.
포털이 자동으로 배포 창으로 이동합니다. 배포가 완료되기를 기다립니다.
배포가 완료되면 리소스로 이동하여 Apache Cassandra 계정의 새 API로 이동합니다.
리소스 메뉴에서 데이터 탐색기 옵션을 선택합니다.
데이터 탐색기에서 + 새 테이블을 선택합니다.

테이블 추가 대화 상자에서 다음 옵션을 구성한 다음 확인을 선택합니다.

	가치
Keyspace	새로 만들기
키스페이스 이름	`cosmicworks`
테이블 이름	`product`
테이블 스키마	`(id text, name text, category text, quantity int, price decimal, clearance boolean, PRIMARY KEY (id))`

팁 (조언)

지정하지 않은 옵션은 기본값으로 그대로 둘 수 있습니다.

자격 증명 가져오기

이제 최근에 만든 계정에 대한 연결을 만드는 데 사용할 클라이언트 라이브러리의 암호를 가져옵니다.

Azure CLI
Azure Portal

계정의 연락처 지점 및 사용자 이름을 가져오는 데 사용합니다 az cosmosdb show .

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

이전 명령 출력의 contactPoint 값 및 username 속성을 기록합니다. 이러한 속성의 값은 이 가이드를 진행할 때 라이브러리를 사용하여 계정에 연결하는 데 사용하는 연락처 와 사용자 이름입니다.

계정의 az cosmosdb keys list 가져오는 데 사용합니다.

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

이전 명령의 primaryMasterKey 출력에서 속성 값을 기록합니다. 이 속성의 값은 이 가이드의 뒷부분에서 라이브러리를 사용하여 계정에 연결하는 데 사용하는 암호 입니다.

개발 환경 준비

그런 다음 새 프로젝트 및 클라이언트 라이브러리를 사용하여 개발 환경을 구성합니다. 이 단계는 이 가이드의 나머지 단계로 넘어가기 전에 마지막으로 필요한 필수 구성 요소입니다.

빈 폴더에서 시작합니다.
새 모듈을 초기화합니다.
```
npm init es6 --yes
```
cassandra-driver 노드 패키지 관리자(npm)에서 패키지를 설치합니다.
```
npm install --save cassandra-driver
```
index.js 파일을 만듭니다.

빈 디렉터리에서 시작합니다.
새 모듈을 초기화합니다.
```
npm init es6 --yes
```
typescript 노드 패키지 관리자(npm)에서 패키지를 설치합니다.
```
npm install --save-dev typescript
```
tsx npm에서 패키지를 설치합니다.
```
npm install --save-dev tsx
```
cassandra-driver npm에서 패키지를 설치합니다.
```
npm install --save cassandra-driver
```
컴파일러(tsc)를 사용하여 TypeScript 프로젝트를 초기화합니다.
```
npx tsc --init --target es2017 --module es2022 --moduleResolution nodenext
```
index.ts 파일을 만듭니다.

개체 모델

	설명
`Client`	클러스터에 대한 특정 연결을 나타냅니다.
`Mapper`	쿼리를 실행하는 데 사용되는 CQL(Cassandra 쿼리 언어) 클라이언트

클라이언트 인증

먼저 이 가이드의 앞부분에서 수집한 자격 증명을 사용하여 클라이언트를 인증합니다.

IDE(통합 개발 환경)에서 index.js 파일을 엽니다.

모듈에서 다음 타입을 cassandra-driver 가져옵니다.

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;

이 가이드의 앞부분에서 수집된 자격 증명에 대한 문자열 상수 변수를 만듭니다. 변수 username, password, 및 contactPoint의 이름을 지정하세요.
```
const username = '<username>';
const password = '<password>';
const contactPoint = '<contact-point>';
```
Azure Cosmos DB for Apache Cassandra 계정을 만든 지역에 대한 또 다른 문자열 변수를 만듭니다. 이 변수의 이름을 지정합니다 region.
```
const region = '<azure-region>';
```
이전 단계에서 지정한 자격 증명을 사용하여 새 PlainTextAuthProvider 개체를 만듭니다.
```
let authProvider = new PlainTextAuthProvider(
    username,
    password
);
```

Client 이전 단계에서 만든 자격 증명 및 구성 변수를 사용하여 개체를 만듭니다.

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

클러스터에 비동기적으로 연결합니다.
```
await client.connect();
```

cosmicworks 키스페이스와 product 테이블을 대상으로 하는 새 매퍼를 만드세요. 매퍼 이름을 지정합니다 Product.

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

forModel 함수와 Product 매퍼 이름을 사용하여 매퍼 인스턴스를 생성합니다.
```
const productMapper = mapper.forModel('Product');
```

IDE(통합 개발 환경)에서 index.ts 파일을 엽니다.
모듈에서 다음 타입을 cassandra-driver 가져옵니다.
- 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;
```
이 가이드의 앞부분에서 수집된 자격 증명에 대한 문자열 상수 변수를 만듭니다. 변수 username, password, 및 contactPoint의 이름을 지정하세요.
```
const username: string = '<username>';
const password: string = '<password>';
const contactPoint: string = '<contact-point>';
```
Azure Cosmos DB for Apache Cassandra 계정을 만든 지역에 대한 또 다른 문자열 변수를 만듭니다. 이 변수의 이름을 지정합니다 region.
```
const region: string = '<azure-region>';
```
이전 단계에서 지정한 자격 증명을 사용하여 새 PlainTextAuthProvider 개체를 만듭니다.
```
let authProvider = new PlainTextAuthProvider(
    username,
    password
);
```
TLS(전송 계층 보안) 1.2 프로토콜을 사용하는지 확인하는 옵션을 사용하여 익명 개체를 만듭니다.
```
let sslOptions = {
    secureProtocol: 'TLSv1_2_method'
};
```

ClientOptions 이전 단계에서 만든 자격 증명 및 구성 변수를 사용하여 개체를 만듭니다.

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

Client 생성자에서 변수를 clientOptions 사용하여 개체를 만듭니다.
```
let client = new Client(clientOptions);
```
클러스터에 비동기적으로 연결합니다.
```
await client.connect();
```

cosmicworks 키스페이스와 product 테이블을 대상으로 하는 새 매퍼를 만드세요. 매퍼 이름을 지정합니다 Product.

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

forModel 함수와 Product 매퍼 이름을 사용하여 매퍼 인스턴스를 생성합니다.
```
const productMapper = mapper.forModel('Product');
```

경고

인증을 간소화하기 위해 이 가이드에서는 TLS(전체 전송 계층 보안) 유효성 검사를 사용할 수 없습니다. 프로덕션 배포의 경우 유효성 검사를 완전히 사용하도록 설정합니다.

데이터 Upsert

다음으로 새 데이터를 테이블에 업서트합니다. Upserting은 동일한 데이터가 테이블에 이미 있는지 여부에 따라 데이터를 적절하게 만들거나 바꿉니다.

변수에 새 개체를 만듭니다 product.

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

이전 단계에서 만든 insert 변수를 전달하여 product 함수를 비동기적으로 호출합니다.
```
await productMapper.insert(product);
```

이 가이드의 앞부분에서 만든 테이블에 해당하는 필드로 명명 Product 된 새 인터페이스를 정의합니다.

유형

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;
}
```
팁 (조언)

Node.js다른 파일에 이 형식을 만들거나 기존 파일의 끝에 만들 수 있습니다.

	유형
`Id`	`string`
`Name`	`string`
`Category`	`string`
`Quantity`	`int`
`Price`	`decimal`
`Clearance`	`bool`

형식의 새 개체를 만듭니다 Product. 개체를 변수 product에 저장합니다.

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

이전 단계에서 만든 insert 변수를 전달하여 product 함수를 비동기적으로 호출합니다.
```
await productMapper.insert(product);
```

데이터 읽기

그런 다음, 이전에 테이블에 업서트된 데이터를 읽습니다.

라는 익명 개체를 만듭니다 filter. 이 개체에는 이 가이드의 앞부분에서 만든 제품과 동일한 값으로 명명된 id 속성을 포함합니다.
```
const filter = {
    id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb'
};
```
매퍼의 get 함수를 호출하여 filter 변수를 전달합니다. matchedProduct라는 변수에 결과를 저장합니다.
```
let matchedProduct = await productMapper.get(filter);
```

라는 익명 개체를 만듭니다 filter. 이 개체에는 이 가이드의 앞부분에서 만든 제품과 동일한 값으로 명명된 id 속성을 포함합니다.
```
const filter = {
    id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb'
};
```
매퍼의 get 함수를 호출하여 filter 변수를 전달합니다. 결과를 형식 matchedProduct의 변수 Product에 저장합니다.
```
let matchedProduct: Product = await productMapper.get(filter);
```

쿼리 데이터

마지막으로 쿼리를 사용하여 테이블의 특정 필터와 일치하는 모든 데이터를 찾습니다.

동일한 query 필드가 있는 항목과 일치하는 CQL 쿼리를 사용하여 명명된 category 새 문자열 변수를 만듭니다.
```
const query = `
SELECT
    *
FROM
    cosmicworks.product
WHERE
    category = :category
ALLOW FILTERING
`;
```
라는 익명 개체를 만듭니다 params. 이 개체에는 이 가이드의 앞부분에서 만든 제품과 동일한 값으로 명명된 category 속성을 포함합니다.
```
const params = {
    category: 'gear-surf-surfboards'
};
```
execute 및 query 변수를 인수로 전달하여 params 함수를 비동기적으로 호출합니다. 결과의 rows 속성을 이름이 지정된 matchedProducts변수로 저장합니다.
```
let { rows: matchedProducts } = await client.execute(query, params);
```
제품 배열에서 메서드를 호출하여 foreach 쿼리 결과를 반복합니다.
```
matchedProducts.forEach(product => {
    // Do something here with each result
});
```

동일한 query 필드가 있는 항목과 일치하는 CQL 쿼리를 사용하여 명명된 category 새 문자열 변수를 만듭니다.
```
const query: string = `
SELECT
    *
FROM
    cosmicworks.product
WHERE
    category = :category
ALLOW FILTERING
`;
```
라는 익명 개체를 만듭니다 params. 이 개체에는 이 가이드의 앞부분에서 만든 제품과 동일한 값으로 명명된 category 속성을 포함합니다.
```
const params = {
    category: 'gear-surf-surfboards'
};
```
execute 및 query 변수를 인수로 전달하여 params 함수를 비동기적으로 호출합니다. 결과를 형식 result의 변수 types.ResultSet에 저장합니다.
```
let result: types.ResultSet = await client.execute(query, params);
```
결과의 rows 속성을 matchedProducts 형식의 변수인 Product[]로 저장합니다.
```
let matchedProducts: Product[] = result.rows;
```

제품 배열에서 메서드를 호출하여 foreach 쿼리 결과를 반복합니다.

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

코드 실행

애플리케이션 디렉터리의 터미널을 사용하여 새로 만든 애플리케이션을 실행합니다.

node index.js

npx tsx index.ts

자원을 정리하세요

계정이 더 이상 필요하지 않은 경우 리소스를 삭제하여 Azure 구독에서 계정을 제거합니다.

Azure CLI
Azure Portal

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

다음 단계

Apache Cassandra용 Azure Cosmos DB 개요

피드백

이 페이지가 도움이 되었나요?

Last updated on 2025-07-22