適用於 JavaScript 的 Azure Cosmos DB 用戶端連結庫 - 4.2.0 版

發行項
11/20/2024

/TypeScript

Azure Cosmos DB 是全域散發的多模型資料庫服務，可支援檔、索引鍵/值、寬數據行和圖形資料庫。此套件適用於 JavaScript/TypeScript 應用程式，以便與 SQL API 資料庫與其包含的 JSON 文件互動：

建立 Cosmos DB 資料庫並修改其設定
建立和修改容器以儲存 JSON 檔的集合
在容器中建立、讀取、更新和刪除專案（JSON 檔案）
使用類似 SQL 的語法查詢資料庫中的檔

主要連結：

開始

先決條件

Azure 訂用帳戶和 Cosmos DB SQL API 帳戶

您必須擁有 Azure 訂用帳戶，以及 Cosmos DB 帳戶（SQL API）才能使用此套件。

如果您需要 Cosmos DB SQL API 帳戶，您可以使用 Azure Cloud Shell 使用此 Azure CLI 命令建立帳戶：

az cosmosdb create --resource-group <resource-group-name> --name <cosmos-database-account-name>

或者，您可以在 Azure 入口網站中建立帳戶

NodeJS

此套件會透過 npm 散發，其預安裝於使用 LTS 版本的 NodeJS。

CORS

如果您需要針對瀏覽器進行開發，您必須為 Cosmos DB 帳戶設定跨原始資源分享（CORS）規則。請遵循連結檔中的指示，為您的 Cosmos DB 建立新的 CORS 規則。

安裝此套件

npm install @azure/cosmos

取得帳戶認證

您將需要 Cosmos DB 帳戶端點 和金鑰。您可以在 Azure 入口網站中找到這些專案，或使用下列 Azure CLI 代碼段。代碼段會格式化為Bash殼層。

az cosmosdb show --resource-group <your-resource-group> --name <your-account-name> --query documentEndpoint --output tsv
az cosmosdb keys list --resource-group <your-resource-group> --name <your-account-name> --query primaryMasterKey --output tsv

建立 `CosmosClient` 的實例

與 Cosmos DB 的互動會從 CosmosClient 類別的實例開始

const { CosmosClient } = require("@azure/cosmos");

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

async function main() {
  // The rest of the README samples are designed to be pasted into this function body
}

main().catch((error) => {
  console.error(error);
});

為了簡單起見，我們已將 key 和 endpoint 直接包含在程序代碼中，但您可能會想要從不在原始檔控制中的檔案載入這些專案，例如 dotenv 或從環境變數載入

在生產環境中，密鑰之類的秘密應該儲存在 Azure Key Vault

重要概念

初始化 CosmosClient之後，您就可以與 Cosmos DB 中的主要資源類型互動：

資料庫：Cosmos DB 帳戶可以包含多個資料庫。當您建立資料庫時，您可以指定與文件互動時想要使用的 API：SQL、MongoDB、Gremlin、Cassandra 或 Azure 數據表。使用 Database 物件來管理其容器。
容器：容器是 JSON 檔的集合。您可以使用 Container 物件上的方法，在容器中建立（插入）、讀取、更新和刪除專案。
Item：專案是儲存在容器中的 JSON 檔。每個項目都必須包含具有可唯一識別容器內專案之值的 id 索引鍵。如果您沒有提供 id，SDK 將會自動產生一個。

如需這些資源的詳細資訊，請參閱使用 Azure Cosmos 資料庫、容器和專案。

例子

下列各節提供數個代碼段，涵蓋一些最常見的Cosmos DB工作，包括：

建立資料庫
建立容器
使用分割區索引鍵
插入專案
查詢檔
讀取專案
刪除專案
使用階層式分割區索引鍵在容器上 CRUD

建立資料庫

驗證 CosmosClient之後，您可以使用帳戶中的任何資源。下列代碼段會建立NOSQL API 資料庫。

const { database } = await client.databases.createIfNotExists({ id: "Test Database" });
console.log(database.id);

建立容器

此範例會建立具有預設設定的容器

const { container } = await database.containers.createIfNotExists({ id: "Test Database" });
console.log(container.id);

使用分割區索引鍵

此範例顯示支援的各種分割區索引鍵類型。

await container.item("id", "1").read();        // string type
await container.item("id", 2).read();          // number type
await container.item("id", true).read();       // boolean type
await container.item("id", {}).read();         // None type
await container.item("id", undefined).read();  // None type
await container.item("id", null).read();       // null type

如果數據分割索引鍵是由單一值所組成，它可以提供為常值或陣列。

await container.item("id", "1").read();
await container.item("id", ["1"]).read();

