Mengelola layanan Pencarian Azure AI Anda menggunakan Azure CLI

Nota

Pencarian Azure AI tersedia melalui portal Azure, REST API, dan Azure SDK. Ini juga mendukung Foundry IQ, lapisan pengetahuan terkelola yang mengubah konten perusahaan menjadi pangkalan pengetahuan yang dapat digunakan kembali dan sadar izin untuk agen di portal Microsoft Foundry.

Anda dapat menjalankan perintah dan skrip Azure CLI di Windows, macOS, Linux, atau di Azure Cloud Shell untuk membuat dan mengonfigurasi Pencarian Azure AI.

Gunakan modul pencarian az untuk melakukan tugas-tugas berikut:

Informasi berikut menjawab pertanyaan umum tentang tugas yang tidak ada dalam daftar sebelumnya.

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 di dalam modul pencarian az. Jika Anda ingin menggunakan fitur pratinjau, gunakan REST API Manajemen dengan versi API pratinjau.

Prasyarat

Versi Azure CLI terdaftar di GitHub.

Modul pencarian az memperluas Azure CLI dengan paritas penuh terhadap versi stabil Manajemen Pencarian API REST.

Mencantumkan layanan dalam langganan

Perintah berikut berasal dari sumber daya az, 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.

az resource list --resource-type Microsoft.Search/searchServices --output table

Dari daftar layanan, kembalikan informasi tentang sumber daya tertentu.

az resource list --name <search-service-name>

Mencantumkan semua perintah az search

Anda dapat melihat informasi tentang subgrup dan perintah yang tersedia dalam az search dari dalam CLI. Atau, Anda dapat meninjau dokumentasi.

Untuk melihat subgrup yang tersedia di dalamnya az search, jalankan perintah berikut ini.

az search --help

Responsnya akan terlihat mirip dengan output berikut.

Group
    az search : Manage Azure AI Search.

Subgroups:
    admin-key                    : Manage Azure AI Search admin keys.
    offering                     : Manage Azure AI Search offerings.
    private-endpoint-connection  : Manage Azure AI Search private endpoint connections.
    private-link-resource        : Manage Azure AI Search private link resources.
    query-key                    : Manage Azure AI Search query keys.
    service                      : Manage Service.
    shared-private-link-resource : Manage Azure AI Search shared private link resources.
    usage                        : Manage Usage.

Dalam setiap subgrup, beberapa perintah tersedia. Anda bisa melihat perintah yang tersedia untuk service subgrup dengan menjalankan baris berikut.

az search service --help

Anda juga dapat melihat argumen yang tersedia untuk perintah tertentu.

az search service create --help

Mendapatkan informasi layanan pencarian

Jika Anda mengetahui grup sumber daya yang berisi layanan pencarian Anda, jalankan az search service show untuk menampilkan definisi layanan, termasuk nama, wilayah, lapisan, dan jumlah replika dan partisi. Untuk perintah ini, sediakan grup sumber daya yang berisi layanan pencarian.

az search service show --name <service-name> --resource-group <search-service-resource-group-name>

Membuat atau menghapus layanan

Untuk membuat layanan pencarian baru, gunakan perintah buat layanan pencarian az.

az search service create \
    --name <service-name> \
    --resource-group <search-service-resource-group-name> \
    --sku Standard \
    --partition-count 1 \
    --replica-count 1

Anda akan melihat hasil yang mirip dengan output berikut:

{
  "hostingMode": "default",
  "id": "/subscriptions/<alphanumeric-subscription-ID>/resourceGroups/demo-westus/providers/Microsoft.Search/searchServices/my-demo-searchapp",
  "identity": null,
  "location": "West US",
  "name": "my-demo-searchapp",
  "networkRuleSet": {
    "bypass": "None",
    "ipRules": []
  },
  "partitionCount": 1,
  "privateEndpointConnections": [],
  "provisioningState": "succeeded",
  "publicNetworkAccess": "Enabled",
  "replicaCount": 1,
  "resourceGroup": "demo-westus",
  "sharedPrivateLinkResources": [],
  "sku": {
    "name": "standard"
  },
  "status": "running",
  "statusDetails": "",
  "tags": null,
  "type": "Microsoft.Search/searchServices"
}

