Azure Cosmos DB Node.js SDK SQL API:版本資訊和資源

適用于 :SQL API

資源 連結
下載 SDK NPM
API 檔 JavaScript SDK 參考檔
SDK 安裝指示 安裝指示
參與 SDK GitHub
樣品 Node.js程式碼範例
入門教學課程 開始使用 JavaScript SDK
Web App 教學課程 使用 Azure Node.js DB 建立Cosmos應用程式
目前支援的平臺 Node.js v12.x - SDK 版本 3.x.x
Node.js v10.x - SDK 版本 3.x.x
Node.js v8.x - SDK 版本 3.x.x
Node.js v6.x - SDK 版本 2.x.x
Node.js v4.2.0- SDK 版本 1.x.x
Node.js 0.12版 - SDK 版本 1.x.x
Node.js 0.10版 - SDK 版本 1.x.x

版本資訊

版本歷程記錄會維持在 azure-sdk-for-js repo 中,有關詳細發行清單,請參閱 changelog 檔案

中斷變更的移移指南

如果您採用舊版 SDK,建議您遷移到 3.0 版本。 本節詳細說明此版本的改良功能,以及 3.0 版本中的錯誤修正。

改良的用戶端安裝器選項

已簡化的構造器選項:

  • masterKey 已重新命名金鑰,並移至最頂層
  • 選項.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"
})

簡化查詢 iterator 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 (id)
// 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)
}

已修正的容器現在已分割

Cosmos服務現在支援所有容器上的分區鍵,包括先前建立為固定容器的容器。 v3 SDK 會更新為可實施此變更的最新 API 版本,但並未中斷。 如果您沒有提供用於作業的分區鍵,我們會預設為可處理您所有現有容器和檔的系統金鑰。

已移除儲存程式的 Upsert

先前已允許非分區集合使用 upsert,但有了 API 版本更新,所有集合會進行分區,所以我們將其完全移除。

專案讀取不會在 404 上顯示

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

// 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,則 SDK 現在預設會寫入Cosmos區域。 這是先前加入宣告的行為。

正確的錯誤物件

失敗的要求現在會拋出正確的錯誤或錯誤子類別。 之前,它們會丟出純文字的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 建立作業的一部分

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

@azure/宇宙符號

頁碼權杖產生被分割成新的文件庫,@azure/cosmos-sign。 任何直接Cosmos REST API 的人,都可以使用我們在 rest/cosmos 中@azure代碼來簽署標題。

產生之 ID 的 UUID

