تكوين Azure Private Link لحساب Azure Cosmos DB

مقالة
04/24/2023

ينطبق على: NoSQL MongoDB كاساندرا العفريت الجدول

باستخدام Azure Private Link، يمكنك الاتصال بحساب Azure Cosmos DB من خلال نقطة نهاية خاصة. إن نقطة النهاية الخاصة عبارة عن مجموعة من عناوين IP الخاصة في شبكة فرعية داخل شبكتك الظاهرية. يمكنك بعد ذلك تقييد الوصول إلى حساب Azure Cosmos DB عبر عناوين IP الخاصة. عند دمج الارتباط الخاص مع نهج NSG التقييدية، فإنه يساعد على تقليل مخاطر النقل غير المصرح للبيانات. لمعرفة المزيد حول نقاط النهاية الخاصة، راجع ما هو Azure Private Link؟

ملاحظة

لا يمنع الارتباط الخاص نقاط نهاية Azure Cosmos DB من الحل بواسطة DNS العام. تتم تصفية الطلبات الواردة على مستوى التطبيق، وليس على مستوى النقل أو الشبكة.

يسمح الارتباط الخاص للمستخدمين بالوصول إلى حساب Azure Cosmos DB من داخل الشبكة الظاهرية أو من أي شبكة ظاهرية نظيرة. يمكن أيضًا الوصول إلى الموارد المعينة للرابط الخاص داخليًا عبر التناظر الخاص عبر شبكة ظاهرية خاصة أو Azure ExpressRoute.

يمكنك الاتصال بحساب Azure Cosmos DB الذي تم تكوينه باستخدام Private Link باستخدام طريقة الموافقة التلقائية أو اليدوية. لمعرفة المزيد، راجع قسم سير عمل الموافقة في وثائق الارتباط الخاص.

توضح هذه المقالة كيفية إعداد نقاط النهاية الخاصة لمخزن معاملات Azure Cosmos DB. يفترض أنك تستخدم أسلوب الموافقة التلقائية. إذا كنت تستخدم المخزن التحليلي، فشاهد تكوين نقاط النهاية الخاصة للمخزن التحليلي.

إنشاء نقطة نهاية خاصة باستخدام مدخل Azure

اتبع هذه الخطوات لإنشاء نقطة نهاية خاصة لحساب Azure Cosmos DB موجود باستخدام مدخل Microsoft Azure:

سجل الدخول إلى مدخل Microsoft Azure، ثم حدد حساب Azure Cosmos DB.
حدد Networking من قائمة الإعدادات، ثم حدد + Private endpoint ضمن علامة التبويب Private access :

في جزء Create a private endpoint من Basics، أدخِل أو حدّد التفاصيل التالية:

الإعداد	القيمة
تفاصيل المشروع
الاشتراك	حدد اشتراكك.
مجموعة الموارد	حدد مجموعة موارد.
تفاصيل المثيل
الاسم	أدخل أي اسم لنقطة النهاية الخاصة. إذا كان هذا الاسم مستخدماً من قبل، فأنشئ اسماً جديداً.
المنطقة	حدد المنطقة التي تريد توزيع Private Link فيها. قم بإنشاء نقطة النهاية الخاصة في نفس الموقع الذي توجد به شبكتك الظاهرية.

حدد Next: Resource.

في جزء Create a private endpoint - Resource ، أدخل هذه المعلومات أو حددها:

إعداد	القيمة
طريقة التوصيل	حدد الاتصال بمورد Azure في دليلي. يمكنك بعد ذلك اختيار أحد مواردك لإعداد Private Link. أو يمكنك الاتصال بمورد شخص آخر باستخدام معرّف مورد أو اسم مستعار شاركه معك.
الاشتراك	حدد اشتراكك.
نوع المورد	حدد Microsoft.AzureCosmosDB/databaseAccounts.
المورد	حدد حساب "Azure Cosmos DB" الخاص بك.
هدف المورد الفرعي	حدد نوع واجهة برمجة التطبيقات الخاصة بـ Azure Cosmos DB الذي تريد تعيينه. هذا افتراضيا إلى خيار واحد فقط لواجهات برمجة التطبيقات ل SQL وMongoDB وCassandra. بالنسبة لواجهات برمجة التطبيقات ل Gremlin وTable، يمكنك أيضا اختيار NoSQL لأن واجهات برمجة التطبيقات هذه قابلة للتشغيل التفاعلي مع واجهة برمجة التطبيقات ل NoSQL. إذا كان لديك بوابة مخصصة تم توفيرها لحساب API ل NoSQL، فسترى أيضا خيارا ل SqlDedicated.

