PowerShell ile Azure AI Arama hizmeti yönetme
Azure AI Search oluşturmak ve yapılandırmak için PowerShell cmdlet'lerini ve betiklerini Windows, Linux veya Azure Cloud Shell'de çalıştırabilirsiniz.
Aşağıdaki görevleri gerçekleştirmek için Az.Search modülünü kullanın:
- Abonelikteki arama hizmetlerini listeleme
- İade hizmeti bilgileri
- Hizmet oluşturma veya silme
- Özel uç nokta ile hizmet oluşturma
- Yönetici API anahtarlarını yeniden oluşturma
- Sorgu api anahtarlarını oluşturma veya silme
- Çoğaltmalar ve bölümler ile ölçeği artırma veya azaltma
- Paylaşılan özel bağlantı kaynağı oluşturma
Bazen, yukarıdaki listede bulunmayan görevler hakkında sorular sorulur.
Sunucu adını, bölgesini veya katmanını program aracılığıyla veya portalda değiştiremezsiniz. Ayrılmış kaynaklar hizmet oluşturulduğunda ayrılır. Bu nedenle, temel alınan donanımın (konum veya düğüm türü) değiştirilmesi yeni bir hizmet gerektirir.
Dizin gibi içerikleri bir hizmetten diğerine aktarmak için araçları veya API'leri kullanamazsınız. Bir hizmet içinde program aracılığıyla içerik oluşturma işlemi, Arama Hizmeti REST API'sini veya .NET için Azure SDK gibi bir SDK'yı kullanır. İçerik geçişi için ayrılmış komut olmasa da, yeni bir hizmete dizinler oluşturmak ve yüklemek için REST API'yi veya istemci kitaplığını çağıran betik yazabilirsiniz.
Önizleme yönetimi özellikleri genellikle Az.Search modülünde kullanılamaz. Önizleme özelliğini kullanmak istiyorsanız Yönetim REST API'sini ve önizleme API'sinin sürümünü kullanın.
Az.Search modülü, Azure PowerShell'i tam eşlikle Arama Yönetimi REST API'lerinin kararlı sürümlerine genişletir.
Sürümleri denetleme ve modülleri yükleme
Bu makaledeki örnekler etkileşimlidir ve yükseltilmiş izinler gerektirir. Yerel PowerShell ve Azure PowerShell ( Az modülü) gereklidir.
PowerShell sürüm denetimi
Sahip değilseniz PowerShell'in en son sürümünü yükleyin.
$PSVersionTable.PSVersion
Azure PowerShell'i yükleme
Az'nin yüklü olup olmadığından emin değilseniz doğrulama adımı olarak aşağıdaki komutu çalıştırın.
Get-InstalledModule -Name Az
Bazı sistemler modülleri otomatik olarak yüklemez. Önceki komutta hata aldıysanız modülü yüklemeyi deneyin ve bu başarısız olursa, bir adımı atlayıp kaçırmadığınıza bakmak için Azure PowerShell yükleme yönergelerine geri dönün.
Import-Module -Name Az
Tarayıcı oturum açma belirteci ile Azure'a Bağlan
PowerShell'de bir aboneliğe bağlanmak için portal oturum açma kimlik bilgilerinizi kullanabilirsiniz. Alternatif olarak, bir hizmet sorumlusuyla etkileşimli olmayan kimlik doğrulaması yapabilirsiniz.
Connect-AzAccount
Birden çok Azure aboneliğiniz varsa Azure aboneliğinizi ayarlayın. Geçerli aboneliklerinizin listesini görmek için bu komutu çalıştırın.
Get-AzSubscription | sort SubscriptionName | Select SubscriptionName
Aboneliği belirtmek için aşağıdaki komutu çalıştırın. Aşağıdaki örnekte abonelik adı şeklindedir ContosoSubscription.
Select-AzSubscription -SubscriptionName ContosoSubscription
Abonelikteki hizmetleri listeleme
Aşağıdaki komutlar Az.Resources'tan gelir ve aboneliğinizde önceden sağlanan mevcut kaynaklar ve hizmetler hakkında bilgi döndürür. Daha önce kaç arama hizmetinin oluşturulduğunu bilmiyorsanız, bu komutlar bu bilgileri döndürerek portala bir yolculuk yapmanızı sağlar.
İlk komut tüm arama hizmetlerini döndürür.
Get-AzResource -ResourceType Microsoft.Search/searchServices | ft
Hizmetler listesinden belirli bir kaynakla ilgili bilgileri döndürebilirsiniz.
Get-AzResource -ResourceName <service-name>
Sonuçlar aşağıdaki çıkışa benzer görünmelidir.
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
Ithalat Az.Search
Az.Search komutları, modülü yükleyene kadar kullanılamaz.
Install-Module -Name Az.Search -Scope CurrentUser
Tüm Az.Search komutları listeleme
Doğrulama adımı olarak modülde sağlanan komutların listesini döndürebilirsiniz.
Get-Command -Module Az.Search
Sonuçlar aşağıdaki çıkışa benzer görünmelidir.
CommandType Name Version Source
----------- ---- ------- ------
Cmdlet Get-AzSearchAdminKeyPair 0.10.0 Az.Search
Cmdlet Get-AzSearchPrivateEndpointConnection 0.10.0 Az.Search
Cmdlet Get-AzSearchPrivateLinkResource 0.10.0 Az.Search
Cmdlet Get-AzSearchQueryKey 0.10.0 Az.Search
Cmdlet Get-AzSearchService 0.10.0 Az.Search
Cmdlet Get-AzSearchSharedPrivateLinkResource 0.10.0 Az.Search
Cmdlet New-AzSearchAdminKey 0.10.0 Az.Search
Cmdlet New-AzSearchQueryKey 0.10.0 Az.Search
Cmdlet New-AzSearchService 0.10.0 Az.Search
Cmdlet New-AzSearchSharedPrivateLinkResource 0.10.0 Az.Search
Cmdlet Remove-AzSearchPrivateEndpointConnection 0.10.0 Az.Search
Cmdlet Remove-AzSearchQueryKey 0.10.0 Az.Search
Cmdlet Remove-AzSearchService 0.10.0 Az.Search
Cmdlet Remove-AzSearchSharedPrivateLinkResource 0.10.0 Az.Search
Cmdlet Set-AzSearchPrivateEndpointConnection 0.10.0 Az.Search
Cmdlet Set-AzSearchService 0.10.0 Az.Search
Cmdlet Set-AzSearchSharedPrivateLinkResource 0.10.0 Az.Search
Paketin eski bir sürümüne sahipseniz modülü güncelleştirerek en son işlevleri edinin.
Update-Module -Name Az.Search
Arama hizmeti bilgilerini alma
Az.Search içeri aktarıldıktan ve arama hizmetinizi içeren kaynak grubunu biliyorsanız, ad, bölge, katman, çoğaltma ve bölüm sayıları dahil olmak üzere hizmet tanımını döndürmek için Get-AzSearchService komutunu çalıştırın. Bu komut için arama hizmetini içeren kaynak grubunu sağlayın.
Get-AzSearchService -ResourceGroupName <resource-group-name>
Sonuçlar aşağıdaki çıkışa benzer görünmelidir.
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
Hizmeti oluşturma veya silme
New-AzSearchService, yeni bir arama hizmeti oluşturmak için kullanılır.
New-AzSearchService -ResourceGroupName <resource-group-name> -Name <search-service-name> -Sku "Standard" -Location "West US" -PartitionCount 3 -ReplicaCount 3 -HostingMode Default
Sonuçlar aşağıdaki çıkışa benzer görünmelidir.
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
Remove-AzSearchService , bir hizmeti ve verilerini silmek için kullanılır.
Remove-AzSearchService -ResourceGroupName <resource-group-name> -Name <search-service-name>
Eylemi onaylamanız istenir.
Confirm
Are you sure you want to remove Search Service 'pstestazuresearch01'?
[Y] Yes [N] No [S] Suspend [?] Help (default is "Y"): y
IP kurallarıyla hizmet oluşturma
Güvenlik gereksinimlerinize bağlı olarak, IP güvenlik duvarı yapılandırılmış bir arama hizmeti oluşturmak isteyebilirsiniz. Bunu yapmak için önce IP Kurallarını tanımlayın ve ardından aşağıda gösterildiği gibi parametresine IPRuleList geçirin.
$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
Sistem tarafından atanan yönetilen kimlikle hizmet oluşturma
Bazı durumlarda, örneğin bir veri kaynağına bağlanmak için yönetilen kimlik kullanırken sistem tarafından atanan yönetilen kimliği açmanız gerekir. Bu, komutuna eklenerek -IdentityType SystemAssigned gerçekleştirilir.
New-AzSearchService -ResourceGroupName <resource-group-name> `
-Name <search-service-name> `
-Sku Standard `
-Location "West US" `
-PartitionCount 3 -ReplicaCount 3 `
-HostingMode Default `
-IdentityType SystemAssigned
S3HD hizmeti oluşturma
S3HD hizmeti oluşturmak için ve -HostingMode birleşimi -Sku kullanılır. ve -HostingMode olarak Standard3HighDensityayarlayın-Sku.
New-AzSearchService -ResourceGroupName <resource-group-name> `
-Name <search-service-name> `
-Sku Standard3 `
-Location "West US" `
-PartitionCount 1 -ReplicaCount 3 `
-HostingMode HighDensity
Özel uç nokta ile hizmet oluşturma
Azure AI Search için Özel Uç Noktalar, sanal ağdaki bir istemcinin bir Özel Bağlantı üzerinden arama dizinindeki verilere güvenli bir şekilde erişmesini sağlar. Özel uç nokta, arama hizmetiniz için sanal ağ adres alanından bir IP adresi kullanır. İstemci ile arama hizmeti arasındaki ağ trafiği, sanal ağ üzerinden ve Microsoft omurga ağındaki özel bir bağlantı üzerinden geçiş yaparak genel İnternet'ten etkilenmeyi ortadan kaldırır. Daha fazla bilgi için bkz . Azure AI Search için özel uç nokta oluşturma.
Aşağıdaki örnekte özel uç nokta ile arama hizmetinin nasıl oluşturulacağı gösterilmektedir.
İlk olarak, olarak ayarlanmış bir arama hizmeti PublicNetworkAccess dağıtın 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
Ardından bir sanal ağ, özel ağ bağlantısı ve özel uç nokta oluşturun.
# 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
Son olarak, özel bir DNS Bölgesi oluşturun.
## 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'de özel uç nokta oluşturma hakkında daha fazla bilgi için bu Özel Bağlantı Hızlı Başlangıç'a bakın.
Özel uç nokta bağlantılarını yönetme
Özel uç nokta bağlantısı oluşturmaya ek olarak , Setve Remove bağlantısını da Getoluşturabilirsiniz.
Get-AzSearchPrivateEndpoint Bağlan ion, özel uç nokta bağlantısını almak ve durumunu görmek için kullanılır.
Get-AzSearchPrivateEndpointConnection -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name>
Bağlantıyı güncelleştirmek için Set-AzSearchPrivateEndpoint Bağlan ion kullanılır. Aşağıdaki örnek, özel uç nokta bağlantısını reddedildi olarak ayarlar:
Set-AzSearchPrivateEndpointConnection -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -Name <pe-connection-name> -Status Rejected -Description "Rejected"
Remove-AzSearchPrivateEndpoint Bağlan ion özel uç nokta bağlantısını silmek için kullanılır.
Remove-AzSearchPrivateEndpointConnection -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -Name <pe-connection-name>
Yönetici anahtarlarını yeniden oluşturma
New-AzSearch Yönetici Key, yönetici API anahtarlarını almak için kullanılır. Kimliği doğrulanmış erişim için her hizmetle iki yönetici anahtarı oluşturulur. Anahtarlar her istekte gereklidir. Her iki yönetici anahtarı da işlevsel olarak eşdeğerdir ve herhangi bir bilgiyi alma veya herhangi bir nesne oluşturup silme özelliğiyle bir arama hizmetine tam yazma erişimi verir. Birini diğerini değiştirirken kullanabilmeniz için iki anahtar vardır.
Veya anahtarı olarak primarysecondary belirtilen bir kerede yalnızca bir tane yeniden oluşturabilirsiniz. Kesintisiz hizmet için birincil anahtar üzerinde çalışırken ikincil anahtar kullanmak üzere tüm istemci kodunu güncelleştirmeyi unutmayın. İşlemler devam ederken anahtarları değiştirmekten kaçının.
Beklediğiniz gibi, istemci kodunu güncelleştirmeden anahtarları yeniden oluşturursanız, eski anahtarı kullanan istekler başarısız olur. Tüm yeni anahtarların yeniden yenilenmesi sizi kalıcı olarak hizmetinizin dışına kilitlemez ve portaldan hizmete erişmeye devam edebilirsiniz. Birincil ve ikincil anahtarları yeniden üretdikten sonra, istemci kodunu yeni anahtarları kullanacak şekilde güncelleştirebilirsiniz ve işlemler buna göre devam eder.
API anahtarları için değerler hizmet tarafından oluşturulur. Azure AI Search'te kullanılacak özel bir anahtar sağlayamazsınız. Benzer şekilde, yönetici API anahtarları için kullanıcı tanımlı bir ad yoktur. Anahtara başvurular veya primarysecondarysabit dizelerdir.
New-AzSearchAdminKey -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -KeyKind Primary
Sonuçlar aşağıdaki çıkışa benzer görünmelidir. Her iki anahtar da aynı anda yalnızca birini değiştirmenize rağmen döndürülür.
Primary Secondary
------- ---------
<alphanumeric-guid> <alphanumeric-guid>
Sorgu anahtarlarını oluşturma veya silme
New-AzSearchQueryKey , istemci uygulamalarından Azure AI Search dizinine salt okunur erişim için sorgu API anahtarları oluşturmak için kullanılır. Sorgu anahtarları, arama sonuçlarını almak için belirli bir dizinde kimlik doğrulaması yapmak için kullanılır. Sorgu anahtarları, hizmette dizin, veri kaynağı veya dizin oluşturucu gibi diğer öğelere salt okunur erişim izni vermez.
Azure AI Arama'nın kullanması için bir anahtar sağlayamazsınız. API anahtarları hizmet tarafından oluşturulur.
New-AzSearchQueryKey -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -Name <query-key-name>
Çoğaltmaları ve bölümleri ölçeklendirme
Set-AzSearchService, hizmetinizdeki faturalanabilir kaynakları yeniden ayarlamak için çoğaltmaları ve bölümleri artırmak veya azaltmak için kullanılır. Çoğaltmaların veya bölümlerin artırılması, faturanıza hem sabit hem de değişken ücretler içeren ekler. Daha fazla işleme gücü için geçici bir ihtiyacınız varsa, iş yükünü işlemek için çoğaltmaları ve bölümleri artırabilirsiniz. Genel Bakış portalı sayfasındaki izleme alanında sorgu gecikme süresi, saniye başına sorgu sayısı ve geçerli kapasitenin yeterli olup olmadığını gösteren azaltma kutucukları bulunur.
Kaynak oluşturmanın eklenmesi veya kaldırılması biraz zaman alabilir. Kapasitede yapılan ayarlamalar arka planda gerçekleşir ve mevcut iş yüklerinin devam etmesi sağlanır. Ek kapasite hazır olduğunda gelen istekler için kullanılır ve ek yapılandırma gerekmez.
Kapasitenin kaldırılması kesintiye neden olabilir. Bırakılan isteklerden kaçınmak için kapasiteyi azaltmadan önce tüm dizin oluşturma ve dizin oluşturucu işlerinin durdurulması önerilir. Bu mümkün değilse, yeni hedef düzeylerinize ulaşılana kadar kapasiteyi artımlı olarak azaltmayı, bir kerede bir çoğaltmayı ve bölümü azaltmayı düşünebilirsiniz.
Komutu gönderdikten sonra, yolun ortasında sonlandırmanın hiçbir yolu yoktur. Sayıları düzeltmeden önce komutun bitmesini beklemeniz gerekir.
Set-AzSearchService -ResourceGroupName <search-service-resource-group-name> -Name <search-service-name> -PartitionCount 6 -ReplicaCount 6
Sonuçlar aşağıdaki çıkışa benzer görünmelidir.
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
Paylaşılan özel bağlantı kaynağı oluşturma
Azure AI Arama API'leri aracılığıyla oluşturulan güvenli kaynakların özel uç noktaları paylaşılan özel bağlantı kaynakları olarak adlandırılır. Bunun nedeni, Azure Özel Bağlantı hizmetiyle tümleştirilmiş depolama hesabı gibi bir kaynağa erişimi "paylaşmanız"dır.
Azure AI Search'te verilerin dizinini oluşturmak için dizin oluşturucu kullanıyorsanız ve veri kaynağınız özel bir ağdaysa, verilere ulaşmak için bir giden özel uç nokta bağlantısı oluşturabilirsiniz.
Azure AI Search'ten giden özel uç noktaları oluşturabileceğiniz Azure Kaynaklarının tam listesi ve ilgili Grup Kimliği değerleri burada bulunabilir.
New-AzSearchSharedPrivateLinkResource paylaşılan özel bağlantı kaynağını oluşturmak için kullanılır. Bu komutu çalıştırmadan önce veri kaynağı için bazı yapılandırmalar gerekebileceğini unutmayın.
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 paylaşılan özel bağlantı kaynaklarını almanıza ve durumlarını görüntülemenize olanak tanır.
Get-AzSearchSharedPrivateLinkResource -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -Name <spl-name>
Kullanılabilmesi için önce aşağıdaki komutla bağlantıyı onaylamanız gerekir.
Approve-AzPrivateEndpointConnection `
-Name <spl-name> `
-ServiceName <search-service-name> `
-ResourceGroupName <search-service-resource-group-name> `
-Description = "Approved"
Paylaşılan özel bağlantı kaynağını silmek için Remove-AzSearchSharedPrivateLinkResource kullanılır.
$job = Remove-AzSearchSharedPrivateLinkResource -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -Name <spl-name> -Force -AsJob
$job | Get-Job
Paylaşılan özel bağlantı kaynaklarını ayarlamayla ilgili tüm ayrıntılar için özel uç nokta üzerinden dizin oluşturucu bağlantıları oluşturma belgelerine bakın.
Sonraki adımlar
Bir dizin oluşturun, portalı, REST API'leri veya .NET SDK'sını kullanarak bir dizini sorgular.