Mengelola layanan Pencarian Azure AI Anda dengan Azure CLI

  • Artikel

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

Gunakan modul pencarian az untuk melakukan tugas-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 pencarian az. Jika Anda ingin menggunakan fitur pratinjau, gunakan Rest API Manajemen dan versi API pratinjau.

Prasyarat

Versi Azure CLI tercantum di GitHub.

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

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 jumlah layanan pencarian yang sudah dibuat, perintah ini mengembalikan informasi tersebut, menghemat perjalanan Anda ke portal.

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 Search services, admin keys and query keys.
        WARNING: This command group is in preview and under development. Reference and support
        levels: https://aka.ms/CLI_refstatus
Subgroups:
    admin-key                    : Manage Azure Search admin keys.
    private-endpoint-connection  : Manage Azure Search private endpoint connections.
    private-link-resource        : Manage Azure Search private link resources.
    query-key                    : Manage Azure Search query keys.
    service                      : Manage Azure Search services.
    shared-private-link-resource : Manage Azure Search shared private link resources.

For more specific examples, use: az find "az search"

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 acara layanan pencarian az untuk mengembalikan definisi layanan, termasuk nama, wilayah, tingkat, 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

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, silakan lihat dokumentasi tentang membuat titik akhir privat untuk Azure AI Search.

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 Mulai Cepat Private Link ini.

Mengelola sambungan titik akhir privat

Selain membuat koneksi titik akhir privat, Anda juga dapat show, update, dan delete koneksi.

Untuk mengambil koneksi titik akhir privat dan untuk melihat statusnya, gunakan tampilkan az search private-endpoint-connection.

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 pembaruan az search private-endpoint-connection. 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 titik akhir privat, gunakan hapus az search private-endpoint-connection.

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

Meregenerasi kunci admin

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

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 demi satu.

{
  "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 Azure AI Search, 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 Azure AI Search 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 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.

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

Untuk membuat sumber daya tautan privat bersama, gunakan buat az search shared-private-link-resource. 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 daftar az search shared-private-link-resource .

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 koneksi dari penyimpanan az.

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 bersama, gunakan hapus az search shared-private-link-resource.

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 titik akhir privat.

Langkah berikutnya

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