为 Azure Cosmos DB 帐户配置 Azure 专用链接

项目
10/08/2023

适用对象： NoSQL MongoDB Cassandra Gremlin 表

通过使用 Azure 专用链接，可以通过专用终结点连接到 Azure Cosmos DB 帐户。专用终结点是虚拟网络中某个子网内的一组专用 IP 地址。然后，可以通过专用 IP 地址限制对 Azure Cosmos DB 帐户的访问。当结合使用专用链接与限制性的 NSG 策略时，有助于降低数据外泄的风险。要详细了解专用终结点，请参阅什么是 Azure 专用链接？

注意

专用链接不会阻止公共 DNS 解析 Azure Cosmos DB 终结点。筛选传入请求在应用程序级别（而不是传输或网络级别）进行。

专用链接允许用户从虚拟网络内或任何对等虚拟网络访问 Azure Cosmos DB 帐户。还可以在本地使用 VPN 或 Azure ExpressRoute 通过专用对等互连访问映射到专用链接的资源。

你可以使用自动或手动审批方法连接到使用专用链接配置的 Azure Cosmos DB 帐户。要了解详细信息，请参阅专用链接文档的审批工作流部分。

本文介绍如何为 Azure Cosmos DB 事务存储设置专用终结点。它假设你使用的是自动审批方法。如果使用的是分析存储，请参阅配置面向分析存储的专用终结点。

使用 Azure 门户创建专用终结点

按照以下步骤，通过使用 Azure 门户为现有 Azure Cosmos DB 帐户创建专用终结点：

登录到 Azure 门户，然后选择 Azure Cosmos DB 帐户。
从设置列表中选择“网络”，然后在“专用访问”选项卡下选择“+ 专用终结点”：

在“创建专用终结点 - 基本信息”窗格中，输入或选择以下详细信息：

设置	值
项目详细信息
订阅	选择订阅。
资源组	选一个择资源组。
实例详细信息
名称	为专用终结点输入任意名称。如果此名称已被使用，请创建唯一的名称。
区域	选择要在其中部署专用链接的区域。在虚拟网络所在的位置创建专用终结点。

在完成时选择“下一步:资源”。

在“创建专用终结点 - 资源”窗格中，输入或选择以下信息：

设置	值
连接方法	选择“连接到我的目录中的 Azure 资源”。然后，可以选择一个资源来设置专用链接。或者，可以使用他人与你共享的资源 ID 或别名连接到其资源。
订阅	选择订阅。
资源类型	选择“Microsoft.AzureCosmosDB/databaseAccounts”。
资源	选择 Azure Cosmos DB 帐户。
目标子资源	选择要映射的 Azure Cosmos DB API 类型。默认情况下，适用于 SQL、MongoDB 和 Cassandra 的 API 只有一种选择。对于 Gremlin 和 Table 的 API，还可以选择“NoSQL”，因为这些 API 可以与 NoSQL API 进行互操作。

选择“下一步: 虚拟网络”。
在“创建专用终结点 - 虚拟网络”窗格中，输入或选择以下信息：

设置值

虚拟网络选择你的虚拟网络。

子网选择子网。
选择“下一步: DNS”。

设置	值
虚拟网络	选择你的虚拟网络。
子网	选择子网。

在“创建专用终结点 - DNS”中，输入或选择以下信息：

设置	值
与专用 DNS 区域集成	请选择“是”。若要以私密方式连接到专用终结点，需有一条 DNS 记录。建议将专用终结点与专用 DNS 区域集成。你也可以使用自己的 DNS 服务器，或者使用虚拟机上的主机文件创建 DNS 记录。为此选项选择“是”时，还将创建一个专用 DNS 区域组。 DNS 区域组是专用 DNS 区域和专用终结点之间的链接。当专用终结点进行更新时，此链接可帮助你自动更新专用 DNS 区域。例如，添加或删除区域后，会自动更新专用 DNS 区域。
配置名称	选择订阅和资源组。系统会自动确定专用 DNS 区域。无法使用 Azure 门户更改此区域。

设置

值

与专用 DNS 区域集成

请选择“是”。

若要以私密方式连接到专用终结点，需有一条 DNS 记录。建议将专用终结点与专用 DNS 区域集成。你也可以使用自己的 DNS 服务器，或者使用虚拟机上的主机文件创建 DNS 记录。

