빠른 시작: Node.js를 사용하여 Azure Cosmos DB SQL API 계정에 연결하고 데이터 쿼리

적용 대상: SQL API

이 빠른 시작에서는 Azure Portal 및 GitHub에서 복제된 Node.js 앱을 사용하여 Azure Cosmos DB SQL API 계정을 만들고 관리합니다. Azure Cosmos DB는 글로벌 배포 및 수평적 크기 조정 기능을 사용하여 문서, 테이블, 키 값 및 그래프 데이터베이스를 빠르게 만들고 쿼리할 수 있는 다중 모델 데이터베이스 서비스입니다.

연습 비디오

이 문서의 내용에 대한 전체 연습을 보려면 이 비디오를 시청하세요.

필수 구성 요소

Azure Cosmos 계정 만들기

이 빠른 시작을 위해 Azure Cosmos DB 체험 옵션을 사용하여 Azure Cosmos 계정을 만들 수 있습니다.

  1. Azure Cosmos DB 체험 페이지로 이동합니다.

  2. SQL API 계정을 선택하고 만들기 를 선택합니다. Microsoft 계정을 사용하여 로그인합니다.

  3. 로그인이 성공하면 Azure Cosmos 계정이 준비되어야 합니다. Azure Portal에서 열기 를 선택하여 새로 만든 계정을 엽니다.

"Azure Cosmos DB 체험" 옵션에는 Azure 구독이 필요하지 않으며, 30일의 제한된 기간 동안 Azure Cosmos 계정을 제공합니다. 더 오랜 기간 동안 Azure Cosmos 계정을 사용하려면 Azure 구독 내에서 계정을 만들어야 합니다.

컨테이너 추가

이제 Azure Portal에서 Data Explorer 도구를 사용하여 데이터베이스 및 컨테이너를 만들 수 있습니다.

  1. Data Explorer > 새 컨테이너 를 선택합니다.

    맨 오른쪽에 컨테이너 추가 영역이 표시되는데, 안 보이면 오른쪽으로 스크롤해야 합니다.

    Azure Portal Data Explorer, 컨테이너 추가 창

  2. 컨테이너 추가 페이지에서 새 컨테이너의 설정을 입력합니다.

    설정 제안 값 Description
    데이터베이스 ID ToDoList 새 데이터베이스의 이름으로 작업 을 입력합니다. 데이터베이스 이름은 1~255자여야 하며, /, \\, #, ? 또는 후행 공백은 포함할 수 없습니다. 컨테이너 간에 처리량 공유 옵션을 선택합니다. 그러면 데이터베이스에 프로비저닝된 처리량을 데이터베이스 내 모든 컨테이너가 공유할 수 있습니다. 이 옵션은 비용 절감에도 도움이 됩니다.
    데이터베이스 처리량 자동 스케일링 또는 수동 처리량을 프로비저닝할 수 있습니다. 수동 처리량을 사용하면 RU/s를 직접 스케일링할 수 있지만 자동 스케일링을 사용하면 시스템에서 사용량에 따라 RU/s를 스케일링할 수 있습니다. 이 예제에서는 수동 을 선택합니다.

    처리량을 400 RU/s(초당 요청 단위)로 유지합니다. 대기 시간을 줄이려면 용량 계산기를 사용하여 필요한 RU/s를 예측하여 나중에 처리량을 스케일 업할 수 있습니다.

    참고: 서버리스 계정에서 새 컨테이너를 만들 때는 이 설정을 사용할 수 없습니다.
    컨테이너 ID Items 새 컨테이너의 이름으로 Items 를 입력합니다. 컨테이너 ID에는 데이터베이스 이름과 동일한 문자 요구 사항이 적용됩니다.
    파티션 키 /category 이 문서에 설명된 샘플은 파티션 키로 /category 를 사용합니다.

    이 예제에서는 고유 키 를 추가하거나 분석 저장소 를 설정하지 마세요. 고유 키를 사용하면 분할 키당 하나 이상의 값의 고유성을 보장하여 데이터베이스에 데이터 무결성 레이어를 추가할 수 있습니다. 자세한 내용은 Azure Cosmos DB의 고유 키를 참조하세요. 분석 저장소는 트랜잭션 워크로드에 영향을 주지 않으면서 운영 데이터에 대한 대규모 분석을 사용하도록 설정하는 데 사용됩니다.

    확인 을 선택합니다. Data Explorer에 새 데이터베이스와 컨테이너가 표시됩니다.

샘플 데이터 추가