حدد Next: Virtual Network.
في جزء إنشاء نقطة نهاية خاصة - الشبكة الظاهرية ، أدخل هذه المعلومات أو حددها:

إعداد القيمة

شبكة ظاهرية حدد شبكتك الظاهرية.

الشبكة الفرعية حدد شبكتك الفرعية.
حدد Next: DNS.

إعداد	القيمة
شبكة ظاهرية	حدد شبكتك الظاهرية.
الشبكة الفرعية	حدد شبكتك الفرعية.

في جزء إنشاء نقطة نهاية خاصة - DNS ، أدخل هذه المعلومات أو حددها:

إعداد	القيمة
التكامل مع منطقة DNS الخاصة	حدد Yes. للاتصال بشكل خاص بنقطة النهاية الخاصة بك، فأنت بحاجة إلى سجل DNS. نوصي بدمج نقطة النهاية الخاصة بك مع منطقة DNS خاصة. يمكنك أيضاً استخدام خوادم DNS الخاصة بك أو إنشاء سجلات DNS باستخدام ملفات المضيف الموجودة على أجهزتك الظاهرية. عند تحديد "نعم" لهذا الخيار، يتم أيضاً إنشاء مجموعة منطقة DNS خاصة. تمثل مجموعة منطقة DNS ارتباطاً بين منطقة DNS الخاصة ونقطة النهاية الخاصة. يساعدك هذا الارتباط على التحديث التلقائي لمنطقة DNS الخاصة عند وجود تحديث لنقطة النهاية الخاصة. على سبيل المثال، عند إضافة أو إزالة المناطق، يتم تحديث منطقة DNS الخاصة تلقائياً.
اسم التهيئة	حدد الاشتراك ومجموعة الموارد. يتم تحديد منطقة DNS الخاصة تلقائياً. ولا يمكنك تغييرها باستخدام مدخل Azure.

إعداد

القيمة

التكامل مع منطقة DNS الخاصة

حدد Yes.

للاتصال بشكل خاص بنقطة النهاية الخاصة بك، فأنت بحاجة إلى سجل DNS. نوصي بدمج نقطة النهاية الخاصة بك مع منطقة DNS خاصة. يمكنك أيضاً استخدام خوادم DNS الخاصة بك أو إنشاء سجلات DNS باستخدام ملفات المضيف الموجودة على أجهزتك الظاهرية.

عند تحديد "نعم" لهذا الخيار، يتم أيضاً إنشاء مجموعة منطقة DNS خاصة. تمثل مجموعة منطقة DNS ارتباطاً بين منطقة DNS الخاصة ونقطة النهاية الخاصة. يساعدك هذا الارتباط على التحديث التلقائي لمنطقة DNS الخاصة عند وجود تحديث لنقطة النهاية الخاصة. على سبيل المثال، عند إضافة أو إزالة المناطق، يتم تحديث منطقة DNS الخاصة تلقائياً.

اسم التهيئة

حدد الاشتراك ومجموعة الموارد.

يتم تحديد منطقة DNS الخاصة تلقائياً. ولا يمكنك تغييرها باستخدام مدخل Azure.

حدد Next: Tags>Review + create. في صفحة Review + create، يتحقق Azure من صحة التكوين الخاص بك.
عندما ترى رسالة Validation passed، حدد Create.

عندما يكون لديك ارتباط خاص معتمد لحساب Azure Cosmos DB، في مدخل Microsoft Azure، لا يتوفر خيار جميع الشبكات في جزء جدار الحماية والشبكات الظاهرية .

أنواع واجهة برمجة التطبيقات (API) وأسماء المناطق الخاصة