如果分割區索引鍵是由多個值所組成，則應該以數位的形式提供。

await container.item("id", ["a", "b"]).read();
await container.item("id", ["a", 2]).read();
await container.item("id", [{}, {}]).read();
await container.item("id", ["a", {}]).read();
await container.item("id", [2, null]).read();

插入專案

若要將專案插入容器中，請將包含資料的物件傳遞至items.upsert 。 Azure Cosmos DB 服務要求每個專案都有 id 密鑰。如果您沒有提供，SDK 將會自動產生 id。

此範例會將數個專案插入容器中

const cities = [
  { id: "1", name: "Olympia", state: "WA", isCapitol: true },
  { id: "2", name: "Redmond", state: "WA", isCapitol: false },
  { id: "3", name: "Chicago", state: "IL", isCapitol: false }
];
for (const city of cities) {
  await container.items.create(city);
}

讀取專案

若要從容器讀取單一專案，請使用 Item.read。這是比使用 SQL 查詢 id成本較低的作業。

await container.item("1", "1").read();

容器上具有階層式分割區索引鍵的 CRUD

使用階層式分割區索引鍵建立容器

const containerDefinition = {
  id: "Test Database",
  partitionKey: {
    paths: ["/name", "/address/zip"],
    version: PartitionKeyDefinitionVersion.V2,
    kind: PartitionKeyKind.MultiHash,
  },
}
const { container } = await database.containers.createIfNotExists(containerDefinition);
console.log(container.id);

使用定義為的階層式分割區索引鍵插入專案 - ["/name", "/address/zip"]

const item = {
  id: "1",
  name: 'foo',
  address: {
    zip: 100
  },
  active: true
}
await container.items.create(item);

若要從定義為階層式分割索引鍵的容器讀取單一專案 - ["/name", "/address/zip"],

await container.item("1", ["foo", 100]).read();

使用定義為階層式數據分割索引鍵的專案查詢專案 - ["/name", "/address/zip"],

const { resources } = await container.items
  .query("SELECT * from c WHERE c.active = true", {
          partitionKey: ["foo", 100],
        })
  .fetchAll();
for (const item of resources) {
  console.log(`${item.name}, ${item.address.zip} `);
}

刪除專案

若要從容器中刪除專案，請使用 Item.delete。

// Delete the first item returned by the query above
await container.item("1").delete();

查詢資料庫

Cosmos DB SQL API 資料庫支援使用類似 SQL 語法來查詢容器中的專案，Items.query：

const { resources } = await container.items
  .query("SELECT * from c WHERE c.isCapitol = true")
  .fetchAll();
for (const city of resources) {
  console.log(`${city.name}, ${city.state} is a capitol `);
}

將包含參數及其值的對象傳遞至 Items.query ，以執行參數化查詢：

const { resources } = await container.items
  .query({
    query: "SELECT * from c WHERE c.isCapitol = @isCapitol",
    parameters: [{ name: "@isCapitol", value: true }]
  })
  .fetchAll();
for (const city of resources) {
  console.log(`${city.name}, ${city.state} is a capitol `);
}

如需使用 SQL API 查詢 Cosmos DB 資料庫的詳細資訊，請參閱使用 SQL 查詢 Azure Cosmos DB 資料。

變更摘要提取模型

您可以擷取分割區索引鍵、摘要範圍或整個容器的變更摘要。

若要處理變更摘要，請建立 ChangeFeedPullModelIterator實例。當您一開始建立 ChangeFeedPullModelIterator時，您必須在 ChangeFeedIteratorOptions 內指定必要的 changeFeedStartFrom 值，其中包含讀取變更的起始位置，以及要擷取變更的資源（分割區索引鍵或 FeedRange）。您可以選擇在 ChangeFeedIteratorOptions 中使用 maxItemCount，以設定每個頁面收到的項目數目上限。

注意：如果未指定任何 changeFeedStartFrom 值，則會從 Now（）擷取整個容器的 changefeed。

變更摘要有四個起始位置：

Beginning

// Signals the iterator to read changefeed from the beginning of time.
const options = {
  changeFeedStartFrom: ChangeFeedStartFrom.Beginning(),
};
const iterator = container.getChangeFeedIterator(options);

Time

// Signals the iterator to read changefeed from a particular point of time.
const time = new Date("2023/09/11"); // some sample date
const options = {
  changeFeedStartFrom: ChangeFeedStartFrom.Time(time),
};

Now

// Signals the iterator to read changefeed from this moment onward.
const options = {
  changeFeedStartFrom: ChangeFeedStartFrom.Now(),
};

Continuation

