設定從虛擬網路 (VNet) 存取 Azure Cosmos DB

發行項
03/28/2024

適用於：NoSQL MongoDB Cassandra Gremlin Table

您可以設定 Azure Cosmos DB 帳戶，只允許從虛擬網路 (VNET) 的特定子網路存取。在虛擬網路內的子網路上啟用服務端點，以控制對 Azure Cosmos DB 的存取。來自該子網路的流量會使用子網路和虛擬網路的身分識別傳送至 Azure Cosmos DB。 Azure Cosmos DB 服務端點啟用之後，就可以將它新增至您的 Azure Cosmos DB 帳戶，以限制對子網路的存取。

根據預設，如果要求伴隨有效的授權權杖，就可以從任何來源存取 Azure Cosmos DB 帳戶。當您在 VNet 內新增一或多個子網路時，只有來自那些子網路的要求會取得有效回應。來自任何其他來源的要求將會收到 403 (禁止) 回應。

您可以設定 Azure Cosmos DB 帳戶，只允許從 Azure 虛擬網路的特定子網路存取。若要限制只能從虛擬網路中的子網路進行連線來存取 Azure Cosmos DB 帳戶：

讓 Azure Cosmos DB 的服務端點能夠將子網路和虛擬網路身分識別傳送至 Azure Cosmos DB。
在 Azure Cosmos DB 帳戶中新增規則，將子網路指定為可存取帳戶的來源。

注意

在子網路上啟用 Azure Cosmos DB 帳戶的服務端點時，送到 Azure Cosmos DB 的流量來源就會從公用 IP 切換為虛擬網路和子網路。對於任何要從這個子網路存取的 Azure Cosmos DB 帳戶，都會套用流量切換。如果您的 Azure Cosmos DB 帳戶有允許此子網路的 IP 型防火牆，已啟用服務的子網路所發出的要求將不再符合 IP 防火牆規則，而會被拒絕。

若要深入了解，請參閱本文的從 IP 防火牆規則移轉至虛擬網路存取控制清單一節所說明的步驟。

以下幾節將說明如何設定 Azure Cosmos DB 帳戶的虛擬網路服務端點。

使用 Azure 入口網站來設定服務端點

對現有的 Azure 虛擬網路和子網路設定服務端點

從 [所有資源] 窗格，尋找要保護的 Azure Cosmos DB 帳戶。
從設定功能表中選取 [網路]
選擇允許從 [選取的網路] 存取。
若要將存取權授與現有虛擬網路的子網路，請在 [虛擬網路] 下選取 [新增現有 Azure 虛擬網路]。
選取您要從中新增 Azure 虛擬網路的訂用帳戶。選取要提供 Azure Cosmos DB 帳戶存取權的 Azure 虛擬網路和子網路。接下來，選取 [啟用] 以啟用具有 "Microsoft.AzureCosmosDB" 服務端點的選定網路。完成時選取 [新增]。

注意

設定 VNET 服務端點可能需要長達 15分鐘來傳播，在這段期間，端點可能出現不一致的行為。
在 Azure Cosmos DB 帳戶啟用從虛擬網路的存取後，它將只會允許來自這個選定子網路的流量。您所新增的虛擬網路和子網路應會如下列螢幕擷取畫面所示：

注意

若要啟用虛擬網路服務端點，您必須具備下列訂用帳戶權限：

虛擬網路的訂用帳戶：網路參與者
Azure Cosmos DB 帳戶的訂用帳戶：DocumentDB 帳戶參與者
如果虛擬網路和 Azure Cosmos DB 帳戶在不同的訂用帳戶中，請確定虛擬網路所在的訂用帳戶也已註冊 Microsoft.DocumentDB 資源提供者。若要註冊資源提供者，請參閱 Azure 資源提供者和類型一文。

這裡提供向資源提供者註冊訂用帳戶的指示。

對新的 Azure 虛擬網路和子網路設定服務端點

從 [所有資源] 窗格，尋找要保護的 Azure Cosmos DB 帳戶。
從設定功能表中選取 [網路]，並選擇允許從 [選取的網路] 進行存取。
若要授與新 Azure 虛擬網路的存取權，請在 [虛擬網路] 下選取 [新增虛擬網路]。
提供建立新虛擬網路所需的詳細資料，然後選取 [建立]。這會建立已啟用 "Microsoft.AzureCosmosDB" 服務端點的子網路。