为此选项选择“是”时，还将创建一个专用 DNS 区域组。 DNS 区域组是专用 DNS 区域和专用终结点之间的链接。当专用终结点进行更新时，此链接可帮助你自动更新专用 DNS 区域。例如，添加或删除区域后，会自动更新专用 DNS 区域。

配置名称

选择订阅和资源组。

系统会自动确定专用 DNS 区域。无法使用 Azure 门户更改此区域。

选择“下一步：标记”>“审阅 + 创建”。在“查看 + 创建”页上，Azure 会验证你的配置。
看到“验证通过”消息时，选择“创建” 。

在适用于 Azure Cosmos DB 帐户的专用链接获得批准后，在 Azure 门户中，“防火墙和虚拟网络”窗格中的“所有网络”选项将不可用。

API 类型和专用区域名称

下表显示了不同 Azure Cosmos DB 帐户 API 类型、支持的子资源和相应专用区域名称之间的映射。还可以通过 API for NoSQL 访问 Gremlin 和 API for Table 帐户，因此这些 API 有两个条目。

Azure Cosmos DB 帐户 API 类型	支持的子资源或组 ID	专用区域名称
NoSQL	Sql	privatelink.documents.azure.cn
Cassandra	Cassandra	privatelink.cassandra.cosmos.azure.cn
Mongo	MongoDB	privatelink.mongo.cosmos.azure.cn
Gremlin	Gremlin	privatelink.gremlin.cosmos.azure.cn
Gremlin	Sql	privatelink.documents.azure.cn
表	表	privatelink.table.cosmos.azure.cn
表	Sql	privatelink.documents.azure.cn

提取专用 IP 地址

预配专用终结点后，可以查询 IP 地址。若要在 Azure 门户中查看 IP 地址，请执行以下操作：

搜索前面创建的专用终结点。在本例中，该终结点为 cdbPrivateEndpoint3。
选择“概览”选项卡，查看 DNS 设置和 IP 地址。

Screenshot of private IP addresses in the Azure portal

可为每个专用终结点创建多个 IP 地址：

一个 IP 地址用于 Azure Cosmos DB 帐户的与区域无关的多区域终结点。
每个部署 Azure Cosmos DB 帐户的区域使用一个。

使用 Azure PowerShell 创建专用终结点

运行以下 PowerShell 脚本，为现有 Azure Cosmos DB 帐户创建名为 MyPrivateEndpoint 的专用终结点。请将变量值替换为你的环境的详细信息。

$SubscriptionId = "<your Azure subscription ID>"
# Resource group where the Azure Cosmos DB account and virtual network resources are located
$ResourceGroupName = "myResourceGroup"
# Name of the Azure Cosmos DB account
$CosmosDbAccountName = "mycosmosaccount"

# Resource for the Azure Cosmos DB account: Sql, MongoDB, Cassandra, Gremlin, or Table
$CosmosDbSubResourceType = "Sql"
# Name of the existing virtual network
$VNetName = "myVnet"
# Name of the target subnet in the virtual network
$SubnetName = "mySubnet"
# Name of the private endpoint to create
$PrivateEndpointName = "MyPrivateEndpoint"
# Location where the private endpoint can be created. The private endpoint should be created in the same location where your subnet or the virtual network exists
$Location = "chinaeast2"

$cosmosDbResourceId = "/subscriptions/$($SubscriptionId)/resourceGroups/$($ResourceGroupName)/providers/Microsoft.DocumentDB/databaseAccounts/$($CosmosDbAccountName)"

$privateEndpointConnection = New-AzPrivateLinkServiceConnection -Name "myConnectionPS" -PrivateLinkServiceId $cosmosDbResourceId -GroupId $CosmosDbSubResourceType
 
$virtualNetwork = Get-AzVirtualNetwork -ResourceGroupName  $ResourceGroupName -Name $VNetName  
 
$subnet = $virtualNetwork | Select -ExpandProperty subnets | Where-Object  {$_.Name -eq $SubnetName}  
 
$privateEndpoint = New-AzPrivateEndpoint -ResourceGroupName $ResourceGroupName -Name $PrivateEndpointName -Location $Location -Subnet  $subnet -PrivateLinkServiceConnection $privateEndpointConnection

将专用终结点与专用 DNS 区域集成

创建专用终结点后，可以使用以下 PowerShell 脚本将其与专用 DNS 区域集成：

Import-Module Az.PrivateDns

