適用於 NoSQL 的 Azure Cosmos DB Node.js SDK：版本資訊和資源

發行項
02/06/2024

適用於： NoSQL

資源	連結
下載 SDK	@azure/cosmos
API 文件	JavaScript SDK 參考檔
SDK 安裝指示	`npm install @azure/cosmos`
參與 SDK	azure-sdk-for-js 存放庫的參與指南
範例	Node.js程式代碼範例
用戶入門教學課程	開始使用 JavaScript SDK
Web 應用程式教學課程	使用 Azure Cosmos DB 建置Node.js Web 應用程式
目前支援的Node.js平臺	LTS 版本的 Node.js

版本資訊

版本歷程記錄會在 azure-sdk-for-js 存放庫中維護，以取得版本的詳細清單，請參閱變更記錄檔。

重大變更的移轉指南

如果您使用的是舊版的 SDK，建議您移轉至 3.0 版本。本節詳述您使用此版本取得的改善，以及 3.0 版本中所做的錯誤修正。

改善的用戶端建構函式選項

建構函式選項已簡化：

masterKey 已重新命名密鑰，並移至最上層
先前在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（）
頁面現在是適當的 Response 物件，而不是一般 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 上擲回

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 現在預設會寫入多個區域。這是先前選擇加入的行為。

適當的錯誤物件

失敗的要求現在會擲回適當的 Error 或 Error 子類別。先前會擲回一般 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呼叫的相同程式代碼來簽署標頭。

產生的標識碼的 UUID

v2 有自定義程式代碼可產生專案標識碼。我們已切換到已知且維護的社區連結庫 uuid。

連接字串

現在可以傳遞從 Azure 入口網站複製的連接字串：

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，但這不是理想的體驗。您需要 Polyfill 數個Node.js內建連結庫，並使用 webpack 或 Parcel 之類的配套程式。 v3 SDK 可讓現用的瀏覽器用戶體驗變得更好。

將要求內部取代為 fetch （#245）
移除緩衝區的使用方式（#330）
移除節點內建使用量，以偏向通用套件/API （#328）
切換至 node-abort-controller （#294）

錯誤修正

修正供應項目讀取並帶回供應項目測試（#224）
修正 EnableEndpointDiscovery （#207）
修正編頁結果上的遺漏 RU （#360）
展開 SQL 查詢參數型態（#346）
將 ttl 新增至 ItemDefinition （#341）
修正 CP 查詢計量（#311）
將 activityId 新增至 FeedResponse （#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 日

常見問題集

如何收到即將淘汰 SDK 的通知？

Microsoft 會在淘汰 SDK 終止支援之前提供 12 個月的提前通知，以利順利轉換至支援的 SDK。我們會透過各種通道通知您：Azure 入口網站、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 服務頁面。