快速入門：適用於 Node.js 的 Azure Cosmos DB for NoSQL 程式庫

• 適用於:

  ✅ NoSQL

• .NET
• Node.js
• Java
• Python
• Go

開始使用適用於 Node.js 的 Azure Cosmos DB for NoSQL 用戶端程式庫來查詢容器中的資料，並對各個項目執行常見作業。 請依照以下步驟，使用 Azure Developer CLI 將基本解決方案部署到您的環境。

API 參考文件 | 程式庫原始程式碼 | 套件 (npm) | Azure Developer CLI

必要條件

• 具有有效訂用帳戶的 Azure 帳戶。 免費建立帳戶。
• GitHub 帳戶

• 具有有效訂用帳戶的 Azure 帳戶。 免費建立帳戶。
• Azure Developer CLI
• Docker Desktop

設定

將這個專案的開發容器部署到您的環境。 然後使用 Azure Developer CLI (azd) 來建立 Azure Cosmos DB for NoSQL 帳戶，並部署容器化應用程式範例。 應用程式範例使用用戶端程式庫管理、建立、讀取和查詢樣本資料。

重要

GitHub 帳戶的免費權利包括儲存體和核心時數。 如需詳細資訊，請參閱 GitHub 帳戶包含的儲存體和核心時數。

1. 在專案的根目錄中開啟終端。

2. 使用 azd auth login 以向 Azure Developer CLI 進行驗證。 依照工具指定的步驟，使用您慣用的 Azure 認證向 CLI 進行驗證。

   azd auth login
   

3. 使用 azd init 來初始化專案。

   azd init --template cosmos-db-nosql-dotnet-quickstart
   

   注意

   本快速入門使 azure-samples/cosmos-db-nosql-dotnet-quickstart (英文) 範本 GitHub 存放庫。 如果尚未複製此專案，Azure Developer CLI 會自動將其複製至您的機器上。

4. 在初始化期間，請設定唯一的環境名稱。

   提示

   環境名稱也將是目標資源群組名稱。 在這個快速入門中，請考慮使用 msdocs-cosmos-db。

5. 使用 azd up 部署 Azure Cosmos DB 帳戶。 Bicep 範本也會部署範例 Web 應用程式。

   azd up
   

6. 在佈建流程期間，請選取您的訂用帳戶和所需位置。 等候佈建程序完成。 此流程「大約需要五分鐘」的時間。

7. Azure 資源佈建完成後，輸出將包含正在執行的 Web 應用程式的 URL。

   Deploying services (azd deploy)
   
     (✓) Done: Deploying service web
   - Endpoint: <https://[container-app-sub-domain].azurecontainerapps.io>
   
   SUCCESS: Your application was provisioned and deployed to Azure in 5 minutes 0 seconds.
   

8. 請使用主控台中的 URL，以在瀏覽器中導覽至您的 Web 應用程式。 觀察執行中應用程式的輸出。

   

安裝用戶端程式庫

用戶端程式庫可透過 Node 套件管理員以 @azure/cosmos 套件形式提供。

1. 開啟終端機，然後導覽至 /src 資料夾。

   cd ./src
   

2. 如果尚未安裝，則請使用 npm install 來安裝 @azure/cosmos 套件。

   npm install --save @azure/cosmos
   

3. 也請安裝 @azure/identity 套件 (如果尚未安裝)。

   npm install --save @azure/identity
   

4. 開啟並檢閱 src/package.json 檔案，以驗證 azure-cosmos 和 azure-identity 項目都存在。

物件模型

名稱	描述
CosmosClient	此類別是主要用戶端類別，並且用來管理全帳戶中繼資料或資料庫。
Database	此類別代表帳戶內的資料庫。
Container	此類別主要用來對容器或容器內所儲存的項目執行讀取、更新和刪除作業。
PartitionKey	此類別代表邏輯分割區索引鍵。 許多常見的作業和查詢都需要此類別。
SqlQuerySpec	此介面代表 SQL 查詢和任何查詢參數。

程式碼範例

• 驗證用戶端
• 取得資料庫
• 取得容器
• 建立項目
• 取得項目
• 查詢項目

範本中的程式碼範例使用 cosmicworks 資料庫和 products 容器。 products 容器包含每個產品的名稱、類別、數量、唯一識別碼和銷售旗標這類詳細資料。 容器使用 /category 屬性作為邏輯分割區索引鍵。