v2 有可產生專案 ID 的自訂程式碼。 我們已切換到已知及維護的社群文件庫 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,但這不是理想的體驗。 您需要將數個內建文件庫node.js多邊形填上,並使用套件 ,例如 Webpack 或包裹。 v3 SDK 為瀏覽器使用者提供更豐富的開箱即用體驗。

  • 以抓取 (#245)
  • 移除緩衝 (#330)
  • 移除節點內建使用量,以利於通用套件/API (#328)
  • 切換到節點中止-控制器 (#294)

錯誤修正

  • 修正已讀取優惠並返回優惠測試 (#224)
  • 修正 EnableEndpointDiscovery (#207)
  • 修正分頁結果 (#360)
  • 展開SQL查詢參數類型 (#346)
  • 新增 ttl 至 ItemDefinition (#341)
  • 修正 CP 查詢度量 (#311)
  • 將 activityId 新增到 FeedResponse (#293)
  • 將_ts字型從字串切換到數位 (#252) (#295)
  • 修正要求費用匯總 (#289)
  • 允許空白字串分區鍵 (#277)
  • 新增字串至衝突查詢類型 (#237)
  • 新增唯一的KeyPolicy至容器 (#234)

工程系統

不一定最顯眼的變更,但能協助我們的小組更快速地提供更好的程式碼。

  • 使用生產版匯總 (#104)
  • 更新至 Typescript 3.5 (#327)
  • 轉換成 TS 專案參照。 解壓縮測試檔案夾 (#270)
  • 啟用 noUnusedLocals 和 noUnusedParameters (#275)
  • Azure Pipelines YAML for CI 建立 (#298)

發行 & 退休日期

Microsoft 在停用 SDK 前 至少 12 個月提供通知,以便順利轉換至較新/支援的版本。 新功能、功能和優化只會新加到目前的 SDK 中,因此建議您一直儘早升級至最新的 SDK 版本。

版本 發行日期 退休日期
3.4.2 2019 年 11 月 7 日 ---
3.4.1 2019 年 11 月 5 日 ---
3.4.0 2019 年 10 月 28 日 ---
3.3.6 2019 年 10 月 14 日 ---
3.3.5 2019 年 10 月 14 日 ---
3.3.4 2019 年 10 月 14 日 ---
3.3.3 2019 年 10 月 3 日 ---
3.3.2 2019 年 10 月 3 日 ---
3.3.1 2019 年 10 月 1 日 ---
3.3.0 2019 年 9 月 24 日 ---
3.2.0 2019 年 8 月 26 日 ---
3.1.1 2019 年 8 月 7 日 ---
3.1.0 2019 年 7 月 26 日 ---
3.0.4 2019 年 7 月 22 日 ---
3.0.3 2019 年 7 月 17 日 ---
3.0.2 2019 年 7 月 9 日 ---
3.0.0 2019 年 6 月 28 日 ---
2.1.5 2019 年 3 月 20 日 ---
2.1.4 2019 年 3 月 15 日 ---
2.1.3 2019 年 3 月 8 日 ---
2.1.2 2019 年 1 月 28 日 ---
2.1.1 2018 年 12 月 5 日 ---
2.1.0 2018 年 12 月 4 日 ---
2.0.5 2018 年 11 月 7 日 ---
2.0.4 2018 年 10 月 30 日 ---
2.0.3 2018 年 10 月 30 日 ---
2.0.2 2018 年 10 月 10 日 ---
2.0.1 2018 年 9 月 25 日 ---
2.0.0 2018 年 9 月 24 日 ---
2.0.0-3 (RC) 2018 年 8 月 2 日 ---
1.14.4 2018 年 5 月 3 日 2020 年 8 月 30 日
1.14.3 2018 年 5 月 3 日 2020 年 8 月 30 日
1.14.2 2017 年 12 月 21 日 2020 年 8 月 30 日
1.14.1 2017 年 11 月 10 日 2020 年 8 月 30 日
1.14.0 2017 年 11 月 9 日 2020 年 8 月 30 日
1.13.0 2017 年 10 月 11 日 2020 年 8 月 30 日
1.12.2 2017 年 8 月 10 日 2020 年 8 月 30 日
1.12.1 2017 年 8 月 10 日 2020 年 8 月 30 日
1.12.0 2017 年 5 月 10 日 2020 年 8 月 30 日
1.11.0 2017 年 3 月 16 日 2020 年 8 月 30 日
1.10.2 2017 年 1 月 27 日 2020 年 8 月 30 日
1.10.1 2016 年 12 月 22 日 2020 年 8 月 30 日
1.10.0 2016 年 10 月 3 日 2020 年 8 月 30 日
1.9.0 2016 年 7 月 7 日 2020 年 8 月 30 日
1.8.0 2016 年 6 月 14 日 2020 年 8 月 30 日
1.7.0 2016 年 4 月 26 日 2020 年 8 月 30 日
1.6.0 2016 年 3 月 29 日 2020 年 8 月 30 日
1.5.6 2016 年 3 月 8 日 2020 年 8 月 30 日
1.5.5 2016 年 2 月 2 日 2020 年 8 月 30 日
1.5.4 2016 年 2 月 1 日 2020 年 8 月 30 日
1.5.2 2016 年 1 月 26 日 2020 年 8 月 30 日
1.5.2 2016 年 1 月 22 日 2020 年 8 月 30 日
1.5.1 2016 年 1 月 4 日 2020 年 8 月 30 日
1.5.0 2015 年 12 月 31 日 2020 年 8 月 30 日
1.4.0 2015 年 10 月 6 日 2020 年 8 月 30 日
1.3.0 2015 年 10 月 6 日 2020 年 8 月 30 日
1.2.2 2015 年 9 月 10 日 2020 年 8 月 30 日
1.2.1 2015 年 8 月 15 日 2020 年 8 月 30 日
1.2.0 2015 年 8 月 5 日 2020 年 8 月 30 日
1.1.0 2015 年 7 月 9 日 2020 年 8 月 30 日
1.0.3 2015 年 6 月 4 日 2020 年 8 月 30 日
1.0.2 2015 年 5 月 23 日 2020 年 8 月 30 日
1.0.1 2015 年 5 月 15 日 2020 年 8 月 30 日
1.0.0 2015 年 4 月 8 日 2020 年 8 月 30 日

常見問題

如何收到即將停用 SDK 的通知?

Microsoft 將在即將終止支援 SDK 之前提供 12 個月的事先通知,以協助順利轉換至支援的 SDK。 我們會透過各種通訊通道通知您:Azure 入口網站、Azure 更新,以及直接通訊給指派的服務系統管理員。

在 12 個月內,我可以使用即將停用的 Azure Cosmos DB SDK 來撰寫應用程式嗎?

是的,您可以在 12 個月的通知期間使用即將停用的 Azure Cosmos DB SDK 來撰寫、部署及修改應用程式。 建議您在 12 個月的通知期間 ,在 12 個月的通知期間,Cosmos更新支援版本的 Azure 和 DB SDK。

在停用日期之後,使用不受支援 Azure 和 DB SDK Cosmos會發生什麼情況?

停用日期之後,Azure Cosmos DB 將不再進行錯誤修正、新增新功能,或為已停用的 SDK 版本提供支援。 如果您不想升級,Azure 和 DB 服務會繼續提供從已停用版本的 SDK Cosmos要求。

哪些 SDK 版本會提供最新的功能和更新?

新功能和更新只會新增到最新支援的主要 SDK 版本的最新次要版本。 我們建議您一直使用最新版本,以利用新功能、改良功能和錯誤修正。 如果您使用的是舊的、非停用版本的 SDK,您向 Azure Cosmos DB 提出的要求仍可運作,但您無法存取任何新功能。

如果截止日期之前無法更新應用程式,該怎麼辦?

建議您儘早升級至最新的 SDK。 將 SDK 標記為停用後,您將有 12 個月來更新您的應用程式。 如果您無法于淘汰日期之前更新,Azure Cosmos DB 會繼續提供從已停用版本的 SDK 所送出的要求,因此您執行的應用程式會繼續運作。 但 Azure Cosmos DB 將不再進行錯誤修正、新增新功能,或為已停用的 SDK 版本提供支援。

如果您有支援計畫且需要技術支援, 請提交 支援票證來聯絡我們。

另請參閱

若要深入瞭解資料庫Cosmos,請參閱Microsoft Azure Cosmos服務頁面。