# Zone name differs based on the API type and group ID you are using. 
$zoneName = "privatelink.documents.azure.cn"
$zone = New-AzPrivateDnsZone -ResourceGroupName $ResourceGroupName `
  -Name $zoneName

$link  = New-AzPrivateDnsVirtualNetworkLink -ResourceGroupName $ResourceGroupName `
  -ZoneName $zoneName `
  -Name "myzonelink" `
  -VirtualNetworkId $virtualNetwork.Id  
 
$pe = Get-AzPrivateEndpoint -Name $PrivateEndpointName `
  -ResourceGroupName $ResourceGroupName

$networkInterface = Get-AzResource -ResourceId $pe.NetworkInterfaces[0].Id `
  -ApiVersion "2019-04-01"

# Create DNS configuration

$PrivateDnsZoneId = $zone.ResourceId

$config = New-AzPrivateDnsZoneConfig -Name $zoneName `
 -PrivateDnsZoneId $PrivateDnsZoneId

## Create a DNS zone group
New-AzPrivateDnsZoneGroup -ResourceGroupName $ResourceGroupName `
 -PrivateEndpointName $PrivateEndpointName `
 -Name "MyPrivateZoneGroup" `
 -PrivateDnsZoneConfig $config

提取专用 IP 地址

预配专用终结点后，可以使用以下 PowerShell 脚本查询 IP 地址和 FQDN 映射：

$pe = Get-AzPrivateEndpoint -Name MyPrivateEndpoint -ResourceGroupName myResourceGroup
$networkInterface = Get-AzNetworkInterface -ResourceId $pe.NetworkInterfaces[0].Id
foreach ($IPConfiguration in $networkInterface.IpConfigurations)
{
    Write-Host $IPConfiguration.PrivateIpAddress ":" $IPConfiguration.PrivateLinkConnectionProperties.Fqdns
}

使用 Azure CLI 创建专用终结点

运行以下 Azure CLI 脚本，为现有 Azure Cosmos DB 帐户创建名为 myPrivateEndpoint 的专用终结点。请将变量值替换为你的环境的详细信息。

# Resource group where the Azure Cosmos DB account and virtual network resources are located
ResourceGroupName="myResourceGroup"

# Subscription ID where the Azure Cosmos DB account and virtual network resources are located
SubscriptionId="<your Azure subscription ID>"

# Name of the existing Azure Cosmos DB account
CosmosDbAccountName="mycosmosaccount"

# API type of your Azure Cosmos DB account: Sql, MongoDB, Cassandra, Gremlin, or Table
CosmosDbSubResourceType="Sql"

# Name of the virtual network to create
VNetName="myVnet"

# Name of the subnet to create
SubnetName="mySubnet"

# Name of the private endpoint to create
PrivateEndpointName="myPrivateEndpoint"

# Name of the private endpoint connection to create
PrivateConnectionName="myConnection"

az network vnet create \
 --name $VNetName \
 --resource-group $ResourceGroupName \
 --subnet-name $SubnetName

az network vnet subnet update \
 --name $SubnetName \
 --resource-group $ResourceGroupName \
 --vnet-name $VNetName \
 --disable-private-endpoint-network-policies true

az network private-endpoint create \
    --name $PrivateEndpointName \
    --resource-group $ResourceGroupName \
    --vnet-name $VNetName  \
    --subnet $SubnetName \
    --private-connection-resource-id "/subscriptions/$SubscriptionId/resourceGroups/$ResourceGroupName/providers/Microsoft.DocumentDB/databaseAccounts/$CosmosDbAccountName" \
    --group-ids $CosmosDbSubResourceType \
    --connection-name $PrivateConnectionName

将专用终结点与专用 DNS 区域集成

创建专用终结点后，可以使用以下 Azure CLI 脚本将其与专用 DNS 区域集成：

#Zone name differs based on the API type and group ID you are using. 
zoneName="privatelink.documents.azure.cn"

az network private-dns zone create --resource-group $ResourceGroupName \
   --name  $zoneName

az network private-dns link vnet create --resource-group $ResourceGroupName \
   --zone-name  $zoneName\
   --name myzonelink \
   --virtual-network $VNetName \
   --registration-enabled false 

#Create a DNS zone group
az network private-endpoint dns-zone-group create \
   --resource-group $ResourceGroupName \
   --endpoint-name $PrivateEndpointName \
   --name "MyPrivateZoneGroup" \
   --private-dns-zone $zoneName \
   --zone-name "myzone"

