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

아티클
08/15/2024

적용 대상: 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()로 이름이 바뀌었습니다.
이제 Pages가 일반 JS 개체 대신 적절한 Response 개체가 되었습니다.
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') }

기본 다중 지역 쓰기

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

적절한 오류 개체

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

새로운 기능

사용자가 취소할 수 있는 요청

내부적으로 가져오기를 이동하면 브라우저 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를 사용하면 브라우저 사용자에게 가장 적합한 환경을 사용할 수 있습니다.

요청 내부를 인출로 바꾸기(#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 서비스 페이지를 참조하세요.

다음을 통해 공유