빠른 시작: Node.js 및 Azure Cosmos DB를 사용하여 Table용 API 앱 빌드
적용 대상: 
테이블
이 빠른 시작에서는 Azure Cosmos DB Table용 API 계정을 만들고 GitHub에서 복제된 데이터 탐색기 및 Node.js 앱을 사용하여 테이블과 엔터티를 만듭니다. Azure Cosmos DB는 글로벌 배포 및 수평적 크기 조정 기능을 사용하여 문서, 테이블, 키 값 및 그래프 데이터베이스를 빠르게 만들고 쿼리할 수 있는 다중 모델 데이터베이스 서비스입니다.
필수 조건
- 활성 구독이 있는 Azure 계정. 체험 계정 만들기
- Node.js 0.10.29 이상.
- Git
샘플 응용 프로그램
이 자습서의 샘플 애플리케이션은 리포지토리 https://github.com/Azure-Samples/msdocs-azure-data-tables-sdk-js에서 복제하거나 다운로드할 수 있습니다. 시작 및 완료된 앱은 모두 샘플 리포지토리에 포함됩니다.
git clone https://github.com/Azure-Samples/msdocs-azure-data-tables-sdk-js
샘플 애플리케이션은 날씨 데이터를 예제로 사용하여 API for Table의 기능을 보여 줍니다. 날씨 관측을 나타내는 개체는 테이블용 API를 사용하여 저장 및 검색됩니다. 여기에는 테이블용 API의 스키마 없는 기능을 보여 주기 위해 추가 속성이 있는 개체 저장이 포함됩니다.
1 - Azure Cosmos DB 계정 만들기
먼저 애플리케이션에서 사용되는 테이블을 포함할 Azure Cosmos DB Tables API 계정을 만들어야 합니다. 이 작업은 Azure Portal, Azure CLI 또는 Azure PowerShell을 사용하여 수행할 수 있습니다.
Azure Portal에 로그인하고 다음 단계에 따라 Azure Cosmos DB 계정을 만듭니다.
| 지침 | 스크린샷 |
|---|---|
Azure Portal에서 다음을 수행합니다.
|
|
| Azure Cosmos DB 페이지에서 +만들기를 선택합니다. | 
|
| API 옵션 선택 페이지에서 Azure Table 옵션을 선택합니다. | 
|
Azure Cosmos DB 계정 만들기 - Azure Table 페이지에서 다음과 같이 양식을 작성합니다.
|
|
2 - 테이블 만들기
다음으로 애플리케이션에서 사용할 Azure Cosmos DB 계정 내에 테이블을 만들어야 합니다. 기존 데이터베이스와 달리, 테이블의 속성(열)이 아니라 테이블의 이름만 지정하면 됩니다. 데이터가 테이블에 로드되면 필요에 따라 속성(열)이 자동으로 만들어집니다.
Azure Portal에서 다음 단계를 완료하여 Azure Cosmos DB 계정 내에 테이블을 만듭니다.
| 지침 | 스크린샷 |
|---|---|
| Azure Portal에서 Azure Cosmos DB 계정의 개요 페이지로 이동합니다. 위쪽 검색 창에 Azure Cosmos DB 계정의 이름(cosmos-msdocs-tables-sdk-demo-XYZ)을 입력하고 리소스 제목 아래를 보면 Azure Cosmos DB 계정의 개요 페이지로 이동할 수 있습니다. Azure Cosmos DB 계정의 이름을 선택하여 개요 페이지로 이동합니다. | 
|
| 개요 페이지에서 +테이블 추가를 선택합니다. 새 테이블 대화 상자가 페이지의 오른쪽에서 서서히 표시됩니다. | 
|
새 테이블 대화 상자에서 다음과 같이 양식을 작성합니다.
|
|
3 - Azure Cosmos DB 연결 문자열 가져오기
Azure Cosmos DB의 테이블에 액세스하려면 앱에 CosmosDB Storage 계정에 대한 테이블 연결 문자열이 필요합니다. 이 연결 문자열은 Azure Portal, Azure CLI 또는 Azure PowerShell을 사용하여 검색할 수 있습니다.
| 지침 | 스크린샷 |
|---|---|
| Azure Cosmos DB 계정 페이지의 왼쪽에서 설정 머리글 아래에서 연결 문자열이라는 메뉴 항목을 찾아 선택합니다. Azure Cosmos DB 계정에 대한 연결 문자열을 검색할 수 있는 페이지로 이동됩니다. | 
|
| 애플리케이션에서 사용할 기본 연결 문자열 값을 복사합니다. | 
|
4 - Azure Data Tables SDK for JS 설치
nodejs 애플리케이션에서 Azure Cosmos DB for Table에 액세스하려면 Azure Data Tables SDK 패키지를 설치합니다.
npm install @azure/data-tables
5 - env.js 파일에서 테이블 클라이언트 구성
Azure Portal에서 Azure Cosmos DB 또는 Storage 계정 연결 문자열을 복사하고 복사한 연결 문자열을 사용하여 TableServiceClient 개체를 만듭니다. 1-strater-app 또는 2-completed-app 폴더로 전환합니다. 그런 다음, configure/env.js 파일의 해당 환경 변수 값을 추가합니다.
const env = {
connectionString:"A connection string to an Azure Storage or Azure Cosmos DB account.",
tableName: "WeatherData",
};
Azure SDK는 클라이언트 개체를 통해 Azure와 통신하여 Azure에 대해 다양한 작업을 실행합니다. TableClient 클래스는 Azure Cosmos DB Table과의 통신을 위해 사용되는 클래스입니다. 애플리케이션은 일반적으로 애플리케이션 전체에서 사용할 serviceClient 개체를 테이블마다 하나씩 만듭니다.
const { TableClient } = require("@azure/data-tables");
const env = require("../configure/env");
const serviceClient = TableClient.fromConnectionString(
env.connectionString,
env.tableName
);
6 - Azure Cosmos DB 테이블 작업 구현
샘플 앱의 모든 Azure Cosmos DB 테이블 작업은 service 디렉터리 아래의 tableClient.js 파일에 있는 serviceClient 개체에서 구현됩니다.
const { TableClient } = require("@azure/data-tables");
const env = require("../configure/env");
const serviceClient = TableClient.fromConnectionString(
env.connectionString,
env.tableName
);
테이블에서 행 가져오기
serviceClient 개체에는 테이블에서 행을 선택할 수 있게 해주는 listEntities라는 메서드가 포함되어 있습니다. 이 예제에서는 이 메서드에 전달되는 매개 변수가 없으므로 테이블의 모든 행이 선택됩니다.
const allRowsEntities = serviceClient.listEntities();
테이블에서 반환된 행 필터링
테이블에서 반환된 행을 필터링하려면 OData 스타일 필터 문자열을 listEntities 메서드에 전달하면 됩니다. 예를 들어 2021년 7월 1일 자정부터 2021년 7월 2일 자정(포함) 사이의 모든 시카고 날씨 판독값을 가져오려면 다음 필터 문자열을 전달합니다.
PartitionKey eq 'Chicago' and RowKey ge '2021-07-01 12:00' and RowKey le '2021-07-02 12:00'
OData 웹 사이트의 필터 시스템 쿼리 옵션 섹션에서 모든 OData 필터 연산자를 확인할 수 있습니다.
request.args 매개변수가 serviceClient 클래스의 listEntities 메서드에 전달되면 null이 아닌 각 속성 값에 대한 필터 문자열이 생성됩니다. 그런 다음, 모든 값을 "and" 절과 조인하여 결합된 필터 문자열을 만듭니다. 이 결합된 필터 문자열은 listEntities 개체의 serviceClient 메서드에 전달되며 필터 문자열과 일치하는 행만 반환됩니다. 비슷한 메서드를 코드에 사용하여 애플리케이션에 필요한 적절한 필터 문자열을 생성할 수 있습니다.
const filterEntities = async function (option) {
/*
You can query data according to existing fields
option provides some conditions to query,eg partitionKey, rowKeyDateTimeStart, rowKeyDateTimeEnd
minTemperature, maxTemperature, minPrecipitation, maxPrecipitation
*/
const filterEntitiesArray = [];
const filters = [];
if (option.partitionKey) {
filters.push(`PartitionKey eq '${option.partitionKey}'`);
}
if (option.rowKeyDateTimeStart) {
filters.push(`RowKey ge '${option.rowKeyDateTimeStart}'`);
}
if (option.rowKeyDateTimeEnd) {
filters.push(`RowKey le '${option.rowKeyDateTimeEnd}'`);
}
if (option.minTemperature !== null) {
filters.push(`Temperature ge ${option.minTemperature}`);
}
if (option.maxTemperature !== null) {
filters.push(`Temperature le ${option.maxTemperature}`);
}
if (option.minPrecipitation !== null) {
filters.push(`Precipitation ge ${option.minPrecipitation}`);
}
if (option.maxPrecipitation !== null) {
filters.push(`Precipitation le ${option.maxPrecipitation}`);
}
const res = serviceClient.listEntities({
queryOptions: {
filter: filters.join(" and "),
},
});
for await (const entity of res) {
filterEntitiesArray.push(entity);
}
return filterEntitiesArray;
};
TableEntity 개체를 사용하여 데이터 삽입
테이블에 데이터를 추가하는 가장 간단한 방법은 TableEntity 개체를 사용하는 것입니다. 이 예제에서는 데이터가 입력 모델 개체에서 TableEntity 개체로 매핑됩니다. 기상 관측소 이름과 관측 날짜/시간을 나타내는 입력 개체의 속성은 각각 PartitionKey 및 RowKey 속성에 매핑되어 테이블의 행에 대한 고유 키를 형성합니다. 그런 다음, 입력 모델 개체의 추가 속성이 TableEntity 개체의 사전 속성에 매핑됩니다. 마지막으로 serviceClient 개체의 createEntity 메서드를 사용하여 테이블에 데이터를 삽입합니다.
다음 코드를 포함하도록 예제 애플리케이션에서 insertEntity 함수를 수정합니다.
const insertEntity = async function (entity) {
await serviceClient.createEntity(entity);
};
TableEntity 개체를 사용하여 데이터 upsert
해당 테이블에 이미 있는 파티션 키/행 키 조합으로 테이블에 행을 삽입하려고 하면 오류가 발생합니다. 이러한 이유로 테이블에 행을 추가할 때 createEntity 메서드 대신 upsertEntity를 사용하는 것이 좋습니다. 지정된 파티션 키/행 키 조합이 테이블에 이미 있는 경우 upsertEntity 메서드는 기존 행을 업데이트합니다. 그렇지 않으면 행이 테이블에 추가됩니다.
const upsertEntity = async function (entity) {
await serviceClient.upsertEntity(entity, "Merge");
};
변수 속성이 있는 데이터 삽입 또는 upsert
Azure Cosmos DB for Table을 사용할 때의 이점 중 하나는 테이블에 로드되는 개체에 새 속성이 포함된 경우 해당 속성이 테이블에 자동으로 추가되고 값이 Azure Cosmos DB에 저장된다는 것입니다. 기존 데이터베이스에서 하는 것처럼 열을 추가하기 위해 ALTER TABLE과 같은 DDL 문을 실행할 필요가 없습니다.
이 모델은 시간에 따라 캡처해야 하는 데이터를 추가하거나 수정할 수 있는 데이터 원본을 처리할 때 또는 다른 입력에서 애플리케이션에 다른 데이터를 제공할 때 애플리케이션에 유연성을 제공합니다. 샘플 애플리케이션에서는 기본 날씨 데이터뿐 아니라 몇 가지 추가 값도 전송하는 기상 관측소를 시뮬레이션할 수 있습니다. 이러한 새 속성을 가진 개체가 처음으로 테이블에 저장되면 해당 속성(열)이 테이블에 자동으로 추가됩니다.
Table용 API를 사용하여 이러한 개체를 삽입하거나 upsert하려면 확장 가능한 개체의 속성을 TableEntity 개체에 매핑하고, createEntity 개체에서 upsertEntity 또는 serviceClient 메서드를 적절하게 사용합니다.
또한 샘플 애플리케이션에서 upsertEntity 함수는 변수 속성을 사용해서 삽입 또는 upsert 데이터 함수를 구현할 수 있습니다.
const insertEntity = async function (entity) {
await serviceClient.createEntity(entity);
};
const upsertEntity = async function (entity) {
await serviceClient.upsertEntity(entity, "Merge");
};
엔터티 업데이트
serviceClient 개체에서 updateEntity 메서드를 호출하여 엔터티를 업데이트할 수 있습니다.
샘플 앱에서 이 개체는 serviceClient 개체의 upsertEntity 메서드에 전달됩니다. 해당 엔터티 개체를 업데이트하고 upsertEntity 메서드를 사용하여 업데이트를 데이터베이스에 저장합니다.
const updateEntity = async function (entity) {
await serviceClient.updateEntity(entity, "Replace");
};
7 - 코드 실행
샘플 애플리케이션을 실행하여 Azure Cosmos DB for Table과 상호 작용합니다. 애플리케이션을 처음 실행하면 테이블이 비어 있기 때문에 데이터가 없습니다. 애플리케이션 맨 위에 있는 단추를 사용하여 테이블에 데이터를 추가합니다.
테이블 엔터티를 사용하여 삽입 단추를 선택하면 TableEntity 개체를 사용하여 새 행을 삽입하거나 upsert할 수 있는 대화 상자가 열립니다.
확장 가능한 데이터를 사용하여 삽입 단추를 선택하면 사용자 지정 속성이 있는 개체를 삽입할 수 있는 대화 상자가 나타나고 Azure Cosmos DB for Table이 필요할 때 자동으로 테이블에 속성(열)을 추가하는 방법을 보여 줍니다. 사용자 지정 필드 추가 단추를 사용하여 하나 이상의 새 속성을 추가하고 이 기능을 실습해 보세요.
샘플 데이터 삽입 단추를 사용하여 일부 샘플 데이터를 Cosmos DB 테이블에 로드합니다.
위쪽 메뉴에서 결과 필터링 항목을 선택하여 [결과 필터링] 페이지로 이동합니다. 이 페이지에서 필터 조건을 입력하여 필터 절을 작성하고 Azure Cosmos DB for Table에 전달하는 방법을 보여 줍니다.
리소스 정리
샘플 애플리케이션을 마쳤으면 Azure 계정에서 이 문서와 관련된 모든 Azure 리소스를 제거해야 합니다. 이렇게 하려면 리소스 그룹을 삭제합니다.
다음을 수행하여 Azure Portal을 통해 리소스 그룹을 삭제할 수 있습니다.
| 지침 | 스크린샷 |
|---|---|
| 리소스 그룹으로 이동하려면 검색 창에 리소스 그룹의 이름을 입력합니다. 그런 다음, 리소스 그룹 탭에서 리소스 그룹의 이름을 선택합니다. | 
|
| 리소스 그룹 페이지 위쪽에 있는 도구 모음에서 리소스 그룹 삭제를 선택합니다. | 
|
리소스 그룹의 삭제를 확인하는 메시지를 표시하는 대화 상자가 화면 오른쪽에 표시됩니다.
|
|
다음 단계
이 빠른 시작에서, Azure Cosmos DB 계정을 만들고, 데이터 탐색기를 사용하여 테이블을 만들고, 앱을 실행하는 방법을 알아보았습니다. 이제 테이블용 API를 사용하여 데이터를 쿼리할 수 있습니다.