設定 Azure Cosmos DB 帳戶的 Azure Private Link

發行項
03/20/2024

適用於：NoSQL MongoDB Cassandra Gremlin Table

藉由使用 Azure Private Link，您就可以透過私人端點連線到 Azure Cosmos DB 帳戶。私人端點是虛擬網路內子網路中的一組私人 IP 位址。您可接著限制透過私人 IP 位址對 Azure Cosmos DB 帳戶進行存取。 Private Link 與限制性 NSG 原則結合時，有助於降低資料外流的風險。若要深入了解私人端點，請參閱 Azure Private Link 是什麼？。

注意

Private Link 不會防止公用 DNS 解析您的 Azure Cosmos DB 端點。篩選傳入要求發生在應用程式層級，而不是發生在傳輸或網路層級。

Private Link 可讓使用者從虛擬網路內或從任何對等互連的虛擬網路存取 Azure Cosmos DB 帳戶。對應至 Private Link 的資源也是私人對等互連上可透過 VPN 或 Azure ExpressRoute 存取的內部部署。

您可使用自動或手動核准方法來連線到設定 Private Link 的 Azure Cosmos DB 帳戶。若要深入了解，請參閱 Private Link 文件的核准工作流程一節。

本文描述如何設定 Azure Cosmos DB 交易式存放區的私人端點。其假設您使用自動核准方法。如果您使用的是分析存放區，請參閱為分析存放區設定私人端點。

使用 Azure 入口網站建立私人端點

依照下列步驟，使用 Azure 入口網站為現有 Azure Cosmos DB 帳戶建立私人端點：

登入 Azure 入口網站，然後選取 Azure Cosmos DB 帳戶。
從設定清單中選取 [網路]，然後在 [私人存取] 索引標籤底下選取 [+ 私人端點]：

在 [建立私人端點 - 基本] 窗格中，輸入或選取下列詳細資料：

設定	值
專案詳細資料
訂用帳戶	選取您的訂用帳戶。
資源群組	選取資源群組。
[執行個體詳細資料]
名稱	為私人端點輸入任何名稱。如果此名稱已被使用，請建立不重複的名稱。
區域	選取要部署 Private Link 的區域。在虛擬網路所在的相同位置中建立私人端點。

選取 [下一步：資源]。

在 [建立私人端點 - 資源] 窗格中，輸入或選取下列資訊：

設定	值
連線方式	選取 [連線到我目錄中的 Azure 資源]。然後，您可選擇其中一個資源來設定 Private Link。或者，您可使用其他人與您共用的資源識別碼或別名來連線到其資源。
訂用帳戶	選取您的訂用帳戶。
資源類型	選取 Microsoft.AzureCosmosDB/databaseAccounts。
資源	選取 Azure Cosmos DB 帳戶。
目標子資源	選取想要對應的 Azure Cosmos DB API 類型。這會預設為 API for SQL、API for MongoDB 和 API for Cassandra 只有一個選項。針對 API for Gremlin 和 API for Table，您還可選擇 NoSQL，因為這些 API 可與 API for NoSQL 互通。如果您已為 API for NoSQL 帳戶佈建專用網路閘道，也會看到適用於 SqlDedicated 的選項。

選取 [下一步：虛擬網路]。
在 [建立私人端點 - 虛擬網路] 窗格中，輸入或選取下列資訊：

設定值

虛擬網路選取您的虛擬網路。