يرجى مراجعة تكوين Azure Private Endpoint DNS للحصول على شرح أكثر تفصيلا حول المناطق الخاصة وتكوينات DNS لنقطة النهاية الخاصة. يعرض الجدول التالي التعيين بين أنواع مختلفة من واجهة برمجة تطبيقات حساب Azure Cosmos DB، والمصدر الفرعي المدعوم، وأسماء المناطق الخاصة المقابلة. يمكنك أيضا الوصول إلى Gremlin وواجهة برمجة التطبيقات لحسابات الجدول من خلال واجهة برمجة التطبيقات ل NoSQL، لذلك هناك إدخالان لواجهات برمجة التطبيقات هذه. هناك أيضا إدخال إضافي لواجهة برمجة التطبيقات ل NoSQL للحسابات التي تستخدم البوابة المخصصة.

نوع واجهة برمجة تطبيقات حساب Azure Cosmos DB	الموارد الفرعية المدعومة أو معرفات المجموعة	اسم المنطقة الخاصة
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
الجدول	الجدول	privatelink.table.cosmos.azure.com
الجدول	Sql	privatelink.documents.azure.com

إحضار عناوين IP الخاصة

بعد توفير نقطة النهاية الخاصة، يمكنك الاستعلام عن عناوين IP. لعرض عناوين IP من مدخل Azure:

ابحث عن نقطة النهاية الخاصة التي قمت بإنشائها مسبقاً. في هذه الحالة، ستكون cdbPrivateEndpoint3.
حدد علامة التبويب Overview لمشاهدة إعدادات DNS وعناوين IP.

لقطة شاشة لعناوين IP الخاصة في مدخل Microsoft Azure

يتم إنشاء عناوين IP متعددة لكل نقطة نهاية خاصة:

واحد لنقطة النهاية العالمية غير المحدودة للمنطقة لحساب Azure Cosmos DB.
واحد لكل منطقة يتم فيها نشر حساب Azure Cosmos DB.

إنشاء نقطة نهاية خاصة باستخدام Azure PowerShell

قم بتشغيل البرنامج النصي PowerShell التالي لإنشاء نقطة نهاية خاصة تسمى MyPrivateEndpoint لحساب Azure Cosmos DB موجود. بعد ذلك، استبدل القيم المتغيرة بتفاصيل البيئة الخاصة بك.

$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 خاصة

بعد إنشاء نقطة النهاية الخاصة، يمكنك دمجها مع منطقة DNS خاصة باستخدام نص PowerShell التالي:

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 الخاصة

بعد توفير نقطة النهاية الخاصة، يمكنك الاستعلام عن عناوين IP وتعيين اسم المجال المؤهل بالكامل (FQDN) باستخدام نص PowerShell التالي:

$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 التالي لإنشاء نقطة نهاية خاصة تسمى myPrivateEndpoint لحساب Azure Cosmos DB موجود. بعد ذلك، استبدل القيم المتغيرة بتفاصيل البيئة الخاصة بك.

# 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 خاصة

بعد إنشاء نقطة النهاية الخاصة، يمكنك دمجها مع منطقة DNS خاصة باستخدام نص Azure CLI التالي:

#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.

استخدم التعليمات البرمجية التالية لإنشاء قالب Resource Manager يسمى PrivateEndpoint_template.json. ينشئ هذا القالب نقطة نهاية خاصة لواجهة برمجة تطبيقات Azure Cosmos DB vAPI موجودة لحساب 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 من خلال واجهات برمجة تطبيقات متعددة. على سبيل المثال:

تحتوي واجهة برمجة التطبيقات لحسابات NoSQL على خيار إضافي للحسابات التي تم تكوينها لاستخدام البوابة المخصصة.
يمكن الوصول إلى واجهة برمجة التطبيقات لحسابات Gremlin من كل من Gremlin وواجهة برمجة التطبيقات لحسابات NoSQL.
يمكن الوصول إلى واجهة برمجة التطبيقات لحسابات الجدول من كل من Table وواجهة برمجة التطبيقات لحسابات NoSQL.

بالنسبة لهذه الحسابات، يجب عليك إنشاء نقطة نهاية خاصة واحدة لكل نوع من أنواع واجهات برمجة التطبيقات (API). إذا كنت تقوم بإنشاء نقطة نهاية خاصة ل SqlDedicated، فأنت بحاجة فقط إلى إضافة نقطة نهاية ثانية إذا Sql كنت تريد أيضا الاتصال بحسابك باستخدام البوابة القياسية. يتم تحديد نوع واجهة برمجة التطبيقات (API) المطابقة في مصفوفة GroupId.

