Aracılığıyla paylaş


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:

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ğlanma

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 Standard3 HighDensityayarlayı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-AzSearchPrivateEndpointConnection ö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-AzSearchPrivateEndpointConnection 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-AzSearchPrivateEndpointConnection ö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-AzSearchAdminKey , 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 primary secondary 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 primary secondarysabit 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

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.