Mengelola layanan Pencarian Azure AI Anda dengan PowerShell

  • Artikel

Anda dapat menjalankan cmdlet dan skrip PowerShell di Windows, Linux, atau di Azure Cloud Shell untuk membuat dan mengonfigurasi Azure AI Search.

Gunakan modul Az.Search untuk melakukan tugas berikut:

Terkadang, pertanyaan yang ditanyakan adalah mengenai tugas yang tidak terdapat dalam daftar di atas.

Anda tidak dapat mengubah nama server, wilayah, atau tingkatan secara terprogram atau di portal. Sumber daya khusus dialokasikan ketika layanan dibuat. Dengan demikian, mengubah perangkat keras yang mendasarinya (lokasi atau jenis simpul) memerlukan layanan baru.

Anda tidak dapat menggunakan alat atau API untuk mentransfer konten, seperti indeks, dari satu layanan ke layanan lainnya. Dalam layanan, pembuatan konten terprogram adalah melalui Search Service REST API atau SDK seperti Azure SDK untuk .NET. Meskipun tidak ada perintah khusus untuk migrasi konten, Anda dapat menulis skrip yang memanggil REST API atau pustaka klien untuk membuat dan memuat indeks pada layanan baru.

Fitur administrasi pratinjau biasanya tidak tersedia dalam modul Az.Search . Jika Anda ingin menggunakan fitur pratinjau, gunakan Rest API Manajemen dan versi API pratinjau.

Modul Az.Search memperluas Azure PowerShell dengan paritas penuh ke versi stabil API REST Manajemen Pencarian.

Memeriksa versi dan memuat modul

Contoh dalam artikel ini bersifat interaktif dan memerlukan izin yang ditinggikan. PowerShell lokal dan Azure PowerShell ( modul Az ) diperlukan.

Pemeriksaan versi PowerShell

Instal Versi terbaru PowerShell jika Anda tidak memilikinya.

$PSVersionTable.PSVersion

Memuat Azure PowerShell

Jika Anda tidak yakin bahwa Az telah diinstal, jalankan perintah berikut sebagai langkah verifikasi.

Get-InstalledModule -Name Az

Beberapa sistem tidak memuat modul secara otomatis. Jika Anda mendapatkan kesalahan pada perintah sebelumnya, coba muat modul, dan jika itu gagal, kembali ke instruksi penginstalan Azure PowerShell penginstalan untuk melihat apakah Anda melewatkan langkah.

Import-Module -Name Az

Menyambungkan ke Azure dengan token masuk browser

Anda bisa menggunakan mandat masuk portal Anda untuk menyambungkan ke langganan di PowerShell. Atau Anda dapat mengautentikasi secara non-interaktif dengan perwakilan layanan.

Connect-AzAccount

Jika Anda memegang beberapa langganan Azure, atur langganan Azure Anda. Untuk melihat daftar langganan Anda saat ini, jalankan perintah ini.

Get-AzSubscription | sort SubscriptionName | Select SubscriptionName

Untuk menentukan langganan, jalankan perintah berikut. Dalam contoh berikut, nama langganan adalah ContosoSubscription.

Select-AzSubscription -SubscriptionName ContosoSubscription

Mencantumkan layanan dalam langganan

Perintah berikut berasal dari Az.Resources, mengembalikan informasi tentang sumber daya dan layanan yang sudah ada yang tersedia dalam langganan Anda. Jika Anda tidak tahu jumlah layanan pencarian yang sudah dibuat, perintah ini mengembalikan informasi tersebut, menghemat perjalanan Anda ke portal.

Perintah pertama mengembalikan semua layanan pencarian.

Get-AzResource -ResourceType Microsoft.Search/searchServices | ft

Dari daftar layanan, kembalikan informasi tentang sumber daya tertentu.

Get-AzResource -ResourceName <service-name>

Anda akan melihat hasil yang mirip dengan output berikut.

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

Impor Az.Search