子網路選取子網路。
選取 [下一步：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 帳戶具有已核准的 Private Link，在 Azure 入口網站中，[防火牆和虛擬網路] 窗格中的 [所有網路] 選項將無法使用。

API 類型和私人區域名稱

如需私人端點的私人區域和 DNS 設定的詳細說明，請檢閱 Azure 私人端點 DNS 設定。下表顯示不同的 Azure Cosmos DB 帳戶 API 類型、支援的子資源以及相對應私人區域名稱之間的對應。您也可以透過 API for NoSQL 來存取 Gremlin 和 API for Table 帳戶，因此這些 API 有兩個項目。另有一個適用於使用專用網路閘道之帳戶的 API for NoSQL 額外項目。

Azure Cosmos DB 帳戶 API 類型	支援的子資源或群組 ID	私人區域名稱
NoSQL	Sql	privatelink.documents.azure.com
NoSQL	SqlDedicated	privatelink.sqlx.cosmos.azure.com
Cassandra	Cassandra	privatelink.cassandra.cosmos.azure.com
Mongo	MongoDB	privatelink.mongo.cosmos.azure.com
Gremlin	Gremlin	privatelink.gremlin.cosmos.azure.com
Gremlin	Sql	privatelink.documents.azure.com
Table	Table	privatelink.table.cosmos.azure.com
Table	Sql	privatelink.documents.azure.com

擷取私人 IP 位址

佈建私人端點之後，即可查詢 IP 位址。若要從 Azure 入口網站檢視 IP 位址：

搜尋稍早建立的私人端點。在本案例中，這是 cdbPrivateEndpoint3。
選取 [概觀] 索引標籤，以查看 DNS 設定和 IP 位址。

Screenshot of private IP addresses in the Azure portal

為每個私人端點建立多個 IP 位址：

為 Azure Cosmos DB 帳戶的全域 (不限區域) 端點建立一個 IP 位址。
為部署 Azure Cosmos DB 帳戶的每個區域各建立一個 IP 位址。

使用 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, SqlDedicated, 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 = "westcentralus"

$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.com"
$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, SqlDedicated, 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.com"

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"

使用 Resource Manager 範本建立私人端點

您可在虛擬網路子網路中建立私人端點來設定 Private Link。您可使用 Azure Resource Manager 範本來達到這個目的。

使用下列程式碼，建立名為 PrivateEndpoint_template.json 的 Resource Manager 範本。此範本會針對現有虛擬網路中的現有 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 指令碼。執行指令碼之前，將訂用帳戶識別碼、資源群組名稱及其他變數值取代為環境的詳細資料。

### 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", "SqlDedicated", "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.
Login-AzAccount
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、SqlDedicated、MongoDB、Cassandra、Gremlin 和 Table。某些 Azure Cosmos DB 帳戶類型可透過多個 API 存取。例如：

API for NoSQL 帳戶為設定為使用專用網路閘道的帳戶新增了一個選項。
您可從 Gremlin 帳戶和 API for NoSQL 帳戶存取 API for Gremlin 帳戶。
您可從 Table 和 API for NoSQL 帳戶存取 API for Table 帳戶。

針對這些帳戶，您必須為每個 API 類型建立一個私人端點。若要為 SqlDedicated 建立私人端點，則只有在也想使用標準網路閘道連線到您的帳戶時，才需要為 Sql 新增第二個端點。對應的 API 類型是在 GroupId 陣列中指定。

成功部署範本之後，您可看到類似下圖所示的輸出。如果正確設定私人端點，則 provisioningState 值會是 Succeeded。

Screenshot of deployment output for the Resource Manager template.

部署範本之後，即會在子網路內保留私人 IP 位址。 Azure Cosmos DB 帳戶其防火牆規則已設定為只接受來自私人端點的連線。

將私人端點與私人 DNS 區域整合

使用下列程式碼，建立名為 PrivateZone_template.json 的 Resource Manager 範本。此範本會為現有虛擬網路中的現有 Azure Cosmos DB API for NoSQL 帳戶建立私人 DNS 區域。

{
    "$schema": "http://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 的 Resource Manager 範本。此範本會為現有虛擬網路中的現有 Azure Cosmos DB API for NoSQL 帳戶建立私人 DNS 區域群組。

{
    "$schema": "http://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 指令碼。執行指令碼之前，將訂用帳戶識別碼、資源群組名稱及其他變數值取代為環境的詳細資料。

### 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", "SqlDedicated", "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.com"
# 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
Login-AzAccount 
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 位址。

Private Link 搭配防火牆規則

當搭配防火牆規則使用 Private Link 時，可能會發生下列情況和結果：

如果您未設定任何防火牆規則，則根據預設，所有流量都可存取 Azure Cosmos DB 帳戶。
如果您設定公用流量或服務端點並建立私人端點，則不同類型之傳入流量會由對應類型的防火牆規則所授權。如果私人端點是在同時設定了服務端點的子網路中進行設定的：
- 私人端點所對應資料庫帳戶的流量會透過私人端點路由傳送，
- 從子網流到其他資料庫帳戶的流量會透過服務端點路由傳送。
如果未設定任何公用流量或服務端點並建立私人端點，則只能透過私人端點來存取 Azure Cosmos DB 帳戶。如果未設定公用流量或服務端點，則在拒絕或刪除所有已核准的私人端點之後，就會對整個網路開放該帳戶，除非將 PublicNetworkAccess 設定為 [已停用]。

在帳戶建立期間封鎖公用網路存取

如上一節所述，除非已設定特定防火牆規則，否則新增私人端點會使 Azure Cosmos DB 帳戶只能透過私人端點存取。這表示在建立 Azure Cosmos DB 帳戶之後到新增私人端點之前，都可透過公用流量存取該帳戶。為確保在建立私人端點之前已停用公用網路存取，您可在帳戶建立期間將 publicNetworkAccess 旗標設定為 [已停用]。請注意，此旗標的優先順序高於任何 IP 或虛擬網路規則。在將此旗標設定為 [已停用] 時，即使防火牆設定中允許來源 IP 或虛擬網絡，仍會封鎖所有公用和虛擬網路流量。

如需如何使用此旗標的範例，請參閱此 Azure Resource Manager 範本。

將私人端點新增至現有的 Azure Cosmos DB 帳戶，沒有發生停機的情況

預設將私人端點新增至現有帳戶會導致大約 5 分鐘的短暫停機。請依照以下指示操作，以避免此停機時間：

將 IP 或虛擬網路規則新增至您的防火牆設定，以明確地允許您的用戶端連線。
等候 10 分鐘，以確定套用了設定更新。
設定新的私人端點。
移除步驟 1 中設定的防火牆規則。

注意

如果您正在使用 Azure Cosmos DB SDK 執行應用程序，則在設定更新期間可能會出現暫時性逾時。請確定您的應用程式設計為能夠復原暫時性連線失敗，並在需要時具備重試邏輯。

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

透過直接模式連線搭配 Azure Cosmos DB 帳戶使用 Private Link 時，您必須確定已開放 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 帳戶使用 Private Link 時，適用下列限制：

您不能在單一 Azure Cosmos DB 帳戶上具有超過 200 個私人端點。
透過直接模式連線搭配 Azure Cosmos DB 帳戶使用 Private Link 時，您只能使用 TCP 通訊協定。目前不支援 HTTP 通訊協定。
將 Azure Cosmos DB 的 API 用於 MongoDB 帳戶時，伺服器 3.6 版或更新版本上的帳戶 (即使用 *.mongo.cosmos.azure.com 格式端點的帳戶) 支援私人端點。伺服器 3.2 版上的帳戶 (即使用 *.documents.azure.com 格式端點的帳戶) 不支援 Private Link。若要使用 Private Link，您應該將舊版帳戶移轉到新版本。
將 Azure Cosmos DB 的 API 用於具有 Private Link 的 MongoDB 帳戶時，工具和程式庫必須支援服務名稱識別 (SNI) 或從連接字串傳遞 appName 參數才能正確連線。某些較舊的工具和連結庫可能無法與 Private Link 功能相容。
網路系統管理員至少應被授與 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 帳戶的虛擬網路服務端點，請參閱設定從虛擬網路存取。
若要深入了解 Private Link，請參閱 Azure Private Link 文件。

設定 Azure Cosmos DB 帳戶的 Azure Private Link

使用 Azure 入口網站建立私人端點

API 類型和私人區域名稱

擷取私人 IP 位址

使用 Azure PowerShell 建立私人端點

將私人端點與私人 DNS 區域整合

擷取私人 IP 位址

使用 Azure CLI 建立私人端點

將私人端點與私人 DNS 區域整合

使用 Resource Manager 範本建立私人端點

將私人端點與私人 DNS 區域整合

設定自訂 DNS

Private Link 搭配防火牆規則

在帳戶建立期間封鎖公用網路存取

將私人端點新增至現有的 Azure Cosmos DB 帳戶，沒有發生停機的情況

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

新增或移除區域時更新私人端點

目前的限制

私人 DNS 區域整合的限制

下一步

其他資源