如果您的 Azure Cosmos DB 帳戶由其他 Azure 服務使用 (例如 Azure AI 搜尋服務)，或由串流分析或 Power BI 存取，請選取 [接受來自全球 Azure 資料中心內的連線] 來允許存取。

若要確保您可以從入口網站存取 Azure Cosmos DB 計量，您必須啟用 [允許從 Azure 入口網站存取] 選項。若要深入了解這些選項，請參閱設定 IP 防火牆一文。啟用存取之後，請選取 [儲存] 以儲存設定。

移除現有虛擬網路或子網路

從 [所有資源] 窗格，尋找您要對其指派端點的 Azure Cosmos DB 帳戶。
從設定功能表中選取 [網路]。
若要移除虛擬網路或子網路規則，請選取該虛擬網路或子網路旁的 […]，然後選取 [移除]。
選取儲存套用變更。

使用 Azure PowerShell 來設定服務端點

注意

建議您使用 Azure Az PowerShell 模組來與 Azure 互動。請參閱安裝 Azure PowerShell 以開始使用。若要了解如何移轉至 Az PowerShell 模組，請參閱將 Azure PowerShell 從 AzureRM 移轉至 Az。

若要使用 Azure PowerShell 對 Azure Cosmos DB 帳戶設定服務端點，請使用下列步驟：

安裝 Azure PowerShell 並登入。

對現有的虛擬網路子網路啟用服務端點。

$resourceGroupName = "<Resource group name>"
$vnetName = "<Virtual network name>"
$subnetName = "<Subnet name>"
$subnetPrefix = "<Subnet address range>"
$serviceEndpoint = "Microsoft.AzureCosmosDB"

Get-AzVirtualNetwork `
   -ResourceGroupName $resourceGroupName `
   -Name $vnetName | Set-AzVirtualNetworkSubnetConfig `
   -Name $subnetName `
   -AddressPrefix $subnetPrefix `
   -ServiceEndpoint $serviceEndpoint | Set-AzVirtualNetwork

注意

當您使用 PowerShell 或 Azure CLI 時，請務必在參數中指定 IP 篩選器和虛擬網路 ACL 的完整清單，而不是只指定必須新增的項目。

取得虛擬網路資訊。

$vnet = Get-AzVirtualNetwork `
   -ResourceGroupName $resourceGroupName `
   -Name $vnetName

$subnetId = $vnet.Id + "/subnets/" + $subnetName

準備 Azure Cosmos DB 虛擬網路規則

$vnetRule = New-AzCosmosDBVirtualNetworkRule `
   -Id $subnetId

使用新的虛擬網路端點設定來更新 Azure Cosmos DB 帳戶屬性：

$accountName = "<Azure Cosmos DB account name>"

Update-AzCosmosDBAccount `
   -ResourceGroupName $resourceGroupName `
   -Name $accountName `
   -EnableVirtualNetwork $true `
   -VirtualNetworkRuleObject @($vnetRule)

若要確認 Azure Cosmos DB 帳戶已透過上一個步驟中設定的虛擬網路服務端點進行更新，請執行下列命令：

$account = Get-AzCosmosDBAccount `
   -ResourceGroupName $resourceGroupName `
   -Name $accountName

$account.IsVirtualNetworkFilterEnabled
$account.VirtualNetworkRules

使用 Azure CLI 來設定服務端點

稍後建立或更新服務端點時，如果已設定子網路，則可設定 Azure Cosmos DB 帳戶。在尚未設定子網路的 Azure Cosmos DB 帳戶上，也可以啟用服務端點。然後，服務端點會在稍後設定子網路時開始運作。這種彈性讓無法同時存取 Azure Cosmos DB 帳戶與虛擬網路資源的管理員能夠個別設定這兩者。

建立新的 Azure Cosmos DB 帳戶並連線至新虛擬網路的後端子網路

在此範例中，虛擬網路和子網路建立時都啟用服務端點。

# Create an Azure Cosmos DB Account with a service endpoint connected to a backend subnet

# Resource group and Azure Cosmos DB account variables
resourceGroupName='MyResourceGroup'
location='West US 2'
accountName='mycosmosaccount'

# 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 with service endpoints enabled for Azure Cosmos DB
az network vnet subnet create \
   -n $backEnd \
   -g $resourceGroupName \
   --address-prefix 10.0.2.0/24 \
   --vnet-name $vnetName \
   --service-endpoints Microsoft.AzureCosmosDB

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