Perintah dari Az.Search tidak tersedia hingga Anda memuat modul.

Install-Module -Name Az.Search -Scope CurrentUser

Mencantumkan semua Az.Search perintah

Sebagai langkah verifikasi, kembalikan daftar perintah yang tersedia dalam modul.

Get-Command -Module Az.Search

Anda akan melihat hasil yang mirip dengan output berikut.

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

Jika Anda memiliki versi paket yang lebih lama, perbarui modul untuk mendapatkan fungsionalitas terbaru.

Update-Module -Name Az.Search

Mendapatkan informasi layanan pencarian

Setelah Az.Search diimpor dan Anda mengetahui grup sumber daya yang berisi layanan pencarian Anda, jalankan Get-AzSearchService untuk mengembalikan definisi layanan, termasuk nama, wilayah, tingkat, dan jumlah replika serta partisi. Untuk perintah ini, sediakan grup sumber daya yang berisi layanan pencarian.

Get-AzSearchService -ResourceGroupName <resource-group-name>

Anda akan melihat hasil yang mirip dengan output berikut.

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

Membuat atau menghapus layanan

New-AzSearchService digunakan untuk membuat layanan pencarian baru.

New-AzSearchService -ResourceGroupName <resource-group-name> -Name <search-service-name> -Sku "Standard" -Location "West US" -PartitionCount 3 -ReplicaCount 3 -HostingMode Default

Anda akan melihat hasil yang mirip dengan output berikut.

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 digunakan untuk menghapus layanan dan datanya.

Remove-AzSearchService -ResourceGroupName <resource-group-name> -Name <search-service-name>

Anda diminta untuk mengonfirmasi tindakan tersebut.

Confirm
Are you sure you want to remove Search Service 'pstestazuresearch01'?
[Y] Yes  [N] No  [S] Suspend  [?] Help (default is "Y"): y

Membuat layanan dengan aturan IP

Bergantung pada persyaratan keamanan, Anda mungkin ingin membuat layanan pencarian dengan firewall IP yang dikonfigurasi. Untuk melakukannya, tentukan Aturan IP terlebih dahulu, kemudian teruskan ke parameter IPRuleList seperti yang ditunjukkan di bawah ini.

$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

Membuat layanan dengan identitas terkelola yang ditetapkan sistem

Dalam beberapa kasus, seperti saat menggunakan identitas terkelola untuk menyambungkan ke sumber data, Anda perlu mengaktifkan identitas terkelola yang ditetapkan sistem. Pengaktifan ini dilakukan dengan menambah -IdentityType SystemAssigned ke perintah.

New-AzSearchService -ResourceGroupName <resource-group-name> `
                      -Name <search-service-name> `
                      -Sku Standard `
                      -Location "West US" `
                      -PartitionCount 3 -ReplicaCount 3 `
                      -HostingMode Default `
                      -IdentityType SystemAssigned

Membuat layanan S3HD

Untuk membuat layanan S3HD , kombinasi dan -Sku-HostingMode digunakan. Atur -Sku ke Standard3 dan -HostingMode ke HighDensity.