// Signals the iterator to read changefeed from a saved point.
const continuationToken = "some continuation token recieved from previous request";
const options = {
  changeFeedStartFrom: ChangeFeedStartFrom.Continuation(continuationToken),
};

以下是擷取分割區索引鍵變更摘要的範例

const partitionKey = "some-partition-Key-value";
const options = {
  changeFeedStartFrom: ChangeFeedStartFrom.Beginning(partitionKey),
};

const iterator = container.items.getChangeFeedIterator(options);

while (iterator.hasMoreResults) {
  const response = await iterator.readNext();
  // process this response
}

因為變更摘要實際上是包含所有未來寫入和更新的無限專案清單，因此 hasMoreResults 的值一律 true。當您嘗試讀取變更摘要且沒有可用的新變更時，您會收到具有 NotModified 狀態的回應。

如需更詳細的使用方針和變更摘要範例，請參閱這裡。

錯誤處理

SDK 會產生作業期間可能發生的各種錯誤類型。

如果作業的回應傳回錯誤碼為 =400，則會擲回 >ErrorResponse。
如果因逾時而於內部呼叫 Abort，則會擲回 TimeoutError。
如果任何使用者通過的訊號造成中止，就會擲回 AbortError。
RestError 因為網路問題而造成基礎系統呼叫失敗時擲回。
任何 devDependencies 所產生的錯誤。例如 @azure/identity 套件可能會擲回 CredentialUnavailableError。

以下是處理類型 ErrorResponse、TimeoutError、AbortError和 RestError的錯誤範例。

try {
  // some code
} catch (err) {
  if (err instanceof ErrorResponse) {
    // some specific error handling.
  } else if (err instanceof RestError) {
    // some specific error handling.
  }
  // handle other type of errors in similar way.
  else {
    // for any other error.
  }
}

請務必正確處理這些錯誤，以確保您的應用程式可以正常復原任何失敗，並繼續如預期般運作。如需這些錯誤及其可能解決方案的詳細資訊，請參閱這裡。

故障排除

常規

當您與服務傳回的 Cosmos DB 錯誤互動時，會對應至針對 REST API 要求傳回的相同 HTTP 狀態代碼：

Azure Cosmos DB 的 HTTP 狀態代碼

衝突

例如，如果您嘗試使用已在Cosmos DB資料庫中使用的 id 建立專案，則會傳回 409 錯誤，指出衝突。在下列代碼段中，會藉由攔截例外狀況並顯示錯誤的其他資訊，以正常方式處理錯誤。

try {
  await containers.items.create({ id: "existing-item-id" });
} catch (error) {
  if (error.code === 409) {
    console.log("There was a conflict with an existing item");
  }
}

轉譯

Azure SDK 的設計訴求是支援 ES5 JavaScript 語法和 LTS 版本的 Node.js。如果您需要舊版 JavaScript 運行時間的支援，例如 Internet Explorer 或 Node 6，您必須在建置程式中轉譯 SDK 程式代碼。

使用重試處理暫時性錯誤

使用 Cosmos DB 時，您可能會遇到暫時性失敗，原因是服務強制執行速率限制，或其他暫時性問題，例如網路中斷。如需處理這些失敗類型的資訊，請參閱雲端設計模式指南中的重試模式，以及相關的斷路器模式。

伐木

啟用記錄可能有助於找出有關失敗的實用資訊。若要查看 HTTP 要求和回應的記錄，請將 AZURE_LOG_LEVEL 環境變數設定為 info。或者，可以在運行時間啟用記錄，方法是在 @azure/logger中呼叫 setLogLevel。使用 AZURE_LOG_LEVEL 請務必在初始化記錄連結庫之前加以設定。在理想情況下，如果使用類似 dotenv 的連結庫，請確定這類連結庫在記錄連結庫之前已初始化。

const { setLogLevel } = require("@azure/logger");
setLogLevel("info");

如需如何啟用記錄的詳細指示，請參閱@azure/記錄器套件檔。

診斷

Cosmos 診斷功能提供您所有用戶端作業的增強見解。 CosmosDiagnostics 物件會新增至回應所有客戶端作業。如

點查閱作業回應 - item.read()、container.create()、database.delete()
查詢作業回應 -queryIterator.fetchAll()、
大量與批次作業 -item.batch()。
錯誤/例外狀況回應物件。

CosmosDiagnostics 物件會新增至回應所有客戶端作業。有 3 個 Cosmos 診斷層級、資訊、偵錯和偵錯-unsafe。其中只有資訊適用於生產系統，而偵錯和偵錯不安全則表示要在開發和偵錯期間使用，因為它們會耗用大量較高的資源。 Cosmos 診斷層級可透過 2 種方式設定