az search service delete menghapus layanan dan datanya.

az search service delete --name <service-name> \
                         --resource-group  <search-service-resource-group-name> \

Membuat layanan dengan aturan IP

Bergantung pada persyaratan keamanan, Anda mungkin ingin membuat layanan pencarian dengan firewall IP yang dikonfigurasi. Untuk melakukannya, berikan alamat Public IP (v4) atau rentang CIDR ke argumen seperti ip-rules yang ditunjukkan di bawah ini. Aturan harus dipisahkan oleh koma (,) atau titik koma (;).

az search service create \
    --name <search-service-name> \
    --resource-group <search-service-resource-group-name> \
    --sku Standard \
    --partition-count 1 \
    --replica-count 1 \
    --ip-rules "55.5.63.73;52.228.215.197;101.37.221.205"

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 --identity-type SystemAssigned ke perintah.

az search service create \
    --name <search-service-name> \
    --resource-group <search-service-resource-group-name> \
    --sku Standard \
    --partition-count 1 \
    --replica-count 1 \
    --identity-type SystemAssigned

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, silakan lihat dokumentasi tentang 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.

az search service create \
    --name <search-service-name> \
    --resource-group <search-service-resource-group-name> \
    --sku Standard \
    --partition-count 1 \
    --replica-count 1 \
    --public-access Disabled

Selanjutnya, buat jaringan virtual dan titik akhir privat.

# Create the virtual network
az network vnet create \
    --resource-group <vnet-resource-group-name> \
    --location "West US" \
    --name <virtual-network-name> \
    --address-prefixes 10.1.0.0/16 \
    --subnet-name <subnet-name> \
    --subnet-prefixes 10.1.0.0/24

# Update the subnet to disable private endpoint network policies
az network vnet subnet update \
    --name <subnet-name> \
    --resource-group <vnet-resource-group-name> \
    --vnet-name <virtual-network-name> \
    --disable-private-endpoint-network-policies true

# Get the id of the search service
id=$(az search service show \
    --resource-group <search-service-resource-group-name> \
    --name <search-service-name> \
    --query [id] \
    --output tsv)

# Create the private endpoint
az network private-endpoint create \
    --name <private-endpoint-name> \
    --resource-group <private-endpoint-resource-group-name> \
    --vnet-name <virtual-network-name> \
    --subnet <subnet-name> \
    --private-connection-resource-id $id \
    --group-id searchService \
    --connection-name <private-link-connection-name>

Terakhir, buat zona DNS privat.

## Create private DNS zone
az network private-dns zone create \
    --resource-group <private-dns-resource-group-name> \
    --name "privatelink.search.windows.net"

## Create DNS network link
az network private-dns link vnet create \
    --resource-group <private-dns-resource-group-name> \
    --zone-name "privatelink.search.windows.net" \
    --name "myLink" \
    --virtual-network <virtual-network-name> \
    --registration-enabled false

## Create DNS zone group
az network private-endpoint dns-zone-group create \
   --resource-group <private-endpoint-resource-group-name>\
   --endpoint-name <private-endpoint-name> \
   --name "myZoneGroup" \
   --private-dns-zone "privatelink.search.windows.net" \
   --zone-name "searchServiceZone"

Untuk informasi selengkapnya tentang membuat titik akhir privat di Azure CLI, lihat Panduan Memulai Private Link ini.

Mengelola sambungan titik akhir privat

Selain membuat koneksi titik akhir privat, Anda bisa show, update, dan delete koneksi tersebut.

Untuk menampilkan koneksi titik akhir privat dan melihat statusnya, gunakan az search private-endpoint-connection show.

az search private-endpoint-connection show \
    --name <pe-connection-name> \
    --service-name <search-service-name> \
    --resource-group <search-service-resource-group-name>

Untuk memperbarui koneksi, gunakan az search private-endpoint-connection update. Contoh berikut menetapkan koneksi titik akhir privat menjadi ditolak:

az search private-endpoint-connection update \
    --name <pe-connection-name> \
    --service-name <search-service-name> \
    --resource-group <search-service-resource-group-name> 
    --status Rejected \
    --description "Rejected" \
    --actions-required "Please fix XYZ"

Untuk menghapus koneksi private endpoint, gunakan az search private-endpoint-connection delete.

