NoSQL용 API용 Azure Cosmos DB Node.js SDK: 릴리스 정보 및 리소스

적용 대상: NoSQL

리소스 링크
SDK 다운로드 @azure/cosmos
API 설명서 JavaScript SDK 참조 설명서
SDK 설치 지침 npm install @azure/cosmos
SDK에 참여 azure-sdk-for-js 리포지토리에 대한 기여 가이드
샘플 Node.js 코드 샘플
시작 자습서 JavaScript SDK 시작
웹앱 자습서 Azure Cosmos DB를 사용하여 Node.js 웹 애플리케이션 빌드
현재 지원되는 Node.js 플랫폼 Node.js의 LTS 버전

릴리스 정보

릴리스 기록은 azure-sdk-for-js 리포지토리에서 유지 관리됩니다. 자세한 릴리스 목록은 변경 로그 파일을 참조하세요.

주요 변경 내용에 대한 마이그레이션 가이드

이전 버전의 SDK를 사용 중인 경우 3.0 버전으로 마이그레이션하는 것이 좋습니다. 이 섹션에서는 이 버전에서 얻을 수 있는 향상된 기능과 3.0 버전에서 수행된 버그 수정에 대해 자세히 설명합니다.

향상된 클라이언트 생성자 옵션

생성자 옵션이 간소화되었습니다.

  • masterKey를 key로 이름 변경하고 최상위 수준으로 이동했습니다.
  • 이전에 options.auth 아래에 있던 속성을 최상위 수준으로 이동했습니다.
// v2
const client = new CosmosClient({
    endpoint: "https://your-database.cosmos.azure.com",
    auth: {
        masterKey: "your-primary-key"
    }
})

// v3
const client = new CosmosClient({
    endpoint: "https://your-database.cosmos.azure.com",
    key: "your-primary-key"
})

간소화된 쿼리 반복기 API

v2에서는 쿼리 결과를 반복하거나 검색하는 다양한 방법이 있었습니다. v3 API를 간소화하고 유사하거나 중복된 API를 제거하려고 노력했습니다.

  • iterator.next() 및 iterator.current()를 제거했습니다. fetchNext()를 사용하여 결과 페이지를 가져옵니다.
  • iterator.forEach()를 제거했습니다. 대신 비동기 반복기를 사용합니다.
  • iterator.executeNext()를 iterator.fetchNext()로 이름을 변경했습니다.
  • iterator.toArray()를 iterator.fetchAll()로 이름을 변경했습니다.
  • 이제 페이지가 일반 JS 개체가 아닌 적절한 응답 개체입니다.
  • const container = client.database(dbId).container(containerId)
// v2
container.items.query('SELECT * from c').toArray()
container.items.query('SELECT * from c').executeNext()
container.items.query('SELECT * from c').forEach(({ body: item }) => { console.log(item.id) })

// v3
container.items.query('SELECT * from c').fetchAll()
container.items.query('SELECT * from c').fetchNext()
for await(const { result: item } in client.databases.readAll().getAsyncIterator()) {
    console.log(item.id)
}

이제 고정 컨테이너가 분할됨

이제 Azure Cosmos DB 서비스는 이전에 고정 컨테이너로 만든 컨테이너를 포함하여 모든 컨테이너에서 파티션 키를 지원합니다. v3 SDK는이 변경 내용을 구현하는 최신 API 버전으로 업데이트되지만 호환성이 손상되지는 않습니다. 작업에 대한 파티션 키를 제공하지 않으면 기존 컨테이너와 문서 모두에서 작동하는 시스템 키가 기본값으로 사용됩니다.

저장 프로시저에 대해 upsert 제거

이전에는 분할되지 않은 컬렉션에 대해 upsert를 허용했지만 API 버전 업데이트에서는 모든 컬렉션이 분할되므로 이를 완전히 제거했습니다.

항목 읽기가 404에서 throw되지 않음

const container = client.database(dbId).container(containerId)

// v2
try {
    container.items.read(id, undefined)
} catch (e) {
    if (e.code === 404) { console.log('item not found') }
}

// v3
const { result: item }  = container.items.read(id, undefined)
if (item === undefined) { console.log('item not found') }

기본 다중 지역 쓰기