驗證用戶端

大多數 Azure 服務的應用程式要求都需要您授權。 使用 DefaultAzureCredential 型別作為慣用方式，以實作應用程式與 Azure Cosmos DB for NoSQL 之間的無密碼連線。 DefaultAzureCredential 支援多個驗證方法，並在執行階段判斷應該使用哪個方法。

重要

您也可以直接使用密碼、連接字串或其他認證，來授權 Azure 服務要求。 不過，應該謹慎使用此方法。 開發人員應盡力不讓祕密在不安全的位置曝光。 任何取得密碼或祕密金鑰存取權的人員，都可以對資料庫伺服器進行驗證。 DefaultAzureCredential 提供更新版管理和安全性比帳戶金鑰更具優勢，可進行無密碼驗證，完全沒有儲存金鑰需面臨的風險。

此範例會建立 CosmosClient 類型的新執行個體，並使用 DefaultAzureCredential 執行個體來進行驗證。

JavaScript

const credential = new DefaultAzureCredential();

const client = new CosmosClient({
    '<azure-cosmos-db-nosql-account-endpoint>',
    aadCredentials: credential
});

TypeScript

const credential: TokenCredential = new DefaultAzureCredential();

const client = new CosmosClient({
    '<azure-cosmos-db-nosql-account-endpoint>',
    aadCredentials: credential
});

取得資料庫

使用 client.database 來擷取名為 cosmicworks 的現有資料庫。

JavaScript

const database = client.database('cosmicworks');

TypeScript

const database: Database = client.database('cosmicworks');

取得容器

使用 database.container 來擷取現有 products 容器。

JavaScript

const container = database.container('products');

TypeScript

const container: Container = database.container('products');

建立項目

建置新的物件，而此物件具有所有您想要序列化成 JSON 的成員。 在此範例中，此類型具有唯一識別碼，以及類別、名稱、數量、價格和銷售的欄位。 使用 container.items.upsert，以在容器中建立項目。 此方法會有效地 "upserts" 可取代項目 (如果已存在) 的項目。

JavaScript

const item = {
    'id': 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
    'category': 'gear-surf-surfboards',
    'name': 'Yamba Surfboard',
    'quantity': 12,
    'price': 850.00,
    'clearance': false
};

let response = await container.items.upsert(item);

TypeScript

const item: Product = {
    'id': 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
    'category': 'gear-surf-surfboards',
    'name': 'Yamba Surfboard',
    'quantity': 12,
    'price': 850.00,
    'clearance': false
};

let response: ItemResponse<Product> = await container.items.upsert<Product>(item);

讀取項目

使用唯一識別碼 (id) 和分割區索引鍵欄位，來執行點讀取作業。 使用 container.item 來取得項目的指標，以及使用 item.read 來有效率地擷取特定項目。

JavaScript

const id = 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb';
const partitionKey = 'gear-surf-surfboards';

let response = await container.item(id, partitionKey).read();
let read_item = response.resource;

TypeScript

const id = 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb';
const partitionKey = 'gear-surf-surfboards';

let response: ItemResponse<Product> = await container.item(id, partitionKey).read<Product>();
let read_item: Product = response.resource!;

查詢項目

使用 container.items.query，以對容器中的多個項目執行查詢。 使用此參數化查詢，來尋找所指定類別內的所有項目：

SELECT * FROM products p WHERE p.category = @category

使用 query.fetchAll 來擷取查詢的所有結果。 重複查看查詢的結果。

JavaScript

const querySpec = {
    query: 'SELECT * FROM products p WHERE p.category = @category',
    parameters: [
        {
            name: '@category',
            value: 'gear-surf-surfboards'
        }
    ]
};

let response = await container.items.query(querySpec).fetchAll();
for (let item of response.resources) {
    // Do something
}

TypeScript

const querySpec: SqlQuerySpec = {
    query: 'SELECT * FROM products p WHERE p.category = @category',
    parameters: [
        {
            name: '@category',
            value: 'gear-surf-surfboards'
        }
    ]
};

let response: FeedResponse<Product> = await container.items.query<Product>(querySpec).fetchAll();
for (let item of response.resources) {
    // Do something
}

相關內容

• .NET 快速入門
• Java 快速入門
• Python 快速入門
• Go 快速入門