开始通过 JavaScript 使用 Azure Cosmos DB for NoSQL |
您所在的位置：网站首页 › 链接如何生成 › 开始通过 JavaScript 使用 Azure Cosmos DB for NoSQL |
|
你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。 开始通过 JavaScript 使用 Azure Cosmos DB for NoSQL 项目 06/02/2023适用范围： NoSQL 本文介绍如何使用 JavaScript SDK 连接到 Azure Cosmos DB for NoSQL。 连接后，可对数据库、容器和项执行操作。 包 (npm) | 示例 | API 参考 | 库源代码 | 反馈 先决条件 具有活动订阅的 Azure 帐户。 免费创建帐户。 Azure Cosmos DB for NoSQL 帐户。 创建 API for NoSQL 帐户。 Node.js LTS Azure 命令行接口 (CLI) 或 Azure PowerShell 设置本地项目在 bash shell 中为 JavaScript 项目创建新目录。 mkdir cosmos-db-nosql-javascript-samples && cd ./cosmos-db-nosql-javascript-samples通过将 npm init 命令与控制台模板一起使用，创建一个新的 JavaScript 应用程序。 npm init -y安装 Azure Cosmos DB for NoSQL JavaScript SDK 所需的依赖项。 npm install @azure/cosmos 连接到 Azure Cosmos DB for NoSQL若要连接到 Azure Cosmos DB 的 API for NoSQL，请创建 CosmosClient 类的实例。 此类是针对数据库执行所有操作的起点。 可以通过三种核心方式使用 CosmosClient 类连接到 API for NoSQL 帐户： 使用 API for NoSQL 终结点和读/写密钥进行连接 使用 API for NoSQL 连接字符串进行连接 使用 Azure Active Directory 连接 使用终结点和密钥连接CosmosClient 的最常见构造函数有两个参数： 参数 示例值 说明 accountEndpoint COSMOS_ENDPOINT 环境变量 用于所有请求的 API for NoSQL 终结点 authKeyOrResourceToken COSMOS_KEY 环境变量 身份验证时要使用的帐户密钥或资源令牌 检索帐户终结点和密钥 Azure CLI PowerShell Portal为 resourceGroupName 创建 shell 变量。 # Variable for resource group name resourceGroupName="msdocs-cosmos-javascript-howto-rg"使用 az cosmosdb list 命令检索资源组中第一个 Azure Cosmos DB 帐户的名称，并将其存储在 accountName shell 变量中。 # Retrieve most recently created account name accountName=$( az cosmosdb list \ --resource-group $resourceGroupName \ --query "[0].name" \ --output tsv )使用 az cosmosdb show 命令获取帐户的 API for NoSQL 终结点 URI。 az cosmosdb show \ --resource-group $resourceGroupName \ --name $accountName \ --query "documentEndpoint"使用 az-cosmosdb-keys-list 命令从帐户的密钥列表中查找主密钥。 az cosmosdb keys list \ --resource-group $resourceGroupName \ --name $accountName \ --type "keys" \ --query "primaryMasterKey"记录 URI 和主密钥值。 稍后将使用这些凭据。 为 RESOURCE_GROUP_NAME 创建 shell 变量。 # Variable for resource group name $RESOURCE_GROUP_NAME = "msdocs-cosmos-javascript-howto-rg"使用 Get-AzCosmosDBAccount cmdlet 检索资源组中第一个 Azure Cosmos DB 帐户的名称，并将其存储在 ACCOUNT_NAME shell 变量中。 # Retrieve most recently created account name $parameters = @{ ResourceGroupName = $RESOURCE_GROUP_NAME } $ACCOUNT_NAME = ( Get-AzCosmosDBAccount @parameters | Select-Object -Property Name -First 1 ).Name使用 Get-AzCosmosDBAccount cmdlet 获取帐户的 API for NoSQL 终结点 URI。 $parameters = @{ ResourceGroupName = $RESOURCE_GROUP_NAME Name = $ACCOUNT_NAME } Get-AzCosmosDBAccount @parameters | Select-Object -Property "DocumentEndpoint"使用 Get-AzCosmosDBAccountKey cmdlet 从帐户的密钥列表中查找主密钥。 $parameters = @{ ResourceGroupName = $RESOURCE_GROUP_NAME Name = $ACCOUNT_NAME Type = "Keys" } Get-AzCosmosDBAccountKey @parameters | Select-Object -Property "PrimaryMasterKey"记录 URI 和主密钥值。 稍后将使用这些凭据。 提示 对于本指南，建议使用资源组名称 msdocs-cosmos-javascript-howto-rg。 登录 Azure 门户。 导航到现有的 Azure Cosmos DB for NoSQL 帐户页。 从 Azure Cosmos DB for NoSQL 帐户页中，选择“密钥”导航菜单选项。
记录“URI”和“主密钥”字段中的值。 在后续步骤中将要用到这些值。
若要在代码中使用“URI”和“主密钥”值，请将其保存到运行应用程序的本地计算机上的新环境变量。 Windows Linux/macOS $env:COSMOS_ENDPOINT = "" $env:COSMOS_KEY = "" export COSMOS_ENDPOINT="" export COSMOS_KEY="" 使用帐户终结点和密钥创建 CosmosClient使用 COSMOS_ENDPOINT 和 COSMOS_KEY 环境变量作为参数，创建 CosmosClient 类的新实例。 const client = new CosmosClient({ endpoint, key }); 使用连接字符串连接CosmosClient 的另一个构造函数仅包含一个参数： 参数 示例值 说明 accountEndpoint COSMOS_ENDPOINT 环境变量 用于所有请求的 API for NoSQL 终结点 connectionString COSMOS_CONNECTION_STRING 环境变量 API for NoSQL 帐户的连接字符串 检索帐户连接字符串 Azure CLI PowerShell Portal使用 az cosmosdb list 命令检索资源组中第一个 Azure Cosmos DB 帐户的名称，并将其存储在 accountName shell 变量中。 # Retrieve most recently created account name accountName=$( az cosmosdb list \ --resource-group $resourceGroupName \ --query "[0].name" \ --output tsv )使用 az-cosmosdb-keys-list 命令，从帐户的连接字符串列表中查找主连接字符串。 az cosmosdb keys list \ --resource-group $resourceGroupName \ --name $accountName \ --type "connection-strings" \ --query "connectionStrings[?description == \`Primary SQL Connection String\`] | [0].connectionString"使用 Get-AzCosmosDBAccount cmdlet 检索资源组中第一个 Azure Cosmos DB 帐户的名称，并将其存储在 ACCOUNT_NAME shell 变量中。 # Retrieve most recently created account name $parameters = @{ ResourceGroupName = $RESOURCE_GROUP_NAME } $ACCOUNT_NAME = ( Get-AzCosmosDBAccount @parameters | Select-Object -Property Name -First 1 ).Name使用 Get-AzCosmosDBAccountKey cmdlet，从帐户的连接字符串列表中查找主连接字符串。 $parameters = @{ ResourceGroupName = $RESOURCE_GROUP_NAME Name = $ACCOUNT_NAME Type = "ConnectionStrings" } Get-AzCosmosDBAccountKey @parameters | Select-Object -Property "Primary SQL Connection String" -First 1提示 对于本指南，建议使用资源组名称 msdocs-cosmos-javascript-howto-rg。 登录 Azure 门户。 导航到现有的 Azure Cosmos DB for NoSQL 帐户页。 从 Azure Cosmos DB for NoSQL 帐户页中，选择“密钥”导航菜单选项。 记录“主连接字符串”字段的值。 若要在代码中使用“主连接字符串”值，请将其保存到运行应用程序的本地计算机上的新环境变量。 Windows Linux/macOS $env:COSMOS_CONNECTION_STRING = "" export COSMOS_CONNECTION_STRING="" 使用连接字符串创建 CosmosClient使用 COSMOS_CONNECTION_STRING 环境变量作为唯一参数，创建 CosmosClient 类的新实例。 // New instance of CosmosClient class using a connection string const cosmosClient = new CosmosClient(process.env.COSMOS_CONNECTION_STRING); 使用 Microsoft 标识平台连接若要使用 Microsoft 标识平台和 Azure AD 连接到 API for NoSQL 帐户，请使用安全主体。 主体的确切类型将取决于应用程序代码的托管位置。 下表可用作快速参考指南。 应用程序的运行位置 安全主体 本地计算机（开发和测试） 用户标识或服务主体 Azure 托管标识 Azure 外部的服务器或客户端 服务主体 导入 @azure/identity@azure/identity npm 包包含所有 Azure SDK 库之间共享的核心身份验证功能。 使用 npm install 命令导入 @azure/identity npm 包。 npm install @azure/identity在代码编辑器中，添加依赖项。 const { DefaultAzureCredential } = require("@azure/identity"); 使用默认凭据实现创建 CosmosClient如果在本地计算机上进行测试，或者应用程序将在 Azure 服务上运行，并直接支持托管标识，则通过创建 DefaultAzureCredential 实例来获取 OAuth 令牌。 使用 COSMOS_ENDPOINT 环境变量和 TokenCredential 对象作为参数，创建 CosmosClient 类的新实例。 const { CosmosClient } = require("@azure/cosmos"); const { DefaultAzureCredential } = require("@azure/identity"); const credential = new DefaultAzureCredential(); const cosmosClient = new CosmosClient({ endpoint, aadCredentials: credential }); 使用自定义凭据实现创建 CosmosClient如果计划在 Azure 之外部署应用程序，则可以通过使用适用于 JavaScript 的 @azure/identity 客户端库中的其他类来获取 OAuth 令牌。 这些其他类也派生自 TokenCredential 类。 在此示例中，我们使用客户端和租户标识符以及客户端密码来创建 ClientSecretCredential 实例。 在 Azure Active Directory (AD) 中注册应用程序时，可以获取客户端 ID、租户 ID 和客户端密码。 有关如何注册 Azure AD 应用程序的详细信息，请参阅将应用程序注册到 Microsoft 标识平台。 使用 COSMOS_ENDPOINT 环境变量和 TokenCredential 对象作为参数，创建 CosmosClient 类的新实例。 const { CosmosClient } = require("@azure/cosmos"); const { DefaultAzureCredential } = require("@azure/identity"); const credential = new ClientSecretCredential( tenantId: process.env.AAD_TENANT_ID, clientId: process.env.AAD_CLIENT_ID, clientSecret: process.env.AAD_CLIENT_SECRET ); const cosmosClient = new CosmosClient({ endpoint, aadCredentials: credential }); 生成应用程序在生成应用程序时，代码主要与四种类型的资源交互： API for NoSQL 帐户，它是 Azure Cosmos DB 数据的唯一顶级命名空间。 数据库，它用于组织帐户中的容器。 容器，它包含数据库中的一组单个项。 项，它表示容器中的 JSON 文档。 以下图示显示了这些资源之间的关系。
顶部是显示 Azure Cosmos DB 帐户的层次结构示意图。 该帐户包含两个子数据库节点。 其中一个数据库节点包含两个子容器节点。 另一个数据库节点包含单个子容器节点。 该容器节点包含三个子项节点。 每种类型的资源由一个或多个关联的类表示。 下面列出了最常见的类： 类 说明 CosmosClient 此类为 Azure Cosmos DB 服务提供客户端逻辑表示。 此客户端对象用于对服务进行配置和执行请求。 Database 此类是对服务中可能存在或可能不存在的数据库的引用。 在尝试访问该数据库或对其执行操作时，会在服务器端验证该数据库。 Container 此类是对服务中可能不存在的容器的引用。 在尝试使用该容器时，会在服务器端对其进行验证。以下指南介绍了如何使用上述每个类来生成应用程序。 指南 说明 创建数据库 创建数据库 创建容器 创建容器 创建和读取项 点读特定项 查询项 查询多个项 请参阅 npm 包 示例 API 参考 库源代码 提供反馈 后续步骤现在，你已连接到 API for NoSQL 帐户，请使用下一指南创建和管理数据库。 使用 JavaScript 在 Azure Cosmos DB for NoSQL 中创建数据库 |
| CopyRight 2018-2019 办公设备维修网 版权所有 豫ICP备15022753号-3 |