使用 Azure CLI 連線現有 Azure Cosmos 帳戶與虛擬網路服務端點Connect an existing Azure Cosmos account with virtual network service endpoints using Azure CLI

適用於:適用於 MongoDB 的 SQL API Cassandra API Gremlin API Table API Azure Cosmos DB API

必要條件Prerequisites

  • Azure Cloud Shell中使用 Bash 環境。Use the Bash environment in Azure Cloud Shell.

    在新視窗中啟動 Cloud ShellLaunch Cloud Shell in a new window

  • 如果想要,請安裝 Azure CLI 以執行 CLI 參考命令。If you prefer, install the Azure CLI to run CLI reference commands.

    • 如果您使用的是本機安裝,請使用 az login 命令,透過 Azure CLI 來登入。If you're using a local installation, sign in to the Azure CLI by using the az login command. 請遵循您終端機上顯示的步驟,完成驗證程序。To finish the authentication process, follow the steps displayed in your terminal. 如需其他登入選項,請參閱使用 Azure CLI 登入For additional sign-in options, see Sign in with the Azure CLI.

    • 出現提示時,請在第一次使用時安裝 Azure CLI 擴充功能。When you're prompted, install Azure CLI extensions on first use. 如需擴充功能詳細資訊,請參閱使用 Azure CLI 擴充功能For more information about extensions, see Use extensions with the Azure CLI.

    • 執行 az version 以尋找已安裝的版本和相依程式庫。Run az version to find the version and dependent libraries that are installed. 若要升級至最新版本,請執行 az upgradeTo upgrade to the latest version, run az upgrade.

  • 本文需要 2.9.1 版或更新版本的 Azure CLI。This article requires version 2.9.1 or later of the Azure CLI. 如果您是使用 Azure Cloud Shell,就已安裝最新版本。If using Azure Cloud Shell, the latest version is already installed.

範例指令碼Sample script

此範例旨在示範如何使用 ignore-missing-vnet-service-endpoint 參數,將現有的 Azure Cosmos 帳戶連線到現有新的虛擬網路,其中尚未針對服務端點設定子網路。This sample is intended to show how to connect an existing Azure Cosmos account to an existing new virtual network where the subnet is not yet configured for service endpoints by using the ignore-missing-vnet-service-endpoint parameter. 這可在完成虛擬網路的子網路設定之前,讓 Cosmos 帳戶的設定完成,而不會發生錯誤。This allows the configuration for the Cosmos account to complete without error before the configuration to the virtual network's subnet is completed. 子網路設定完成後,便可透過已設定的子網路存取 Cosmos 帳戶。Once the subnet configuration is complete, the Cosmos account will then be accessible through the configured subnet.

注意

此範例會示範如何使用 SQL (核心) API 帳戶。This sample demonstrates using a SQL (Core) API account. 若要將此範例使用於其他 API,請將下面指令碼中的 enable-virtual-networkvirtual-network-rules 參數套用至您的 API 專屬指令碼。To use this sample for other APIs, apply the enable-virtual-network and virtual-network-rules parameters in the script below to your API specific script.

#!/bin/bash
# Reference: az cosmosdb | https://docs.microsoft.com/cli/azure/cosmosdb
# --------------------------------------------------
#
# Service endpoint operations for an Azure Cosmos account
#
# Create an Azure Cosmos Account with a service endpoint connected to a backend subnet
# that is not yet enabled for service endpoints.

# This sample demonstrates how to configure service endpoints for existing Cosmos account where
# the connected subnet is not yet configured for service endpoints.
# This sample will then configure the subnet for service endpoints.

# Resource group and Cosmos account variables
uniqueId=$RANDOM
resourceGroupName="Group-$uniqueId"
location='westus2'
accountName="cosmos-$uniqueId" #needs to be lower case

# Variables for a new Virtual Network with two subnets
vnetName='myVnet'
frontEnd='FrontEnd'
backEnd='BackEnd'

# Create a resource group
az group create -n $resourceGroupName -l $location

# Create a virtual network with a front-end subnet
az network vnet create \
    -n $vnetName \
    -g $resourceGroupName \
    --address-prefix 10.0.0.0/16 \
    --subnet-name $frontEnd \
    --subnet-prefix 10.0.1.0/24

# Create a back-end subnet but without specifying --service-endpoints Microsoft.AzureCosmosDB
az network vnet subnet create \
    -n $backEnd \
    -g $resourceGroupName \
    --address-prefix 10.0.2.0/24 \
    --vnet-name $vnetName

svcEndpoint=$(az network vnet subnet show -g $resourceGroupName -n $backEnd --vnet-name $vnetName --query 'id' -o tsv)

# Create a Cosmos DB account with default values
# Use appropriate values for --kind or --capabilities for other APIs
az cosmosdb create -n $accountName -g $resourceGroupName

# Add the virtual network rule but ignore the missing service endpoint on the subnet
az cosmosdb network-rule add \
    -n $accountName \
    -g $resourceGroupName \
    --virtual-network $vnetName \
    --subnet svcEndpoint \
    --ignore-missing-vnet-service-endpoint true

read -p'Press any key to configure the subnet for service endpoints'

az network vnet subnet update \
    -n $backEnd \
    -g $resourceGroupName \
    --vnet-name $vnetName \
    --service-endpoints Microsoft.AzureCosmosDB

清除部署Clean up deployment

在執行過指令碼範例之後,您可以使用下列命令來移除資源群組和所有與其相關聯的資源。After the script sample has been run, the following command can be used to remove the resource group and all resources associated with it.

az group delete --name $resourceGroupName

指令碼說明Script explanation

此指令碼會使用下列命令。This script uses the following commands. 下表中的每個命令都會連結至命令特定的文件。Each command in the table links to command specific documentation.

CommandCommand 注意Notes
az group createaz group create 建立用來存放所有資源的資源群組。Creates a resource group in which all resources are stored.
az network vnet createaz network vnet create 建立 Azure 虛擬網路。Creates an Azure virtual network.
az network vnet subnet createaz network vnet subnet create 建立 Azure 虛擬網路的子網路。Creates a subnet for an Azure virtual network.
az network vnet subnet showaz network vnet subnet show 傳回 Azure 虛擬網路的子網路。Returns a subnet for an Azure virtual network.
az cosmosdb createaz cosmosdb create 建立 Azure Cosmos DB 帳戶。Creates an Azure Cosmos DB account.
az network vnet subnet updateaz network vnet subnet update 更新 Azure 虛擬網路的子網路。Updates a subnet for an Azure virtual network.
az group deleteaz group delete 刪除資源群組,包括所有的巢狀資源。Deletes a resource group including all nested resources.

後續步驟Next steps

如需 Azure Cosmos DB CLI 的詳細資訊,請參閱 Azure Cosmos DB CLI 文件For more information on the Azure Cosmos DB CLI, see Azure Cosmos DB CLI documentation.

您可以在 Azure Cosmos DB CLI GitHub 存放庫中找到所有 Azure Cosmos DB CLI 指令碼範例。All Azure Cosmos DB CLI script samples can be found in the Azure Cosmos DB CLI GitHub Repository.