بعد توزيع القالب بنجاح، ستظهر لك مخرجات مشابهة لما تعرضه الصورة التالية. إن قيمة provisioningState تكون Succeeded إذا تم إعداد نقاط النهاية الخاصة بشكل صحيح.

لقطة شاشة لإخراج التوزيع لقالب Resource Manager.

بعد توزيع القالب، يتم حجز عناوين IP الخاصة داخل الشبكة الفرعية. يتم تكوين قاعدة جدار الحماية لحساب Azure Cosmos DB لقبول الاتصالات من نقطة النهاية الخاصة فقط.

ثم ادمج نقطة النهاية الخاصة مع منطقة DNS خاصة

استخدم التعليمات البرمجية التالية لإنشاء قالب Resource Manager يسمى PrivateZone_template.json. ينشئ هذا القالب منطقة DNS خاصة لواجهة برمجة تطبيقات Azure Cosmos DB الحالية لحساب NoSQL في شبكة ظاهرية موجودة.

{
    "$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": ""
        }
    }
}

استخدم التعليمات البرمجية التالية لإنشاء قالب Resource Manager يسمى PrivateZoneGroup_template.json. ينشئ هذا القالب مجموعة منطقة DNS خاصة لواجهة برمجة تطبيقات Azure Cosmos DB الحالية لحساب NoSQL في شبكة ظاهرية موجودة.