# Create an Azure Cosmos DB account with default values and service endpoints
az cosmosdb create \
   -n $accountName \
   -g $resourceGroupName \
   --enable-virtual-network true \
   --virtual-network-rules $svcEndpoint

獨立設定 Azure Cosmos DB 帳戶並連線至後端子網路

此範例旨在示範如何將 Azure Cosmos DB 帳戶連線至現有或新的虛擬網路。在此範例中，尚未針對服務端點設定子網路。使用 --ignore-missing-vnet-service-endpoint 參數設定服務端點。此設定允許在虛擬網路的子網路完成設定之前，正確無誤地完成 Azure Cosmos DB 帳戶。子網路設定完成後，便可透過設定的子網路存取 Azure Cosmos DB 帳戶。

# Create an Azure Cosmos DB Account with a service endpoint connected to a backend subnet
# that is not yet enabled for service endpoints.

# Resource group and Azure Cosmos DB account variables
resourceGroupName='MyResourceGroup'
location='West US 2'
accountName='mycosmosaccount'

# 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 configuring service endpoints (--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 an Azure Cosmos DB account with default values
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 now configure the subnet for service endpoints'

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

使用直接模式時的連接埠範圍

當您以 Azure Cosmos DB 帳戶透過直接模式連線使用服務端點時，必須確定已開放 10000 到 20000 的 TCP 連接埠範圍。

從 IP 防火牆規則移轉至虛擬網路 ACL

若要將 Azure Cosmos DB 帳戶從使用 IP 防火牆規則遷移至使用虛擬網路服務端點，請使用下列步驟。

針對子網路的服務端點設定 Azure Cosmos DB 帳戶之後，來自該子網路的每項要求都會以不同方式傳送至 Azure Cosmos DB。要求會隨著虛擬網路和子網路來源資訊傳送，而不是來源公用 IP 位址。這些要求不再符合 Azure Cosmos DB 帳戶上設定的 IP 篩選條件，因此需要下列步驟以避免停機。

取得虛擬網路和子網路資訊：

$resourceGroupName = "myResourceGroup"
$accountName = "mycosmosaccount"
$vnetName = "myVnet"
$subnetName = "mySubnet"

$vnet = Get-AzVirtualNetwork `
   -ResourceGroupName $resourceGroupName `
   -Name $vnetName

$subnetId = $vnet.Id + "/subnets/" + $subnetName

為 Azure Cosmos DB 帳戶準備新的虛擬網路規則物件：

