إدارة خدمة البحث Azure المعرفي باستخدام PowerShell
يمكنك تشغيل أوامر cmdlets والبرامج النصية ل PowerShell على Windows أو Linux أو Azure Cloud Shell لإنشاء بحث Azure المعرفي وتكوينه. تعمل الوحدة النمطية Az.Search على توسيع Azure PowerShell مع التكافؤ الكامل مع واجهات برمجة تطبيقات REST لإدارة البحث والقدرة على تنفيذ المهام التالية:
في بعض الأحيان ، يتم طرح أسئلة حول المهام غير المدرجة في القائمة أعلاه. حاليا، لا يمكنك استخدام الوحدة النمطية Az.Search أو واجهة برمجة تطبيقات REST للإدارة لتغيير اسم خادم أو منطقة أو طبقة. يتم تخصيص موارد مخصصة عند إنشاء خدمة. على هذا النحو ، يتطلب تغيير الجهاز الأساسي (الموقع أو نوع العقدة) خدمة جديدة. وبالمثل، لا توجد أدوات أو واجهات برمجة تطبيقات لنقل المحتوى، مثل فهرس، من خدمة إلى أخرى.
داخل الخدمة، يتم الإنشاء البرمجي للمحتوى من خلال واجهة برمجة تطبيقات REST لخدمة البحث أو .NET SDK. على الرغم من عدم وجود أوامر PowerShell مخصصة للمحتوى، يمكنك كتابة البرنامج النصي PowerShell الذي يستدعي واجهات برمجة تطبيقات REST أو .NET لإنشاء الفهارس وتحميلها.
التحقق من الإصدارات وتحميل الوحدات النمطية
الأمثلة الواردة في هذه المقالة تفاعلية وتتطلب أذونات مرتفعة. مطلوب PowerShell المحلي و Azure PowerShell (الوحدة النمطية Az ).
فحص إصدار PowerShell
PowerShell 7.0.6 LTS أو PowerShell 7.1.3 أو أعلى هو الإصدار الموصى به من PowerShell للاستخدام مع وحدة Azure Az PowerShell النمطية على جميع الأنظمة الأساسية. قم بتثبيت أحدث إصدار من PowerShell إذا لم يكن متوفرا لديك.
$PSVersionTable.PSVersion
Load Azure PowerShell
إذا لم تكن متأكدا مما إذا كان Az مثبتا أم لا، فقم بتشغيل الأمر التالي كخطوة تحقق.
Get-InstalledModule -Name Az
بعض الأنظمة لا تقوم بالتحميل التلقائي للوحدات. إذا تلقيت خطأ في الأمر السابق، فحاول تحميل الوحدة النمطية، وإذا فشل ذلك، فارجع إلى إرشادات تثبيت Azure PowerShell الخاصة بالتثبيت لمعرفة ما إذا كنت قد فاتتك خطوة.
Import-Module -Name Az
الاتصال إلى Azure باستخدام رمز مميز لتسجيل الدخول إلى المستعرض
يمكنك استخدام بيانات اعتماد تسجيل الدخول إلى البوابة الإلكترونية للاتصال باشتراك في PowerShell. بدلا من ذلك ، يمكنك المصادقة بشكل غير تفاعلي مع مدير الخدمة.
Connect-AzAccount
إذا كنت تمتلك اشتراكات Azure متعددة، فقم بتعيين اشتراكك في Azure. للاطلاع على قائمة باشتراكاتك الحالية، قم بتشغيل هذا الأمر.
Get-AzSubscription | sort SubscriptionName | Select SubscriptionName
لتحديد الاشتراك، قم بتشغيل الأمر التالي. في المثال التالي، يكون اسم الاشتراك هو ContosoSubscription.
Select-AzSubscription -SubscriptionName ContosoSubscription
إدراج الخدمات في اشتراك
الأوامر التالية مأخوذة من Az.Resources، وتعرض معلومات حول الموارد والخدمات الحالية التي تم توفيرها بالفعل في اشتراكك. إذا كنت لا تعرف عدد خدمات البحث التي تم إنشاؤها بالفعل، فستعرض هذه الأوامر هذه المعلومات، مما يوفر لك رحلة إلى البوابة الإلكترونية.
يقوم الأمر الأول بإرجاع كافة خدمات البحث.
Get-AzResource -ResourceType Microsoft.Search/searchServices | ft
من قائمة الخدمات، يمكنك إرجاع معلومات حول مورد معين.
Get-AzResource -ResourceName <service-name>
ينبغي أن تتشابه النتائج مع المثال التالي.
Name : my-demo-searchapp
ResourceGroupName : demo-westus
ResourceType : Microsoft.Search/searchServices
Location : westus
ResourceId : /subscriptions/<alphanumeric-subscription-ID>/resourceGroups/demo-westus/providers/Microsoft.Search/searchServices/my-demo-searchapp
استيراد Az.Search
لا تتوفر الأوامر من Az.Search حتى تقوم بتحميل الوحدة النمطية.
Install-Module -Name Az.Search
سرد كافة أوامر Az.Search
كخطوة تحقق، قم بإرجاع قائمة بالأوامر المتوفرة في الوحدة النمطية.
Get-Command -Module Az.Search
ينبغي أن تتشابه النتائج مع المثال التالي.
CommandType Name Version Source
----------- ---- ------- ------
Cmdlet Get-AzSearchAdminKeyPair 0.8.0 Az.Search
Cmdlet Get-AzSearchPrivateEndpointConnection 0.8.0 Az.Search
Cmdlet Get-AzSearchPrivateLinkResource 0.8.0 Az.Search
Cmdlet Get-AzSearchQueryKey 0.8.0 Az.Search
Cmdlet Get-AzSearchService 0.8.0 Az.Search
Cmdlet Get-AzSearchSharedPrivateLinkResource 0.8.0 Az.Search
Cmdlet New-AzSearchAdminKey 0.8.0 Az.Search
Cmdlet New-AzSearchQueryKey 0.8.0 Az.Search
Cmdlet New-AzSearchService 0.8.0 Az.Search
Cmdlet New-AzSearchSharedPrivateLinkResource 0.8.0 Az.Search
Cmdlet Remove-AzSearchPrivateEndpointConnection 0.8.0 Az.Search
Cmdlet Remove-AzSearchQueryKey 0.8.0 Az.Search
Cmdlet Remove-AzSearchService 0.8.0 Az.Search
Cmdlet Remove-AzSearchSharedPrivateLinkResource 0.8.0 Az.Search
Cmdlet Set-AzSearchPrivateEndpointConnection 0.8.0 Az.Search
Cmdlet Set-AzSearchService 0.8.0 Az.Search
Cmdlet Set-AzSearchSharedPrivateLinkResource 0.8.0 Az.Search
إذا كان لديك إصدار أقدم من الحزمة، فقم بتحديث الوحدة النمطية للحصول على أحدث الوظائف.
Update-Module -Name Az.Search
الحصول على معلومات خدمة البحث
بعد استيراد Az.Search وأنت تعرف مجموعة الموارد التي تحتوي على خدمة البحث الخاصة بك، قم بتشغيل Get-AzSearchService لإرجاع تعريف الخدمة، بما في ذلك الاسم والمنطقة والطبقة وعدد النسخ المتماثلة والأقسام. بالنسبة لهذا الأمر، قم بتوفير مجموعة الموارد التي تحتوي على خدمة البحث.
Get-AzSearchService -ResourceGroupName <resource-group-name>
ينبغي أن تتشابه النتائج مع المثال التالي.
Name : my-demo-searchapp
ResourceGroupName : demo-westus
ResourceType : Microsoft.Search/searchServices
Location : West US
Sku : Standard
ReplicaCount : 1
PartitionCount : 1
HostingMode : Default
ResourceId : /subscriptions/<alphanumeric-subscription-ID>/resourceGroups/demo-westus/providers/Microsoft.Search/searchServices/my-demo-searchapp
إنشاء خدمة أو حذفها
يتم استخدام خدمة AzSearchServiceالجديدة لإنشاء خدمة بحث جديدة.
New-AzSearchService -ResourceGroupName <resource-group-name> -Name <search-service-name> -Sku "Standard" -Location "West US" -PartitionCount 3 -ReplicaCount 3 -HostingMode Default
ينبغي أن تتشابه النتائج مع المثال التالي.
ResourceGroupName : demo-westus
Name : my-demo-searchapp
Id : /subscriptions/<alphanumeric-subscription-ID>/demo-westus/providers/Microsoft.Search/searchServices/my-demo-searchapp
Location : West US
Sku : Standard
ReplicaCount : 3
PartitionCount : 3
HostingMode : Default
Tags
إنشاء خدمة باستخدام قواعد IP
استنادا إلى متطلبات الأمان الخاصة بك، قد ترغب في إنشاء خدمة بحث مع تكوين جدار حماية IP. للقيام بذلك ، قم أولا بتحديد قواعد IP ثم تمريرها إلى المعلمة IPRuleList كما هو موضح أدناه.
$ipRules = @([pscustomobject]@{Value="55.5.63.73"},
[pscustomobject]@{Value="52.228.215.197"},
[pscustomobject]@{Value="101.37.221.205"})
New-AzSearchService -ResourceGroupName <resource-group-name> `
-Name <search-service-name> `
-Sku Standard `
-Location "West US" `
-PartitionCount 3 -ReplicaCount 3 `
-HostingMode Default `
-IPRuleList $ipRules
إنشاء خدمة باستخدام هوية مدارة معينة للنظام
في بعض الحالات، مثل عند استخدام الهوية المدارة للاتصال بمصدر بيانات، ستحتاج إلى تشغيل الهوية المدارة المعينة للنظام. يتم ذلك عن طريق الإضافة -IdentityType SystemAssigned إلى الأمر.
New-AzSearchService -ResourceGroupName <resource-group-name> `
-Name <search-service-name> `
-Sku Standard `
-Location "West US" `
-PartitionCount 3 -ReplicaCount 3 `
-HostingMode Default `
-IdentityType SystemAssigned
إنشاء خدمة باستخدام نقطة نهاية خاصة
تسمح نقاط النهاية الخاصة للبحث المعرفي في Azure للعميل على شبكة افتراضية بالوصول الآمن إلى البيانات في فهرس بحث عبر ارتباط خاص. تستخدم نقطة النهاية الخاصة عنوان IP من مساحة عنوان الشبكة الظاهرية لخدمة البحث الخاصة بك. تمر حركة مرور الشبكة بين العميل وخدمة البحث عبر الشبكة الافتراضية وارتباط خاص على شبكة Microsoft الأساسية، مما يلغي التعرض من الإنترنت العام. لمزيد من التفاصيل، راجع إنشاء نقطة نهاية خاصة للبحث المعرفي في Azure
يوضح المثال التالي كيفية إنشاء خدمة بحث باستخدام نقطة نهاية خاصة.
أولا، نشر خدمة بحث مع PublicNetworkAccess تعيين إلى Disabled.
$searchService = New-AzSearchService `
-ResourceGroupName <search-service-resource-group-name> `
-Name <search-service-name> `
-Sku Standard `
-Location "West US" `
-PartitionCount 1 -ReplicaCount 1 `
-HostingMode Default `
-PublicNetworkAccess Disabled
بعد ذلك ، قم بإنشاء شبكة افتراضية واتصال شبكة خاص ونقطة النهاية الخاصة.
# Create the subnet
$subnetConfig = New-AzVirtualNetworkSubnetConfig `
-Name <subnet-name> `
-AddressPrefix 10.1.0.0/24 `
-PrivateEndpointNetworkPolicies Disabled
# Create the virtual network
$virtualNetwork = New-AzVirtualNetwork `
-ResourceGroupName <vm-resource-group-name> `
-Location "West US" `
-Name <virtual-network-name> `
-AddressPrefix 10.1.0.0/16 `
-Subnet $subnetConfig
# Create the private network connection
$privateLinkConnection = New-AzPrivateLinkServiceConnection `
-Name <private-link-name> `
-PrivateLinkServiceId $searchService.Id `
-GroupId searchService
# Create the private endpoint
$privateEndpoint = New-AzPrivateEndpoint `
-Name <private-endpoint-name> `
-ResourceGroupName <private-endpoint-resource-group-name> `
-Location "West US" `
-Subnet $virtualNetwork.subnets[0] `
-PrivateLinkServiceConnection $privateLinkConnection
وأخيرا، قم بإنشاء منطقة DNS خاصة.
## Create private dns zone
$zone = New-AzPrivateDnsZone `
-ResourceGroupName <private-dns-resource-group-name> `
-Name "privatelink.search.windows.net"
## Create dns network link
$link = New-AzPrivateDnsVirtualNetworkLink `
-ResourceGroupName <private-dns-link-resource-group-name> `
-ZoneName "privatelink.search.windows.net" `
-Name "myLink" `
-VirtualNetworkId $virtualNetwork.Id
## Create DNS configuration
$config = New-AzPrivateDnsZoneConfig `
-Name "privatelink.search.windows.net" `
-PrivateDnsZoneId $zone.ResourceId
## Create DNS zone group
New-AzPrivateDnsZoneGroup `
-ResourceGroupName <private-dns-zone-resource-group-name> `
-PrivateEndpointName <private-endpoint-name> `
-Name 'myZoneGroup' `
-PrivateDnsZoneConfig $config
لمزيد من التفاصيل حول إنشاء نقاط نهاية خاصة في PowerShell، راجع هذا الارتباط الخاص التشغيل السريع
إدارة اتصالات نقطة النهاية الخاصة
بالإضافة إلى إنشاء اتصال نقطة نهاية خاص ، يمكنك أيضا Get، Setوالاتصال Remove .
يتم استخدام Get-AzSearchPrivateEndpointConnection لاسترداد اتصال نقطة نهاية خاص ومعرفة حالته.
Get-AzSearchPrivateEndpointConnection -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name>
يتم استخدام Set-AzSearchPrivateEndpointConnection لتحديث الاتصال. يقوم المثال التالي بتعيين اتصال نقطة نهاية خاص إلى مرفوض:
Set-AzSearchPrivateEndpointConnection -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -Name <pe-connection-name> -Status Rejected -Description "Rejected"
يتم استخدام Remove-AzSearchPrivateEndpointConnection لحذف اتصال نقطة النهاية الخاص.
Remove-AzSearchPrivateEndpointConnection -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -Name <pe-connection-name>
إعادة إنشاء مفاتيح المسؤول
يستخدم New-AzSearchAdminKey لتمرير مفاتيح واجهة برمجة تطبيقات المسؤول. يتم إنشاء مفتاحي مسؤول مع كل خدمة للوصول المصادق عليه. المفاتيح مطلوبة في كل طلب. كلا مفتاحي المسؤول متكافئان وظيفيا ، مما يمنح حق الوصول الكامل للكتابة إلى خدمة البحث مع القدرة على استرداد أي معلومات ، أو إنشاء أي كائن وحذفه. يوجد مفتاحان بحيث يمكنك استخدام أحدهما أثناء استبدال الآخر.
يمكنك فقط إعادة الإنشاء واحدا تلو الآخر، والمحدد إما كمفتاح primary أو secondary مفتاح. للحصول على خدمة دون انقطاع، تذكر تحديث كل التعليمات البرمجية للعميل لاستخدام مفتاح ثانوي أثناء التمرير فوق المفتاح الأساسي. تجنب تغيير المفاتيح أثناء سير العمليات.
كما قد تتوقع، إذا قمت بإعادة إنشاء المفاتيح دون تحديث رمز العميل، فستفشل الطلبات التي تستخدم المفتاح القديم. لا يؤدي تجديد جميع المفاتيح الجديدة إلى حظرك نهائيا من خدمتك، ولا يزال بإمكانك الوصول إلى الخدمة من خلال البوابة الإلكترونية. بعد إعادة إنشاء المفاتيح الأساسية والثانوية، يمكنك تحديث التعليمات البرمجية للعميل لاستخدام المفاتيح الجديدة وسيتم استئناف العمليات وفقا لذلك.
يتم إنشاء قيم لمفاتيح API بواسطة الخدمة. لا يمكنك توفير مفتاح مخصص للبحث المعرفي في Azure لاستخدامه. وبالمثل ، لا يوجد اسم معرف من قبل المستخدم لمفاتيح واجهة برمجة التطبيقات للمسؤول. المراجع إلى المفتاح هي سلاسل ثابتة، إما primary أو secondary.
New-AzSearchAdminKey -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -KeyKind Primary
ينبغي أن تتشابه النتائج مع المثال التالي. يتم إرجاع كلا المفتاحين على الرغم من تغيير مفتاح واحد فقط في كل مرة.
Primary Secondary
------- ---------
<alphanumeric-guid> <alphanumeric-guid>
إنشاء مفاتيح استعلام أو حذفها
يستخدم New-AzSearchQueryKey لإنشاء مفاتيح واجهة برمجة تطبيقات الاستعلام للوصول للقراءة فقط من تطبيقات العميل إلى فهرس البحث المعرفي في Azure. تستخدم مفاتيح الاستعلام للمصادقة على فهرس معين لغرض استرداد نتائج البحث. لا تمنح مفاتيح الاستعلام حق الوصول للقراءة فقط إلى العناصر الأخرى الموجودة على الخدمة، مثل فهرس أو مصدر بيانات أو مفهرس.
لا يمكنك توفير مفتاح للبحث المعرفي في Azure لاستخدامه. يتم إنشاء مفاتيح API بواسطة الخدمة.
New-AzSearchQueryKey -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -Name <query-key-name>
مقياس النسخ المتماثلة والأقسام
يستخدم Set-AzSearchServiceلزيادة أو تقليل النسخ المتماثلة والأقسام لإعادة ضبط الموارد القابلة للفوترة داخل خدمتك. تضيف زيادة النسخ المتماثلة أو الأقسام إلى فاتورتك ، التي تحتوي على رسوم ثابتة ومتغيرة. إذا كانت لديك حاجة مؤقتة إلى طاقة معالجة إضافية، فيمكنك زيادة النسخ المتماثلة والأقسام للتعامل مع عبء العمل. تحتوي منطقة المراقبة في صفحة مدخل نظرة عامة على تجانبات حول زمن انتقال الاستعلام والاستعلامات في الثانية والاختناق، مما يشير إلى ما إذا كانت السعة الحالية كافية أم لا.
قد يستغرق الأمر بعض الوقت لإضافة الموارد أو إزالتها. وتحدث تعديلات على السعة في الخلفية، مما يسمح باستمرار أعباء العمل الحالية. يتم استخدام سعة إضافية للطلبات الواردة بمجرد أن تصبح جاهزة، دون الحاجة إلى تكوين إضافي.
يمكن أن تكون إزالة السعة مدمرة. يوصى بإيقاف جميع وظائف الفهرسة والمفهرس قبل تقليل السعة لتجنب الطلبات التي تم إسقاطها. إذا لم يكن ذلك ممكنا ، فقد تفكر في تقليل السعة بشكل تدريجي ، نسخة طبق الأصل واحدة وقسم في كل مرة ، حتى يتم الوصول إلى المستويات المستهدفة الجديدة.
بمجرد إرسال الأمر ، لا توجد طريقة لإنهائه في منتصف الطريق. سيكون عليك الانتظار حتى يتم الانتهاء من الأمر قبل مراجعة العدد.
Set-AzSearchService -ResourceGroupName <search-service-resource-group-name> -Name <search-service-name> -PartitionCount 6 -ReplicaCount 6
ينبغي أن تتشابه النتائج مع المثال التالي.
ResourceGroupName : demo-westus
Name : my-demo-searchapp
Location : West US
Sku : Standard
ReplicaCount : 6
PartitionCount : 6
HostingMode : Default
Id : /subscriptions/65a1016d-0f67-45d2-b838-b8f373d6d52e/resourceGroups/demo-westus/providers/Microsoft.Search/searchServices/my-demo-searchapp
إنشاء مورد ارتباط خاص مشترك
يشار إلى نقاط النهاية الخاصة للموارد الآمنة التي يتم إنشاؤها من خلال واجهات برمجة تطبيقات البحث المعرفي في Azure باسم موارد الارتباط الخاصة المشتركة. ويرجع ذلك إلى أنك تقوم "بمشاركة" الوصول إلى مورد، مثل حساب تخزين، تم دمجه مع خدمة Azure Private Link.
إذا كنت تستخدم مفهرسا لفهرسة البيانات في Azure Cognitive Search، وكان مصدر البيانات الخاص بك على شبكة خاصة، فيمكنك إنشاء اتصال نقطة نهاية خاصة صادرة للوصول إلى البيانات.
يمكن العثور على قائمة كاملة بموارد Azure التي يمكنك إنشاء نقاط نهاية خاصة صادرة لها من Azure Cognitive Search هنا بالإضافة إلى قيم معرف المجموعة ذات الصلة.
يستخدم New-AzSearchSharedPrivateLinkResource لإنشاء مورد الارتباط الخاص المشترك. ضع في اعتبارك أنه قد تكون هناك حاجة إلى بعض التكوين لمصدر البيانات قبل تشغيل هذا الأمر.
New-AzSearchSharedPrivateLinkResource -ResourceGroupName <search-serviceresource-group-name> -ServiceName <search-service-name> -Name <spl-name> -PrivateLinkResourceId /subscriptions/<alphanumeric-subscription-ID>/resourceGroups/<storage-resource-group-name>/providers/Microsoft.Storage/storageAccounts/myBlobStorage -GroupId <group-id> -RequestMessage "Please approve"
يتيح لك Get-AzSearchSharedPrivateLinkResource استرداد موارد الروابط الخاصة المشتركة وعرض حالتها.
Get-AzSearchSharedPrivateLinkResource -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -Name <spl-name>
ستحتاج إلى الموافقة على الاتصال باستخدام الأمر التالي قبل استخدامه.
Approve-AzPrivateEndpointConnection `
-Name <spl-name> `
-ServiceName <search-service-name> `
-ResourceGroupName <search-service-resource-group-name> `
-Description = "Approved"
إزالة-AzSearchSharedPrivateLinkResource يستخدم لحذف مورد الارتباط الخاص المشترك.
$job = Remove-AzSearchSharedPrivateLinkResource -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -Name <spl-name> -Force -AsJob
$job | Get-Job
للحصول على التفاصيل الكاملة حول إعداد موارد الارتباط الخاص المشتركة، راجع الوثائق الخاصة بإجراء اتصالات المفهرس من خلال نقطة نهاية خاصة.
الخطوات التالية
إنشاء فهرس أو الاستعلام عن فهرس باستخدام البوابة الإلكترونية أو واجهات برمجة تطبيقات REST أو .NET SDK.