以程序設計方式

  const client = new CosmosClient({ endpoint, key, diagnosticLevel: CosmosDbDiagnosticLevel.debug });

使用環境變數。（環境變數所設定的診斷層級優先於透過客戶端選項進行設定。

  export AZURE_COSMOSDB_DIAGNOSTICS_LEVEL="debug"

Cosmos 診斷有三個成員

ClientSideRequestStatistics 類型：包含匯總診斷詳細數據，包括元數據查閱、重試、已連絡的端點，以及承載大小和持續時間等要求和回應統計數據。（一律收集，可用於生產系統。
DiagnosticNode：這是一種類似樹狀的結構，可擷取詳細的診斷資訊。類似於 har 瀏覽器中的錄製。此功能預設為停用，且僅供偵錯非生產環境。（收集在診斷層級偵錯和偵錯不安全）
ClientConfig：擷取用戶端初始化期間與用戶端組態設定相關的基本資訊。（收集在診斷層級偵錯和偵錯不安全）

請務必永遠不要在生產環境中將診斷層級設定為 debug-unsafe，因為此層級 CosmosDiagnostics 擷取要求和響應承載，而且如果您選擇記錄它（預設會記錄 @azure/loggerverbose 層級）。這些承載可能會在記錄接收中擷取。

使用診斷

因為 diagnostics 會新增至所有 Response 物件。您可以依程序設計方式存取 CosmosDiagnostic，如下所示。

  // For point look up operations
  const { container, diagnostics: containerCreateDiagnostic } =
    await database.containers.createIfNotExists({
      id: containerId,
      partitionKey: {
        paths: ["/key1"],
      },
  });

  // For Batch operations
   const operations: OperationInput[] = [
    {
      operationType: BulkOperationType.Create,
      resourceBody: { id: 'A', key: "A", school: "high" },
    },
  ];
  const response = await container.items.batch(operations, "A"); 
  
  // For query operations
  const queryIterator = container.items.query("select * from c");
  const { resources, diagnostics } = await queryIterator.fetchAll();

  // While error handling
  try {
    // Some operation that might fail
  } catch (err) {
    const diagnostics = err.diagnostics
  }

您也可以使用 @azure/logger記錄 diagnostics，診斷一律會使用 verbose 層級 @azure/logger 記錄。因此，如果您將診斷層級設定為 debug 或 debug-unsafe，並將 @azure/logger 層級設定為 verbose，則會記錄 diagnostics。

後續步驟

局限性

目前不支援下列功能。如需替代選項，請查看下方的 因應措施 一節。

資料平面限制：

來自 DISTINCT 子查詢的 COUNT 查詢
直接 TCP 模式存取
匯總跨分割區查詢，例如排序、計數和相異，不支援接續令牌。可串流查詢，例如SELECT * FROM WHERE ，支援接續令牌。請參閱一節，以了解在沒有接續令牌的情況下執行不可串流查詢。
變更摘要：處理器
變更摘要：讀取多個分割區索引鍵值
部分階層式分割區索引鍵的變更摘要提取模型支援 #27059
混合類型的跨分割區 ORDER BY

控制平面限制：

取得 CollectionSizeUsage、DatabaseUsage 和 DocumentUsage 計量
建立地理空間索引
更新自動調整輸送量

因應措施

跨分割區查詢的接續令牌

您可以使用側車模式，透過接續令牌支援來達成跨分割區查詢。此模式也可以讓應用程式由異質元件和技術組成。

執行不可結構化的跨分割區查詢

若要在不使用接續令牌的情況下執行不可串流查詢，您可以使用必要的查詢規格和選項來建立查詢反覆運算器。下列範例程式代碼示範如何使用查詢反覆運算器來擷取所有結果，而不需要接續令牌：

const querySpec = {
  query: "SELECT c.status, COUNT(c.id) AS count FROM c GROUP BY c.status",
};
const queryOptions = {
  maxItemCount: 10, // maximum number of items to return per page
  enableCrossPartitionQuery: true,
};
const querIterator = await container.items.query(querySpec, queryOptions);
while (querIterator.hasMoreResults()) {
  const { resources: result } = await querIterator.fetchNext();
  //Do something with result
}

此方法也可用於可串流查詢。

控制平面作業

一般而言，您可以使用 Azure 入口網站、Azure Cosmos DB 資源提供者 REST API、Azure CLI 或 PowerShell，以取得控制平面不支援的限制。

其他檔

如需 Cosmos DB 服務的詳細資訊檔，請參閱 Azure Cosmos DB 檔 docs.microsoft.com。

有用的連結

貢獻

如果您想要參與此連結庫，請閱讀參與指南，以深入瞭解如何建置和測試程序代碼。

共用方式為