Mengelola layanan Pencarian Azure AI Anda menggunakan PowerShell

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

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 atau wilayah layanan secara terprogram atau di portal Microsoft Azure. Sumber daya khusus dialokasikan saat layanan dibuat, sehingga mengubah perangkat keras yang mendasar (jenis lokasi atau node) memerlukan layanan baru.

Nota

REST API Manajemen Pencarian dan portal Microsoft Azure mendukung perubahan tingkat harga Anda. Saat ini, Anda hanya dapat beralih antara tingkat Dasar dan Standar (S1, S2, dan S3).

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 dengan versi API pratinjau.

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

Periksa versi dan muat modul

Contoh dalam artikel ini bersifat interaktif dan memerlukan izin yang ditingkatkan. 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 apakah Az 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 untuk melihat apakah Anda melewatkan langkah.

Import-Module -Name Az

Menyambungkan ke Azure dengan token masuk browser

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

Connect-AzAccount

Jika Anda menyimpan 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 sudah disediakan dalam langganan Anda. Jika Anda tidak tahu berapa banyak layanan pencarian yang sudah dibuat, perintah ini mengembalikan informasi tersebut, menghindarkan Anda dari mengunjungi portal Azure.

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

Mengimpor 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 disediakan 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 dan 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, pertama-tama tentukan Aturan IP lalu teruskan ke parameter seperti yang IPRuleList 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, digunakan kombinasi -Sku dan -HostingMode. 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

Endpoint Privat untuk Pencarian Azure AI memungkinkan klien pada jaringan virtual mengakses data dengan aman di 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 Quickstart Private Link ini.

Mengelola sambungan titik akhir privat

Selain membuat koneksi titik akhir privat, Anda bisa Get, Set, dan Remove koneksi tersebut.

Get-AzSearchPrivateEndpointConnection digunakan untuk mengambil koneksi titik akhir privat dan untuk 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>

Menghasilkan ulang kunci admin

New-AzSearchAdminKey digunakan untuk memperbarui 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 Azure. 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 Pencarian Azure AI 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 kunci pada satu waktu.

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 Pencarian Azure AI. 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 Pencarian Azure AI 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 mengurangi replika dan partisi guna menyesuaikan sumber daya yang dapat ditagih dalam layanan Anda. Meningkatkan jumlah replika atau partisi akan meningkatkan tagihan Anda, yang terdiri dari biaya tetap dan biaya variabel. Jika Anda memiliki kebutuhan sementara untuk lebih banyak daya pemrosesan, Anda dapat meningkatkan replika dan partisi untuk menangani beban kerja. Area pemantauan pada halaman portal Gambaran Umum memiliki kotak untuk latensi kueri, kueri per detik, dan pembatasan kecepatan, yang menunjukkan apakah kapasitas saat ini sudah 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/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/demo-westus/providers/Microsoft.Search/searchServices/my-demo-searchapp

Titik akhir privat dari sumber daya yang diamankan dan dibuat melalui Pencarian Azure AI APIs disebut sebagai sumber daya tautan privat yang dibagikan. 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 Pencarian Azure AI, 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 Pencarian Azure AI 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 tentang menyiapkan sumber daya tautan privat bersama, lihat dokumentasi tentang membuat koneksi pengindeks melalui titik akhir privat.

Langkah selanjutnya

Buat indeks, kueri indeks menggunakan portal Azure, REST API, atau .NET SDK.

  • Last updated on