使用资源管理器模板创建专用终结点

可以通过在虚拟网络子网中创建专用终结点来设置专用链接。使用 Azure 资源管理器模板可以实现此目的。

使用以下代码创建名为 PrivateEndpoint_template.json 的资源管理器模板。此模板可为现有虚拟网络中的现有 Azure Cosmos DB vAPI for NoSQL 帐户创建专用终结点。

Bicep
JSON

@description('Location for all resources.')
param location string = resourceGroup().location
param privateEndpointName string
param resourceId string
param groupId string
param subnetId string

resource privateEndpoint 'Microsoft.Network/privateEndpoints@2019-04-01' = {
  name: privateEndpointName
  location: location
  properties: {
    subnet: {
      id: subnetId
    }
    privateLinkServiceConnections: [
      {
        name: 'MyConnection'
        properties: {
          privateLinkServiceId: resourceId
          groupIds: [
            groupId
          ]
          requestMessage: ''
        }
      }
    ]
  }
}

output privateEndpointNetworkInterface string = privateEndpoint.properties.networkInterfaces[0].id

{
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "location": {
          "type": "string",
          "defaultValue": "[resourceGroup().location]",
          "metadata": {
            "description": "Location for all resources."
          }
        },
        "privateEndpointName": {
            "type": "string"
        },
        "resourceId": {
            "type": "string"
        },
        "groupId": {
            "type": "string"
        },
        "subnetId": {
            "type": "string"
        }
    },
    "resources": [
        {
            "name": "[parameters('privateEndpointName')]",
            "type": "Microsoft.Network/privateEndpoints",
            "apiVersion": "2019-04-01",
            "location": "[parameters('location')]",
            "properties": {
                "subnet": {
                    "id": "[parameters('subnetId')]"
                },
                "privateLinkServiceConnections": [
                    {
                        "name": "MyConnection",
                        "properties": {
                            "privateLinkServiceId": "[parameters('resourceId')]",
                            "groupIds": [ "[parameters('groupId')]" ],
                            "requestMessage": ""
                        }
                    }
                ]
            }
        }
    ],
    "outputs": {
        "privateEndpointNetworkInterface": {
          "type": "string",
          "value": "[reference(concat('Microsoft.Network/privateEndpoints/', parameters('privateEndpointName'))).networkInterfaces[0].id]"
        }
    }
}

定义模板的参数文件

为模板创建一个参数文件，并将其命名为 PrivateEndpoint_parameters.json。将以下代码添加到参数文件：

Bicep/JSON

{
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "privateEndpointName": {
            "value": ""
        },
        "resourceId": {
            "value": ""
        },
        "groupId": {
            "value": ""
        },
        "subnetId": {
            "value": ""
        }
    }
}

使用 PowerShell 脚本部署模板

使用以下代码创建 PowerShell 脚本。在运行该脚本之前，请将订阅 ID、资源组名称和其他变量值替换为你的环境的详细信息。

### This script creates a private endpoint for an existing Azure Cosmos DB account in an existing virtual network

## Step 1: Fill in these details. Replace the variable values with the details for your environment.
$SubscriptionId = "<your Azure subscription ID>"
# Resource group where the Azure Cosmos DB account and virtual network resources are located
$ResourceGroupName = "myResourceGroup"
# Name of the Azure Cosmos DB account
$CosmosDbAccountName = "mycosmosaccount"
# API type of the Azure Cosmos DB account. It can be one of the following: "Sql", "MongoDB", "Cassandra", "Gremlin", "Table"
$CosmosDbSubResourceType = "Sql"
# Name of the existing virtual network
$VNetName = "myVnet"
# Name of the target subnet in the virtual network
$SubnetName = "mySubnet"
# Name of the private endpoint to create
$PrivateEndpointName = "myPrivateEndpoint"

$cosmosDbResourceId = "/subscriptions/$($SubscriptionId)/resourceGroups/$($ResourceGroupName)/providers/Microsoft.DocumentDB/databaseAccounts/$($CosmosDbAccountName)"
$VNetResourceId = "/subscriptions/$($SubscriptionId)/resourceGroups/$($ResourceGroupName)/providers/Microsoft.Network/virtualNetworks/$($VNetName)"
$SubnetResourceId = "$($VNetResourceId)/subnets/$($SubnetName)"
$PrivateEndpointTemplateFilePath = "PrivateEndpoint_template.json"
$PrivateEndpointParametersFilePath = "PrivateEndpoint_parameters.json"