이제 SDK는 Azure Cosmos DB 구성에서 지원하는 경우 기본적으로 여러 지역에 씁니다. 이전에는 옵트인 동작이었습니다.

적절한 오류 개체

이제 실패한 요청은 적절한 오류 또는 오류 하위 클래스를 throw합니다. 이전에는 일반 JS 개체를 throw했습니다.

새로운 기능

사용자 취소 가능한 요청

내부적으로 fetch로 이동하면 브라우저가 AbortController API를 사용하여 사용자 취소 가능한 작업을 지원할 수 있습니다. 잠재적으로 여러 요청이 진행 중인 작업(예: 파티션 간 쿼리)의 경우 작업에 대한 모든 요청이 취소됩니다. 최신 브라우저 사용자는 이미 AbortController가 있습니다. Node.js 사용자는 Polyfill 라이브러리를 사용해야 합니다.

 const controller = new AbortController()
 const {result: item} = await items.query('SELECT * from c', { abortSignal: controller.signal});
 controller.abort()

db/container create 작업의 일부로 처리량 설정

const { database }  = client.databases.create({ id: 'my-database', throughput: 10000 })
database.containers.create({ id: 'my-container', throughput: 10000 })

@azure/cosmos-sign

헤더 토큰 생성이 새 라이브러리 @azure/cosmos-sign으로 분할되었습니다. Azure Cosmos DB REST API를 직접 호출하는 모든 사용자는 이를 사용하여 내부에서 @azure/cosmos호출하는 것과 동일한 코드를 사용하여 헤더에 서명할 수 있습니다.

생성된 ID의 UUID

v2에는 항목 ID를 생성하는 사용자 지정 코드가 있습니다. 잘 알려져 있고 유지 관리되는 커뮤니티 라이브러리 uuid로 전환했습니다.

연결 문자열

이제 Azure Portal에서 복사된 연결 문자열을 전달할 수 있습니다.

