Aracılığıyla paylaş

PowerShell kullanarak Azure AI Search hizmetinizi 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.

Bir hizmetin adını veya bölgesini program aracılığıyla veya Azure portalında değiştiremezsiniz. Ayrılmış kaynaklar bir hizmet oluşturulduğunda ayrılır, bu nedenle temel alınan donanımın (konum veya düğüm türü) değiştirilmesi için yeni bir hizmet gerekir.

Uyarı

Arama Yönetimi REST API'leri ve Azure portalı fiyatlandırma katmanınızı değiştirmeyi destekler. Şu anda yalnızca Temel ve Standart (S1, S2 ve S3) katmanları arasında geçiş yapabilirsiniz.

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. Önceden kaç arama hizmetinin oluşturulduğunu bilmiyorsanız, bu komutlar size Azure portalına gitme gereğini ortadan kaldırarak, gereken bilgileri 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

İthalat 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 bildikten sonra, 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. Komuta -IdentityType SystemAssigned eklenerek bu gerçekleştirilebilir.

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 -Sku birleşimi -HostingMode kullanılır. -Sku öğesini Standard3 olarak ve -HostingMode öğesini HighDensity olarak ayarlayın.

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, PublicNetworkAccessDisabled olarak ayarlayarak bir arama hizmeti dağıtın.

$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 Get, Set ve Remove bağlantısını da oluş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.

primary veya secondary anahtarlarından biri olarak belirlenen 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 sakı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 azure portalı üzerinden 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. Anahtar, ya primary ya da secondary olarak sabit 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>

Replikalar ve bölümler ölçekleri

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ı, hem sabit hem de değişken ücretler içeren fatura maliyetinizi artırır. Geçici olarak daha fazla işleme gücüne ihtiyaç duyuyorsanız, iş yükünü yönetmek 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.

Kaynakları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 birer birer çoğaltma ve bölüm azaltarak kademeli olarak düşürmeyi 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/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/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

Azure portalını, REST API'lerini veya .NET SDK'sını kullanarak bir dizin oluşturun, bir dizini sorgulayın.

  • Last updated on