New-AzSearchService -ResourceGroupName <resource-group-name> `
                      -Name <search-service-name> `
                      -Sku Standard3 `
                      -Location "West US" `
                      -PartitionCount 1 -ReplicaCount 3 `
                      -HostingMode HighDensity

Membuat layanan dengan titik akhir privat

Titik Akhir Privat untuk Azure AI Search memungkinkan klien di jaringan virtual mengakses data dengan aman dalam indeks pencarian melalui Private Link. Titik akhir privat menggunakan alamat IP dari ruang alamat jaringan virtual untuk layanan penelusuran Anda. Lalu lintas jaringan antara klien dan layanan penelusuran melintasi jaringan virtual dan tautan privat di jaringan backbone Microsoft, menghilangkan paparan dari internet publik. Untuk informasi selengkapnya, lihat Membuat titik akhir privat untuk Pencarian Azure AI.

Contoh berikut menunjukkan cara membuat layanan pencarian dengan titik akhir privat.

Pertama, sebarkan layanan pencarian dengan mengatur PublicNetworkAccess ke 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

Selanjutnya, buat jaringan virtual, koneksi jaringan privat, dan titik akhir privat.

# 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

Terakhir, buat zona DNS privat.

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

Untuk informasi selengkapnya tentang membuat titik akhir privat di PowerShell, lihat Mulai Cepat Private Link ini.

Mengelola sambungan titik akhir privat

Selain membuat koneksi titik akhir privat, Anda juga dapat Get, Set, dan Remove koneksi.

Get-AzSearchPrivateEndpointConnection digunakan untuk mengambil koneksi titik akhir privat serta melihat statusnya.

Get-AzSearchPrivateEndpointConnection -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name>

Set-AzSearchPrivateEndpointConnection digunakan untuk memperbarui koneksi. Contoh berikut menetapkan koneksi titik akhir privat menjadi ditolak:

Set-AzSearchPrivateEndpointConnection -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -Name <pe-connection-name> -Status Rejected  -Description "Rejected"

Remove-AzSearchPrivateEndpointConnection digunakan untuk menghapus koneksi titik akhir privat.

 Remove-AzSearchPrivateEndpointConnection -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -Name <pe-connection-name>

Meregenerasi kunci admin

New-AzSearchAdminKey digunakan untuk memutar kunci API admin. Dua kunci admin dibuat pada setiap layanan untuk akses terautentikasi. Kunci diperlukan pada setiap permintaan. Kedua kunci admin memiliki fungsionalitas yang setara, yang memberikan akses tulis penuh ke layanan pencarian dengan kemampuan mengambil informasi apa pun, atau membuat dan menghapus objek apa pun. Terdapat dua kunci agar Anda bisa menggunakan satu kunci saat mengganti yang lainnya.

Anda hanya dapat meregenerasi satu demi satu, yang ditentukan sebagai kunci primary atau secondary. Untuk layanan tanpa gangguan, ingatlah untuk memperbarui semua kode klien agar menggunakan kunci sekunder saat memutar kunci primer. Hindari penggantian kunci saat operasi berlangsung.

Seperti yang Anda kira, jika Anda meregenerasi kunci tanpa memperbarui kode klien, permintaan yang menggunakan kunci lama akan gagal. Meregenerasi semua kunci baru tidak mengunci Anda secara permanen dari layanan Anda, dan Anda masih dapat mengakses layanan melalui portal. Setelah Anda meregenerasi kunci primer dan sekunder, Anda dapat memperbarui kode klien untuk menggunakan kunci baru dan operasi berlanjut sebagaimana mestinya.

Nilai untuk kunci API dihasilkan oleh layanan. Anda tidak dapat menyediakan kunci kustom untuk Azure AI Search untuk digunakan. Demikian pula, tidak ada nama yang ditentukan pengguna untuk kunci API admin. Referensi ke kunci adalah string tetap, baik primary atau secondary.

New-AzSearchAdminKey -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -KeyKind Primary

Anda akan melihat hasil yang mirip dengan output berikut. Kedua kunci dikembalikan meskipun Anda hanya mengubah satu demi satu.

Primary                    Secondary
-------                    ---------
<alphanumeric-guid>        <alphanumeric-guid>

Membuat atau menghapus kunci kueri

New-AzSearchQueryKey digunakan untuk membuat kunci API kueri untuk akses baca-saja dari aplikasi klien ke indeks Azure AI Search. Kunci kueri digunakan untuk mengautentikasi ke indeks tertentu untuk mengambil hasil pencarian. Kunci kueri tidak memberikan akses baca-saja ke item lain di layanan, seperti indeks, sumber data, atau pengindeks.

Anda tidak dapat menyediakan kunci untuk Azure AI Search untuk digunakan. Kunci API dihasilkan oleh layanan.

New-AzSearchQueryKey -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -Name <query-key-name>

Menskalakan replika dan partisi

Set-AzSearchService digunakan untuk meningkatkan atau menurunkan replika atau partisi untuk menyesuaikan ulang sumber daya yang dapat ditagih dalam layanan Anda. Meningkatkan replika atau partisi akan menambah tagihan Anda dengan biaya tetap dan variabel. Jika Anda memiliki kebutuhan sementara untuk lebih banyak daya pemrosesan, Anda dapat meningkatkan replika dan partisi untuk menangani beban kerja. Area pemantauan di halaman portal Gambaran Umum memiliki petak pada latensi kueri, kueri per detik, dan pembatasan, yang menunjukkan apakah kapasitas saat ini memadai.

Penambahan atau penghapusan sumber daya memerlukan waktu beberapa saat. Penyesuaian kapasitas terjadi di latar belakang, yang memungkinkan beban kerja yang ada untuk terus berjalan. Kapasitas tambahan digunakan untuk permintaan masuk segera setelah siap, tanpa konfigurasi tambahan yang diperlukan.

Menghapus kapasitas bisa menjadi proses yang mengganggu. Disarankan untuk menghentikan semua pengindeksan dan pekerjaan pengindeks sebelum mengurangi kapasitas untuk menghindari permintaan yang digugurkan. Jika tidak memungkinkan, sebaiknya Anda mengurangi kapasitas secara bertahap, satu replika dan satu partisi pada satu waktu, hingga tingkat target baru Anda tercapai.

Setelah Anda mengirimkan perintah, tidak ada cara untuk mengakhirinya di tengah jalan. Anda harus menunggu hingga perintah selesai sebelum merevisi hitungan.

Set-AzSearchService -ResourceGroupName <search-service-resource-group-name> -Name <search-service-name> -PartitionCount 6 -ReplicaCount 6

Anda akan melihat hasil yang mirip dengan output berikut.

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

Titik akhir privat sumber daya aman yang dibuat melalui AZURE AI Search API disebut sebagai sumber daya tautan privat bersama. Ini karena Anda "berbagi" akses ke sumber daya, seperti akun penyimpanan yang telah terintegrasi dengan layanan Azure Private Link.

Jika Anda menggunakan pengindeks untuk mengindeks data di Azure AI Search, dan sumber data Anda berada di jaringan privat, Anda dapat membuat koneksi titik akhir privat keluar untuk menjangkau data.

Daftar lengkap Sumber Daya Azure tempat Anda dapat membuat titik akhir privat keluar dari Azure AI Search dapat ditemukan di sini bersama dengan nilai ID Grup terkait.

New-AzSearchSharedPrivateLinkResource digunakan untuk membuat sumber daya tautan privat bersama. Perlu diingat bahwa beberapa konfigurasi mungkin diperlukan untuk sumber data sebelum menjalankan perintah ini.

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 memungkinkan Anda mengambil sumber daya tautan privat bersama dan melihat statusnya.

Get-AzSearchSharedPrivateLinkResource -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -Name <spl-name>

Anda perlu menyetujui koneksi dengan perintah berikut sebelum dapat digunakan.

Approve-AzPrivateEndpointConnection `
    -Name <spl-name> `
    -ServiceName <search-service-name> `
    -ResourceGroupName <search-service-resource-group-name> `
    -Description = "Approved"

Remove-AzSearchSharedPrivateLinkResource digunakan untuk menghapus sumber daya tautan privat bersama.

$job = Remove-AzSearchSharedPrivateLinkResource -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -Name <spl-name> -Force -AsJob

$job | Get-Job

Untuk detail selengkapnya penyiapan sumber daya tautan privat bersama, lihat dokumentasi membuat koneksi pengindeks melalui titik akhir privat.

Langkah berikutnya

Buat indeks, mengkueri indeks dengan portal, REST API, atau .NET SDK.