이제 데이터 탐색기를 사용하여 새 컨테이너에 데이터를 추가할 수 있습니다.

  1. Data Explorer 에서 Tasks 데이터베이스를 확장하고 Items 컨테이너를 확장합니다. 항목 을 선택한 다음, 새 항목 을 선택합니다.

    Azure Portal의 데이터 탐색기에서 새 문서 만들기

  2. 이제 다음과 같은 구조를 사용하여 컨테이너에 문서를 추가합니다.

    {
        "id": "1",
        "category": "personal",
        "name": "groceries",
        "description": "Pick up apples and strawberries.",
        "isComplete": false
    }
    
  3. 문서 탭에 json을 추가했으면 저장 을 선택합니다.

    Azure Portal의 Azure Data Explorer에서 Json 데이터를 복사하고 저장을 선택합니다.

  4. id 속성에 대한 고유한 값을 삽입하는 경우 둘 이상의 문서를 만들고 저장하며 다른 속성을 적합하게 변경합니다. Azure Cosmos DB가 데이터에 어떠한 스키마도 적용하지 않으므로 새 문서는 사용자가 원하는 어떠한 구조든 가질 수 있습니다.

데이터 쿼리

데이터 탐색기에서 쿼리를 사용하여 데이터를 검색하고 필터링할 수 있습니다.

  1. 데이터 탐색기의 항목 탭 위쪽에서 기본 SELECT * FROM c 쿼리를 검토합니다. 이 쿼리는 ID로 정렬된 컨테이너에서 모든 문서를 검색하고 표시됩니다.

    데이터 탐색기의 기본 쿼리는 SELECT * FROM c입니다.

  2. 쿼리를 변경하려면 필터 편집 을 선택하고 기본 쿼리를 ORDER BY c._ts DESC로 변경한 다음, 필터 적용 을 선택합니다.

    ORDER BY c._ts DESC를 추가하고 필터 적용을 클릭하여 기본 쿼리 변경

    수정된 쿼리는 해당 타임스탬프에 따라 내림차순으로 문서를 표시합니다. 따라서 이제 두 번째 문서가 첫 번째로 나열됩니다.

    쿼리를 ORDER BY c._ts DESC로 변경하고 필터 적용을 클릭

SQL 구문에 익숙한 경우 쿼리 조건자 상자에 지원되는 SQL 쿼리를 입력할 수 있습니다. 데이터 탐색기를 사용하여 서버 쪽 비즈니스 논리에 대한 저장 프로시저, UDF 및 트리거를 만들 수도 있습니다.

데이터 탐색기를 사용하면 API에 제공되는 모든 내장 프로그래밍 방식 데이터 액세스 기능에 대해 Azure Portal에서 간편하게 액세스할 수 있습니다. 포털을 사용하여 Azure Cosmos DB 계정에 대한 처리량을 조정하고 키와 연결 문자열을 가져오고, 메트릭과 SLA를 검토할 수 있습니다.

샘플 애플리케이션 복제

이제 GitHub에서 Node.js 앱을 복제하고 연결 문자열을 설정한 다음, 실행해 보겠습니다.

  1. 다음 명령을 실행하여 샘플 리포지토리를 복제합니다. 이 명령은 컴퓨터에서 샘플 앱의 복사본을 만듭니다.

    git clone https://github.com/Azure-Samples/azure-cosmos-db-sql-api-nodejs-getting-started.git
    

코드 검토

이 단계는 선택 사항입니다. Azure Cosmos 데이터베이스 리소스를 코드로 만드는 방법을 알아보려면 다음 코드 조각을 검토하면 됩니다. 그렇지 않으면 연결 문자열 업데이트로 건너뛸 수 있습니다.

이전 버전의 SQL JavaScript SDK에 익숙한 경우 컬렉션문서 라는 용어를 자주 들어 보셨을 것입니다. Azure Cosmos DB가 여러 API 모델을 지원하므로 JavaScript SDK 버전 2.0 이상에서는 컬렉션, 그래프 또는 테이블을 가리키는 일반적인 용어인 컨테이너 와 컨테이너의 콘텐츠를 설명하는 항목 이라는 용어를 사용합니다.

Cosmos DB JavaScript SDK는 "@azure/cosmos"라고 하며 npm에서 설치할 수 있습니다.

npm install @azure/cosmos