$vnetRule = New-AzCosmosDBVirtualNetworkRule `
   -Id $subnetId

將 Azure Cosmos DB 帳戶更新為可供服務端點從子網路存取：

Update-AzCosmosDBAccount `
   -ResourceGroupName $resourceGroupName `
   -Name $accountName `
   -EnableVirtualNetwork $true `
   -VirtualNetworkRuleObject @($vnetRule)

針對從子網路存取的所有 Azure Cosmos DB 帳戶，重複上述步驟。
請依照此文章的針對虛擬網路的現有子網路啟用服務端點一節中所示的步驟，在虛擬網路和子網路上啟用 Azure Cosmos DB 服務端點。
從 Azure Cosmos DB 帳戶的防火牆規則中，移除子網路的 IP 防火牆規則。

常見問題集

以下是與從虛擬網路設定存取權的一些常見問答集：

Notebook 和 Mongo/Cassandra 殼層目前與已啟用虛擬網路的帳戶是否相容？

目前，VNET 存取不支援 Azure Cosmos DB 資料總管中的 Mongo 殼層和 Cassandra 殼層整合，以及 Jupyter Notebook 服務。目前正在積極開發此整合。

是否可以在 Azure Cosmos DB 帳戶中同時指定虛擬網路服務端點和 IP 存取控制原則？

您可以在 Azure Cosmos DB 帳戶上同時啟用虛擬網路服務端點和 IP 存取控制原則 (也稱為防火牆)。這兩個功能彼此互補，且可共同確保 Azure Cosmos DB 帳戶的隔離與安全性。使用 IP 防火牆可確保靜態 IP 可以存取您的帳戶。

如何限制對虛擬網路內子網路的存取？

若要限制從子網路存取 Azure Cosmos DB 帳戶，必須執行兩個步驟。首先，您要允許子網路流量將其子網路和虛擬網路身分識別攜帶至 Azure Cosmos DB。在子網路上啟用 Azure Cosmos DB 的服務端點，即可變更流量的身分識別。接下來要在 Azure Cosmos DB 帳戶中新增規則，將這個子網路指定為可存取帳戶的來源。

虛擬網路 ACL 與 IP 防火牆會拒絕要求或連線嗎？

在新增了 IP 防火牆或虛擬網路存取規則時，只有來自已允許來源的要求能取得有效回應。系統會拒絕其他要求，並顯示 403 (禁止)。請務必區別 Azure Cosmos DB 帳戶的防火牆和連線層級防火牆。來源仍可連線至服務，且連線本身不會被拒絕。

當我在子網路上啟用 Azure Cosmos DB 的服務端點時，我的要求開始遭到封鎖。發生什麼事？

在子網路上啟用 Azure Cosmos DB 的服務端點後，送到帳戶的流量來源就會從公用 IP 切換至虛擬網路和子網路。如果您的 Azure Cosmos DB 帳戶只有 IP 型防火牆，來自已啟用服務之子網路的流量將不再符合 IP 防火牆規則，因此會遭到拒絕。請執行步驟以順暢地從 IP 型防火牆移轉至虛擬網路型存取控制。

具有 VNET 服務端點的 Azure Cosmos DB 帳戶是否需要額外的 Azure 角色型存取控制權限？

當您將 VNET 服務端點新增至 Azure Cosmos DB 帳戶之後，若要對帳戶設定進行任何變更，您需要針對 Azure Cosmos DB 帳戶上設定的所有 VNET 存取 Microsoft.Network/virtualNetworks/subnets/joinViaServiceEndpoint/action 動作。這是必要權限，因為授權程序驗證對資源 (例如，資料庫和虛擬網路資源) 的存取，然後再評估任何屬性。

即使使用者未使用 Azure CLI 來指定 VNET ACL，授權還是會驗證 VNet 資源動作的權限。目前，Azure Cosmos DB 帳戶的控制平面支援設定 Azure Cosmos DB 帳戶的完成狀態。控制平面呼叫的其中一個參數是 virtualNetworkRules。如果未指定此參數，Azure CLI 會進行 GET 資料庫呼叫以擷取 virtualNetworkRules，並在更新呼叫中使用此值。

對等互連的虛擬網路也可以存取 Azure Cosmos DB 帳戶嗎？

只有新增至 Azure Cosmos DB 帳戶的虛擬網路及其子網路可以存取。只有將對等互連之虛擬網路內的子網路新增到帳戶之後，其對等互連的 VNet 才能存取帳戶。

允許存取單一 Azure Cosmos DB 帳戶的子網路數目上限為何？

目前，針對一個 Azure Cosmos DB 帳戶，您最多可以有 256 個子網路。

可以啟用來自 VPN 和 Express Route 的存取嗎？

若要透過快速路由從內部部署存取 Azure Cosmos DB 帳戶，您需要啟用 Microsoft 對等互連。一旦制訂 IP 防火牆或虛擬網路存取規則之後，就可以新增公用 IP 位址 (用於您 Azure Cosmos DB 帳戶 IP 防火牆上的 Microsoft 對等互連)，以允許內部部署服務存取 Azure Cosmos DB 帳戶。

我需要更新網路安全性群組 (NSG) 規則嗎？

NSG 規則可用來限制子網路和虛擬網路的往返連線。當您將 Azure Cosmos DB 的服務端點新增至子網路時，不需要在 NSG 中針對您的 Azure Cosmos DB 帳戶開啟輸出連線。

服務端點是否可供所有 VNet 使用？

否，只有 Azure Resource Manager 虛擬網路可以啟用服務端點。傳統虛擬網路不支援服務端點。

何時應該針對 Azure Cosmos DB 帳戶接受來自全域 Azure 資料中心的連線？

只有當您想要讓 Azure Cosmos DB 帳戶可供任何 Azure 區域中的任何 Azure 服務存取時，才應該啟用此設定。其他 Azure 第一方服務，例如 Azure Data Factory 和 Azure AI 搜尋服務提供了文件，說明如何保護對資料來源的存取，包含 Azure Cosmos DB 帳戶，例如：

下一步

若要設定 Azure Cosmos DB 的防火牆，請參閱防火牆支援一文。