## Step 2: Sign in to your Azure account and select the target subscription.
Connect-AzAccount -Environment AzureChinaCloud
Select-AzSubscription -SubscriptionId $subscriptionId

## Step 3: Make sure private endpoint network policies are disabled in the subnet.
$VirtualNetwork= Get-AzVirtualNetwork -Name "$VNetName" -ResourceGroupName "$ResourceGroupName"
($virtualNetwork | Select -ExpandProperty subnets | Where-Object  {$_.Name -eq "$SubnetName"} ).PrivateEndpointNetworkPolicies = "Disabled"
$virtualNetwork | Set-AzVirtualNetwork

## Step 4: Create the private endpoint.
Write-Output "Deploying private endpoint on $($resourceGroupName)"
$deploymentOutput = New-AzResourceGroupDeployment -Name "PrivateCosmosDbEndpointDeployment" `
    -ResourceGroupName $resourceGroupName `
    -TemplateFile $PrivateEndpointTemplateFilePath `
    -TemplateParameterFile $PrivateEndpointParametersFilePath `
    -SubnetId $SubnetResourceId `
    -ResourceId $CosmosDbResourceId `
    -GroupId $CosmosDbSubResourceType `
    -PrivateEndpointName $PrivateEndpointName

$deploymentOutput

在该 PowerShell 脚本中，GroupId 变量只能包含一个值。该值是帐户的 API 类型。允许的值为：Sql、MongoDB、Cassandra、Gremlin 和 Table。某些 Azure Cosmos DB 帐户类型可通过多个 API 访问。例如：

可以从 Gremlin 和 API for NoSQL 帐户访问 API for Gremlin 帐户。
可以从 Table 和 API for NoSQL 帐户访问 API for Table 帐户。

对于这些帐户，必须为每个 API 类型创建一个专用终结点。相应的 API 类型在 GroupId 数组中指定。

成功部署模板后，可以看到类似于下图所示的输出。如果正确设置了专用终结点，则 provisioningState 值为 Succeeded。

Screenshot of deployment output for the Resource Manager template.

部署模板后，专用 IP 地址会保留在子网中。 Azure Cosmos DB 帐户的防火墙规则配置为仅接受来自专用终结点的连接。

将专用终结点与专用 DNS 区域集成

使用以下代码创建名为 PrivateZone_template.json 的资源管理器模板。此模板可为现有虚拟网络中的现有 Azure Cosmos DB API for NoSQL 帐户创建专用终结点。

{
    "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "privateZoneName": {
            "type": "string"
        },
        "VNetId": {
            "type": "string"
        }        
    },
    "resources": [
        {
            "name": "[parameters('privateZoneName')]",
            "type": "Microsoft.Network/privateDnsZones",
            "apiVersion": "2018-09-01",
            "location": "global",
            "properties": {                
            }
        },
        {
            "type": "Microsoft.Network/privateDnsZones/virtualNetworkLinks",
            "apiVersion": "2018-09-01",
            "name": "[concat(parameters('privateZoneName'), '/myvnetlink')]",
            "location": "global",
            "dependsOn": [
                "[resourceId('Microsoft.Network/privateDnsZones', parameters('privateZoneName'))]"
            ],
            "properties": {
                "registrationEnabled": false,
                "virtualNetwork": {
                    "id": "[parameters('VNetId')]"
                }
            }
        }        
    ]
}

定义模板的参数文件

为该模板创建以下两个参数文件。使用以下代码创建 PrivateZone_parameters.json：

{
    "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentParameters.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "privateZoneName": {
            "value": ""
        },
        "VNetId": {
            "value": ""
        }
    }
}

使用以下代码创建名为 PrivateZoneGroup_template.json 的资源管理器模板。此模板可在现有虚拟网络中为现有 Azure Cosmos DB API for NoSQL 帐户创建专用 DNS 区域组。

{
    "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "privateZoneName": {
            "type": "string"
        },
        "PrivateEndpointDnsGroupName": {
            "value": "string"
        },
        "privateEndpointName":{
            "value": "string"
        }        
    },
    "resources": [
        {
            "type": "Microsoft.Network/privateEndpoints/privateDnsZoneGroups",
            "apiVersion": "2020-06-01",
            "name": "[parameters('PrivateEndpointDnsGroupName')]",
            "location": "global",
            "dependsOn": [
                "[resourceId('Microsoft.Network/privateDnsZones', parameters('privateZoneName'))]",
                "[variables('privateEndpointName')]"
            ],
          "properties": {
            "privateDnsZoneConfigs": [
              {
                "name": "config1",
                "properties": {
                  "privateDnsZoneId": "[resourceId('Microsoft.Network/privateDnsZones', parameters('privateZoneName'))]"
                }
              }
            ]
          }
        }
    ]
}

定义模板的参数文件

为该模板创建以下两个参数文件。创建 PrivateZoneGroup_parameters.json。替换为以下代码：

{
    "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentParameters.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "privateZoneName": {
            "value": ""
        },
        "PrivateEndpointDnsGroupName": {
            "value": ""
        },
        "privateEndpointName":{
            "value": ""
        }
    }
}

使用 PowerShell 脚本部署模板

使用以下代码创建 PowerShell 脚本。在运行该脚本之前，请将订阅 ID、资源组名称和其他变量值替换为你的环境的详细信息。

### This script:
### - creates a private zone
### - creates a private endpoint for an existing Azure Cosmos DB account in an existing VNet
### - maps the private endpoint to the private zone

## Step 1: Fill in these details. Replace the variable values with the details for your environment.
$SubscriptionId = "<your Azure subscription ID>"
# Resource group where the Azure Cosmos DB account and virtual network resources are located
$ResourceGroupName = "myResourceGroup"
# Name of the Azure Cosmos DB account
$CosmosDbAccountName = "mycosmosaccount"
# API type of the Azure Cosmos DB account. It can be one of the following: "Sql", "MongoDB", "Cassandra", "Gremlin", "Table"
$CosmosDbSubResourceType = "Sql"
# Name of the existing virtual network
$VNetName = "myVnet"
# Name of the target subnet in the virtual network
$SubnetName = "mySubnet"
# Name of the private zone to create
$PrivateZoneName = "myPrivateZone.documents.azure.cn"
# Name of the private endpoint to create
$PrivateEndpointName = "myPrivateEndpoint"

# Name of the DNS zone group to create
$PrivateEndpointDnsGroupName = "myPrivateDNSZoneGroup"

$cosmosDbResourceId = "/subscriptions/$($SubscriptionId)/resourceGroups/$($ResourceGroupName)/providers/Microsoft.DocumentDB/databaseAccounts/$($CosmosDbAccountName)"
$VNetResourceId = "/subscriptions/$($SubscriptionId)/resourceGroups/$($ResourceGroupName)/providers/Microsoft.Network/virtualNetworks/$($VNetName)"
$SubnetResourceId = "$($VNetResourceId)/subnets/$($SubnetName)"
$PrivateZoneTemplateFilePath = "PrivateZone_template.json"
$PrivateZoneParametersFilePath = "PrivateZone_parameters.json"
$PrivateEndpointTemplateFilePath = "PrivateEndpoint_template.json"
$PrivateEndpointParametersFilePath = "PrivateEndpoint_parameters.json"
$PrivateZoneGroupTemplateFilePath = "PrivateZoneGroup_template.json"
$PrivateZoneGroupParametersFilePath = "PrivateZoneGroup_parameters.json"

## Step 2: Login your Azure account and select the target subscription
Connect-AzAccount -Environment AzureChinaCloud 
Select-AzSubscription -SubscriptionId $subscriptionId

## Step 3: Make sure private endpoint network policies are disabled in the subnet
$VirtualNetwork= Get-AzVirtualNetwork -Name "$VNetName" -ResourceGroupName "$ResourceGroupName"
($virtualNetwork | Select -ExpandProperty subnets | Where-Object  {$_.Name -eq "$SubnetName"} ).PrivateEndpointNetworkPolicies = "Disabled"
$virtualNetwork | Set-AzVirtualNetwork

## Step 4: Create the private zone
New-AzResourceGroupDeployment -Name "PrivateZoneDeployment" `
    -ResourceGroupName $ResourceGroupName `
    -TemplateFile $PrivateZoneTemplateFilePath `
    -TemplateParameterFile $PrivateZoneParametersFilePath `
    -PrivateZoneName $PrivateZoneName `
    -VNetId $VNetResourceId