az search private-endpoint-connection delete \
    --name <pe-connection-name> \
    --service-name <search-service-name> \
    --resource-group <search-service-resource-group-name>

Membuat layanan dengan komputasi rahasia

Komputasi rahasia adalah jenis komputasi opsional untuk perlindungan penggunaan data. Saat dikonfigurasi, layanan pencarian Anda disebarkan pada VM rahasia (DCasv5 atau DCesv5) alih-alih VM standar. Jenis komputasi ini juga dikenakan surcharge sebesar 10% untuk tingkatan yang bisa ditagihkan. Untuk informasi lebih lanjut, lihat halaman harga.

Untuk penggunaan harian, komputasi rahasia tidak diperlukan. Kami hanya merekomendasikan jenis komputasi ini untuk persyaratan peraturan, kepatuhan, atau keamanan yang ketat. Untuk informasi selengkapnya, lihat Kasus penggunaan komputasi rahasia.

Jenis komputasi ditetapkan untuk masa operasional layanan pencarian Anda. Untuk mengonfigurasi komputasi rahasia secara permanen, atur properti ke compute-typeconfidential pada layanan baru.

az search service create \
  --name <search-service-name> \
  --resource-group <search-service-resource-group-name> \
  --location <search-service-region> \
  --sku basic \
  --compute-type confidential

Menghasilkan ulang kunci admin

Untuk memperbarui kunci API admin, gunakan az search admin-key renew. 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.

Layanan ini menghasilkan nilai untuk kunci API. 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.

az search admin-key renew \
    --resource-group <search-service-resource-group-name> \
    --service-name <search-service-name> \
    --key-kind primary

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

{
  "primaryKey": <alphanumeric-guid>,
  "secondaryKey": <alphanumeric-guid>  
}

Membuat atau menghapus kunci kueri

Untuk membuat kunci API kueri untuk akses baca-saja dari aplikasi klien ke indeks Pencarian Azure AI, gunakan az search query-key create. 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.

az search query-key create \
    --name myQueryKey \
    --resource-group <search-service-resource-group-name> \
    --service-name <search-service-name>

Menskalakan replika dan partisi

Untuk menambah atau mengurangi replika dan partisi, gunakan pembaruan layanan pencarian az. 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.

az search service update \
    --name <search-service-name> \
    --resource-group <search-service-resource-group-name> \
    --partition-count 6 \
    --replica-count 6

Selain memperbarui jumlah replika dan partisi, Anda juga dapat memperbarui ip-rules, public-access, dan identity-type.

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.

Untuk membuat sumber daya tautan privat bersama, gunakan perintah az search shared-private-link-resource create. Perlu diingat bahwa beberapa konfigurasi mungkin diperlukan untuk sumber data sebelum menjalankan perintah ini.

az search shared-private-link-resource create \
    --name <spl-name> \
    --service-name <search-service-name> \
    --resource-group <search-service-resource-group-name> \
    --group-id blob \
    --resource-id "/subscriptions/<alphanumeric-subscription-ID>/resourceGroups/<resource-group-name>/providers/Microsoft.Storage/storageAccounts/myBlobStorage"  \
    --request-message "Please approve"

Untuk mengambil sumber daya tautan privat bersama dan melihat statusnya, gunakan az search shared-private-link-resource list.

az search shared-private-link-resource list \
    --service-name <search-service-name> \
    --resource-group <search-service-resource-group-name>

Anda perlu menyetujui koneksi dengan perintah berikut sebelum dapat digunakan. ID koneksi titik akhir privat harus diambil dari sumber daya anak. Dalam hal ini, kita mendapatkan ID sambungan dari penyimpanan Azure.

id = (az storage account show -n myBlobStorage --query "privateEndpointConnections[0].id")

az network private-endpoint-connection approve --id $id

Untuk menghapus sumber daya tautan privat yang dibagikan, gunakan az search shared-private-link-resource delete.

az search shared-private-link-resource delete \
    --name <spl-name> \
    --service-name <search-service-name> \
    --resource-group <search-service-resource-group-name>

Untuk informasi selengkapnya tentang menyiapkan sumber daya tautan privat bersama, lihat membuat koneksi pengindeks melalui endpoint privat.

Langkah berikutnya

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

  • Last updated on