다음 코드 조각은 모두 app.js 파일에서 가져옵니다.

  • CosmosClient@azure/cosmos npm 패키지에서 가져옵니다.

    const CosmosClient = require("@azure/cosmos").CosmosClient;
    
  • CosmosClient 개체가 초기화되었습니다.

    const client = new CosmosClient({ endpoint, key });
    
  • "Tasks" 데이터베이스를 선택합니다.

    const database = client.database(databaseId);
    
  • "Items" 컨테이너/컬렉션을 선택합니다.

    const container = database.container(containerId);
    
  • "Items" 컨테이너의 모든 항목을 선택합니다.

    // query to return all items
    const querySpec = {
      query: "SELECT * from c"
    };
    
    const { resources: items } = await container.items
      .query(querySpec)
      .fetchAll();
    
  • 새 항목 만들기

    const { resource: createdItem } = await container.items.create(newItem);
    
  • 항목 업데이트

    const { id, category } = createdItem;
    
    createdItem.isComplete = true;
    const { resource: updatedItem } = await container
      .item(id, category)
      .replace(createdItem);
    
  • 항목 삭제

    const { resource: result } = await container.item(id, category).delete();
    

참고

"Update" 및 "delete" 메서드에서는 container.item()을 호출하여 데이터베이스에서 항목을 선택해야 합니다. 전달된 두 개의 매개 변수는 항목의 ID와 항목의 파티션 키입니다. 이 경우 파티션 키는 "category" 필드의 값입니다.

연결 문자열 업데이트

Azure Portal로 돌아가서 Azure Cosmos 계정의 연결 문자열 세부 정보를 가져옵니다. 앱이 데이터베이스에 연결할 수 있도록 연결 문자열을 앱에 복사합니다.

  1. Azure Portal의 Azure Cosmos DB 계정에서 왼쪽 탐색 영역의 를 선택한 다음, 읽기-쓰기 키 를 선택합니다. 다음 단계에서 화면 오른쪽의 복사 단추를 사용하여 URI 및 기본 키를 app.js 파일에 복사합니다.

    Azure Portal 키 블레이드에서 액세스 키 보기 및 복사

  2. config.js 파일을 엽니다.

  3. 포털에서 URI 값을 복사(복사 단추 사용)하고 이 값을 config.js 에서 엔드포인트 키 값으로 만듭니다.

    endpoint: "<Your Azure Cosmos account URI>"

  4. 그런 다음, 포털에서 사용자의 기본 키 값을 복사하고 config.jsconfig.key 값으로 만듭니다. 이제 Azure Cosmos DB와 통신하는 데 필요한 모든 정보로 앱이 업데이트되었습니다.

    key: "<Your Azure Cosmos account key>"

앱 실행

  1. 터미널에서 npm install을 실행하여 "@azure/cosmos" npm 패키지를 설치합니다.

  2. 터미널에서 node app.js을 실행하여 노드 애플리케이션을 시작합니다.

  3. 이 빠른 시작의 앞부분에서 만든 두 항목이 나열됩니다. 새 항목이 생성됩니다. 해당 항목의 "isComplete" 플래그는 "true"로 업데이트된 다음, 마지막으로 항목이 삭제됩니다.

이 샘플 애플리케이션을 계속 실험하거나 Data Explorer로 돌아가서 데이터를 수정 및 작업할 수 있습니다.

Azure Portal에서 SLA 검토

Azure Portal에서는 Cosmos DB 계정 처리량, 스토리지, 가용성, 대기 시간 및 일관성을 모니터링합니다. Azure Cosmos DB SLA(서비스 수준 계약)와 관련된 메트릭 차트에는 실제 성능 대비 SLA 값이 표시됩니다. 이 메트릭 모음을 통해 SLA를 투명하게 모니터링할 수 있습니다.

메트릭 및 SLA를 검토하려면 다음을 수행합니다.

  1. Cosmos DB 계정의 탐색 메뉴에서 메트릭 을 선택합니다.

  2. 대기 시간 과 같은 탭을 선택하고, 오른쪽에서 시간 프레임을 선택합니다. 차트의 실제SLA 줄을 비교합니다.

    Azure Cosmos DB 메트릭 도구 모음

  3. 다른 탭의 메트릭을 검토합니다.

다음 단계

이 빠른 시작에서는 Azure Cosmos DB 계정을 만들고, 데이터 탐색기를 사용하여 컨테이너를 만들고, Node.js 앱을 실행하는 방법을 알아보았습니다. 이제 사용자의 Azure Cosmos DB 계정에 추가 데이터를 가져올 수 있습니다.

Azure Cosmos DB로 마이그레이션하기 위한 용량 계획을 수행하려고 하나요? 용량 계획을 위해 기존 데이터베이스 클러스터에 대한 정보를 사용할 수 있습니다.