## Step 5: Create the private endpoint
Write-Output "Deploying private endpoint on $($resourceGroupName)"
$deploymentOutput = New-AzResourceGroupDeployment -Name "PrivateCosmosDbEndpointDeployment" `
    -ResourceGroupName $resourceGroupName `
    -TemplateFile $PrivateEndpointTemplateFilePath `
    -TemplateParameterFile $PrivateEndpointParametersFilePath `
    -SubnetId $SubnetResourceId `
    -ResourceId $CosmosDbResourceId `
    -GroupId $CosmosDbSubResourceType `
    -PrivateEndpointName $PrivateEndpointName
$deploymentOutput

## Step 6: Create the private zone
New-AzResourceGroupDeployment -Name "PrivateZoneGroupDeployment" `
    -ResourceGroupName $ResourceGroupName `
    -TemplateFile $PrivateZoneGroupTemplateFilePath `
    -TemplateParameterFile $PrivateZoneGroupParametersFilePath `
    -PrivateZoneName $PrivateZoneName `
    -PrivateEndpointName $PrivateEndpointName`
    -PrivateEndpointDnsGroupName $PrivateEndpointDnsGroupName

配置自定义 DNS

应在创建了专用终结点的子网中使用专用 DNS 区域。配置终结点，以便将每个专用 IP 地址映射到某个 DNS 条目。请参阅前面显示的响应中的 fqdns 属性。

创建专用终结点时，可将其与 Azure 中的专用 DNS 区域集成。如果选择改用自定义 DNS 区域，则必须对其进行配置，以便为保留给专用终结点使用的所有专用 IP 地址添加 DNS 记录。

重要

它是请求的 DNS 解析，可确定这些请求是通过你的专用终结点，还是使用标准公共路由。请确保你的本地 DNS 正确引用由专用终结点映射的专用 IP 地址。

将专用链接与防火墙规则结合使用

将专用链接与防火墙规则结合使用时，可能会出现以下情况和结果：

如果不配置任何防火墙规则，那么默认情况下，所有流量都可以访问 Azure Cosmos DB 帐户。
如果配置公共流量或服务终结点并创建专用终结点，则不同类型的传入流量将由相应类型的防火墙规则授权。如果配置了服务终结点的子网中还配置了专用终结点：
- 流向由专用终结点映射的数据库帐户的流量通过专用终结点进行路由，
- 从子网流向其他数据库帐户的流量通过服务终结点进行路由。
如果未配置任何公共流量或服务终结点，并且创建了专用终结点，则只能通过专用终结点访问 Azure Cosmos DB 帐户。如果未配置公共流量或服务终结点，则在拒绝或删除所有已批准的专用终结点之后，该帐户将对整个网络开放，除非已将 PublicNetworkAccess 设置为“已禁用”。

在创建帐户期间阻止公共网络访问

如前一部分所述，除非已设置特定的防火墙规则，否则添加专用终结点将使 Azure Cosmos DB 帐户仅可通过专用终结点访问。这意味着可以在创建之后以及添加专用终结点之前从公共流量访问 Azure Cosmos DB 帐户。要确保在创建专用终结点之前已禁用公共网络访问，可以在创建帐户期间将 publicNetworkAccess 标志设置为“已禁用”。请注意，此标志优先于任何 IP 或虚拟网络规则。如果将此标志设置为“已禁用”，则即使防火墙配置中允许使用源 IP 或虚拟网络，也会阻止所有公共和虚拟网络流量。

有关演示如何使用此标志的示例，请参阅此 Azure 资源管理器模板。

在不停机的情况下将专用终结点添加到现有 Azure Cosmos DB 帐户

默认情况下，将专用终结点添加到现有帐户会导致大约五分钟的短暂故障时间。请按照以下说明操作，以免造成此故障时间：

将 IP 或虚拟网络规则添加到防火墙配置，以显式允许客户端连接。
等待 10 分钟，以确保应用配置更新。
配置新的专用终结点。
移除在步骤 1 中设置的防火墙规则。

使用直接模式时的端口范围

通过直接模式连接对 Azure Cosmos DB 帐户使用专用链接时，需要确保打开 TCP 端口的完整范围 (0 - 65535)。

在添加或删除区域时更新专用终结点

有三个 Azure Cosmos DB 帐户部署区域：中国北部、中国北部和中国北部。为帐户创建专用终结点时，子网中会保留四个专用 IP。这三个区域中的每个区域都有一个 IP，而与区域无关的多区域终结点有一个 IP。稍后，你可以向 Azure Cosmos DB 帐户添加一个新区域。专用 DNS 区域更新如下：

如果使用了专用 DNS 区域组：

如果使用专用 DNS 区域组，则在更新专用终结点时，专用 DNS 区域会自动更新。在上一个示例中，添加新区域后，专用 DNS 区域将自动更新。
如果未使用专用 DNS 区域组：

如果使用的不是专用 DNS 区域组，则向 Azure Cosmos DB 帐户添加或移除区域需要添加或移除该帐户的 DNS 条目。添加或删除区域后，可以更新子网的专用 DNS 区域，使之反映已添加或删除的 DNS 条目及其相应的专用 IP 地址。

在上一个示例中，添加新区域后，需要将相应的 DNS 记录添加到专用 DNS 区域或自定义 DNS。删除区域时可以使用相同的步骤。删除区域后，需要从专用 DNS 区域或自定义 DNS 中删除相应的 DNS 记录。

当前限制

将专用链接用于 Azure Cosmos DB 帐户后，将适用以下限制：

一个 Azure Cosmos DB 帐户上最多只能有 200 个专用终结点。
在通过直接模式结合使用专用链接和 Azure Cosmos DB 帐户时，只能使用 TCP 协议。 HTTP 协议目前不受支持。
如果将 Azure Cosmos DB 的 API 用于 MongoDB 帐户，版本 3.6 或更高版本的服务器上的帐户（即使用格式为 *.mongo.cosmos.azure.cn 的终结点的帐户）支持专用终结点。服务器版本 3.2（即使用格式为 *.documents.azure.cn 的终结点的帐户）上的帐户不支持专用链接。若要使用专用链接，应将旧帐户迁移到新版本。
如果将 Azure Cosmos DB 的 API 用于具有专用链接的 MongoDB 帐户，则工具/库必须支持服务器名称标识 (SNI)，或传递连接字符串中的 appName 参数来实现正确连接。某些较旧的工具和库可能与专用链接功能不兼容。
至少要为网络管理员授予 Azure Cosmos DB 帐户范围的 Microsoft.DocumentDB/databaseAccounts/PrivateEndpointConnectionsApproval/action 权限，管理员才能创建自动批准的专用终结点。
目前，无法批准已拒绝的专用终结点连接。但是，请重新创建专用终结点以恢复专用连接。 Azure Cosmos DB 专用链接服务会自动批准重新创建的专用终结点。

专用 DNS 区域集成的限制

除非使用的是专用 DNS 区域组，否则在删除专用终结点或从 Azure Cosmos DB 帐户中移除某个区域时，将不会自动移除专用 DNS 区域中的 DNS 记录。在执行以下操作之前，必须先手动删除 DNS 记录：

添加链接到此专用 DNS 区域的新专用终结点。
将新区域添加到包含已链接到此专用 DNS 区域的专用终结点的任何数据库帐户。

如果不清理 DNS 记录，可能会发生意外的数据平面问题。这些问题中的一个就是，在删除专用终结点或删除区域后添加的区域发生数据中断。

后续步骤

若要详细了解 Azure Cosmos DB 安全功能，请参阅以下文章：

若要为 Azure Cosmos DB 配置防火墙，请参阅防火墙支持。
若要了解如何为 Azure Cosmos DB 帐户配置虚拟网络服务终结点，请参阅从虚拟网络配置访问。
若要了解有关专用链接的更多信息，请参阅 Azure 专用链接文档。

通过

为 Azure Cosmos DB 帐户配置 Azure 专用链接

使用 Azure 门户创建专用终结点

API 类型和专用区域名称

提取专用 IP 地址

使用 Azure PowerShell 创建专用终结点

将专用终结点与专用 DNS 区域集成

提取专用 IP 地址

使用 Azure CLI 创建专用终结点

将专用终结点与专用 DNS 区域集成

使用资源管理器模板创建专用终结点

将专用终结点与专用 DNS 区域集成

配置自定义 DNS

将专用链接与防火墙规则结合使用

在创建帐户期间阻止公共网络访问

在不停机的情况下将专用终结点添加到现有 Azure Cosmos DB 帐户

使用直接模式时的端口范围

在添加或删除区域时更新专用终结点

当前限制

专用 DNS 区域集成的限制

后续步骤

其他资源