const client = new CosmosClient("AccountEndpoint=https://test-account.documents.azure.com:443/;AccountKey=c213asdasdefgdfgrtweaYPpgoeCsHbpRTHhxuMsTaw==;")
Add DISTINCT and LIMIT/OFFSET queries (#306)
 const { results } = await items.query('SELECT DISTINCT VALUE r.name FROM ROOT').fetchAll()
 const { results } = await items.query('SELECT * FROM root r OFFSET 1 LIMIT 2').fetchAll()

향상된 브라우저 환경

브라우저에서 v2 SDK를 사용할 수 있었지만 이상적인 환경은 아니었습니다. 여러 node.js 기본 제공 라이브러리를 보충하고 Webpack 또는 Parcel 같은 번들러를 사용해야 했습니다. v3 SDK를 사용하면 브라우저 사용자에게 가장 적합한 환경을 사용할 수 있습니다.

  • 요청 내부 구조를 fetch로 바꿈(#245)
  • 버퍼 사용 제거(#330)
  • 노드 기본 제공 사용 제거 및 노드 유니버설 패키지/API 사용(#328)
  • node-abort-controller로 전환(#294)

버그 수정

  • 제품 읽기 수정 및 제품 테스트 다시 사용(#224)
  • EnableEndpointDiscovery 수정(#207)
  • 페이지가 매겨진 결과에서 누락된 RU 수정(#360)
  • SQL 쿼리 매개 변수 형식 확장(#346)
  • ItemDefinition에 ttl 추가(#341)
  • CP 쿼리 메트릭 수정(#311)
  • FeedResponse에 activityId 추가(#293)
  • _ts 형식을 문자열에서 숫자로 전환(#252)(#295)
  • 요청 요금 집계 수정(#289)
  • 빈 문자열 파티션 키 허용(#277)
  • 충돌 쿼리 형식에 문자열 추가(#237)
  • 컨테이너에 uniqueKeyPolicy 추가(#234)

엔지니어링 시스템

항상 가장 눈에 띄는 변경 사항은 아니지만 팀이 더 나은 코드를 더 빠르게 제공하는 데 도움이 됩니다.

  • 프로덕션 빌드에 롤업 사용(#104)
  • TypeScript 3.5로 업데이트(#327)
  • TS 프로젝트 참조로 변환. 테스트 폴더 추출(#270)
  • noUnusedLocals 및 noUnusedParameters 사용(#275)
  • CI 빌드용 Azure Pipelines YAML(#298)

릴리스 및 사용 중지 날짜

Microsoft는 최신/지원 버전으로 원활히 전환할 수 있도록 SDK 사용 중지 최소 12개월 전에 알림을 제공합니다. 새로운 기능 및 최적화는 현재 SDK에만 추가되어 있으며, 따라서 항상 최신 SDK 버전으로 가능한 한 빨리 업그레이드할 것을 권장합니다. 자세한 내용은 SDK에 대한 Microsoft 지원 정책을 참조하세요.

버전 출시 날짜 사용 중지 날짜
v3 2019년 6월 28일 ---
v2 2018년 9월 24일 2021년 9월 24일
v1 2015년 4월 8일 2020년 8월 30일

FAQ

SDK 사용 중지에 대한 알림을 어떻게 받나요?

Microsoft는 지원되는 SDK로 매끄럽게 전환할 수 있도록 사용 중지되는 SDK 지원이 종료되기 12개월 전에 사전 알림을 제공합니다. Azure Portal, Azure 업데이트, 할당된 서비스 관리자에 대한 직접 통신 등 다양한 통신 채널을 통해 알려드립니다.

12개월 동안 사용 중지 예정된 Azure Cosmos DB SDK를 사용하여 애플리케이션을 제작할 수 있나요?

예, 12개월 알림 기간 동안 사용 중지 예정된 Azure Cosmos DB SDK를 사용하여 애플리케이션을 제작, 배포 및 수정할 수 있습니다. 12개월 알림 기간 동안 지원되는 최신 버전의 Azure Cosmos DB SDK로 적절하게 마이그레이션하는 것이 좋습니다.

사용 중지 날짜 후에는 지원되지 않는 Azure Cosmos DB SDK를 사용하는 애플리케이션은 어떻게 되나요?

사용 중지 날짜가 지나면 Azure Cosmos DB는 더 이상 버그를 수정하거나 새 기능을 추가하거나 사용 중지된 SDK 버전을 지원하지 않습니다. 업그레이드하지 않으려는 경우 SDK의 사용 중지 버전에서 보낸 요청은 Azure Cosmos DB 서비스에서 계속 제공됩니다.

최신 기능과 업데이트를 포함하는 SDK 버전은 무엇인가요?

새 기능 및 업데이트는 지원되는 최신 주요 SDK 버전의 최신 부 버전에만 추가됩니다. 항상 최신 버전을 사용하여 새로운 기능, 성능 향상 및 버그 수정을 활용하는 것이 좋습니다. 사용 중지되지 않은 오래된 버전의 SDK를 사용하는 경우 Azure Cosmos DB 요청이 작동하지만 새로운 기능에 액세스할 수는 없습니다.

마감 날짜 전에 내 애플리케이션을 업데이트할 수 없는 경우 어떻게 해야 하나요?

가능한 한 빨리 최신 SDK로 업그레이드하는 것이 좋습니다. SDK가 사용 중지로 태깅된 후 12개월 내에 애플리케이션을 업데이트해야 합니다. 사용 중지 날짜까지 업데이트할 수 없는 경우 SDK 사용 중지 버전에서 전송된 요청은 Azure Cosmos DB에서 계속 제공되므로 실행 중인 애플리케이션은 계속 작동합니다. 그러나 Azure Cosmos DB는 더 이상 버그를 수정하거나 새 기능을 추가하거나 사용 중지된 SDK 버전을 지원하지 않습니다.

지원 계획이 있고 기술 지원이 필요한 경우 지원 티켓을 제출하여 문의해주세요.

SDK 또는 커넥터에 기능 추가를 요청하려면 어떻게 해야 하나요?

새로운 기능이 모든 SDK 또는 커넥터에 항상 즉시 추가되는 것은 아닙니다. 지원되지 않는 기능 중 추가하려는 기능이 있는 경우 커뮤니티 포럼에 피드백을 추가합니다.

참고 항목

Azure Cosmos DB에 대한 자세한 내용은 Microsoft Azure Cosmos DB 서비스 페이지를 참조하세요.