{
    "$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

### 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 في الاستجابة الموضحة سابقا.

عندما تقوم بإنشاء نقطة النهاية الخاصة، يمكنك دمجها مع منطقة DNS خاصة في Azure. إذا اخترت بدلاً من ذلك استخدام منطقة DNS مخصصة، فيجب عليك تكوينها لإضافة سجلات DNS لجميع عناوين IP الخاصة المحجوزة لنقطة النهاية الخاصة.

هام

إن دقة 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 موجود بدون وقت تعطل

بشكل افتراضي، تؤدي إضافة نقطة نهاية خاصة إلى حساب موجود إلى توقف قصير لمدة خمس دقائق تقريبا. اتبع هذه الإرشادات لتجنب وقت التعطل هذا:

أضف عنوان IP أو قواعد الشبكة الظاهرية إلى تكوين جدار الحماية الخاص بك للسماح باتصالات العميل صراحةَ.
انتظر لمدة 10 دقائق للتأكد من أنه تم تطبيق تحديث التكوين.
قم بتكوين نقطة النهاية الخاصة الجديدة الخاصة بك.
قم بإزالة قواعد جدار الحماية المعينة في الخطوة 1.

ملاحظة

إذا كان لديك تطبيقات قيد التشغيل باستخدام Azure Cosmos DB SDKs، فقد تكون هناك مهلات عابرة أثناء تحديث التكوين. تأكد من أن تطبيقك مصمم ليكون مرنا في مواجهة حالات فشل الاتصال العابرة وأن يكون منطق إعادة المحاولة في مكانه في حالة الحاجة إليه.

نطاق المنفذ عند استخدام الوضع المباشر

عند استخدام Private Link مع حساب 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 المخصص الخاص بك.

القيود الحالية

تنطبق القيود التالية عند استخدام Private Link مع حساب Azure Cosmos DB:

لا يمكنك الحصول على أكثر من 200 نقطة نهاية خاصة على حساب Azure Cosmos DB واحد.
عند استخدام Private Link مع حساب Azure Cosmos DB من خلال اتصال الوضع المباشر، يمكنك استخدام بروتوكول TCP فقط. بروتوكول HTTP غير مدعوم حاليا.
عند استخدام واجهة برمجة تطبيقات Azure Cosmos DB لحساب MongoDB، يتم دعم نقطة نهاية خاصة للحسابات على إصدار الخادم 3.6 أو أعلى (أي الحسابات التي تستخدم نقطة النهاية بالتنسيق *.mongo.cosmos.azure.com). الارتباط الخاص غير مدعوم للحسابات على إصدار الخادم 3.2 (أي الحسابات التي تستخدم نقطة النهاية بالتنسيق *.documents.azure.com). لاستخدام Private Link، يجب عليك ترحيل الحسابات القديمة إلى الإصدار الجديد.
عند استخدام واجهة برمجة تطبيقات Azure Cosmos DB لحساب MongoDB يحتوي على ارتباط خاص، يجب أن تدعم الأدوات والمكتبات تعريف اسم الخدمة (SNI) أو تمرر المعلمة appName من سلسلة الاتصال للاتصال بشكل صحيح. قد لا تكون بعض الأدوات والمكتبات القديمة متوافقة مع ميزة الارتباط الخاص.
يجب منح مسؤول الشبكة الإذن على الأقل Microsoft.DocumentDB/databaseAccounts/PrivateEndpointConnectionsApproval/action في نطاق حساب Azure Cosmos DB لإنشاء نقاط نهاية خاصة معتمدة تلقائيا.
لا يمكنك حالياً الموافقة على اتصال نقطة نهاية خاصة مرفوض. بدلاً من ذلك، أعد إنشاء نقطة نهاية خاصة لاستئناف الاتصال الخاص. توافق خدمة الارتباط الخاص ل Azure Cosmos DB تلقائيا على نقطة النهاية الخاصة التي أعيد إنشاؤها.

قيود على تكامل منطقة DNS الخاصة

ما لم تكن تستخدم مجموعة منطقة DNS خاصة، فلن تتم إزالة سجلات DNS في منطقة DNS الخاصة تلقائيا عند حذف نقطة نهاية خاصة أو إزالة منطقة من حساب Azure Cosmos DB. يجب عليك إزالة سجلات DNS يدوياً قبل:

إضافة نقطة نهاية خاصة جديدة مرتبطة بمنطقة DNS الخاصة هذه.
إضافة منطقة جديدة إلى أي حساب قاعدة بيانات له نقاط نهاية خاصة مرتبطة بمنطقة DNS الخاصة هذه.

إذا لم تقم بتنظيف سجلات DNS، فقد تحدث مشكلات غير متوقعة في مستوى البيانات. تتضمن هذه المشكلات انقطاع البيانات في المناطق المضافة بعد إزالة نقطة النهاية الخاصة أو إزالة المنطقة.

الخطوات التالية

لمعرفة المزيد حول ميزات أمان Azure Cosmos DB، راجع المقالات التالية:

لتكوين جدار حماية لـ Azure Cosmos DB، راجع دعم جدار الحماية.
لمعرفة كيفية تكوين نقطة نهاية خدمة شبكة ظاهرية لحساب Azure Cosmos DB الخاص بك، راجع تكوين الوصول من الشبكات الظاهرية.
لمعرفة المزيد حول Private Link، راجع وثائق Azure Private Link.

تكوين Azure Private Link لحساب Azure Cosmos DB

إنشاء نقطة نهاية خاصة باستخدام مدخل Azure

أنواع واجهة برمجة التطبيقات (API) وأسماء المناطق الخاصة

إحضار عناوين IP الخاصة

إنشاء نقطة نهاية خاصة باستخدام Azure PowerShell

ثم ادمج نقطة النهاية الخاصة مع منطقة DNS خاصة

إحضار عناوين IP الخاصة

إنشاء نقطة نهاية خاصة باستخدام Azure CLI

ثم ادمج نقطة النهاية الخاصة مع منطقة DNS خاصة

إنشاء نقطة نهاية خاصة باستخدام قالب Resource Manager

ثم ادمج نقطة النهاية الخاصة مع منطقة DNS خاصة

تكوين نظام أسماء نطاقات (DNS) مخصص

اقتران Private Link مع قواعد جدار الحماية

حظر الوصول إلى الشبكة العامة أثناء إنشاء الحساب

إضافة نقاط نهاية خاصة إلى حساب Azure Cosmos DB موجود بدون وقت تعطل

نطاق المنفذ عند استخدام الوضع المباشر

تحديث نقطة نهاية خاصة عند إضافة منطقة أو إزالتها

القيود الحالية

قيود على تكامل منطقة DNS الخاصة

الخطوات التالية

الموارد الإضافية