Azure CLI ile Azure AI Arama hizmeti yönetme

  • Makale

Azure AI Search oluşturmak ve yapılandırmak için Azure CLI komutlarını ve betiklerini Windows, macOS, 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.

Sunucu adını, bölgesini veya katmanını program aracılığıyla veya portalda değiştiremezsiniz. Ayrılmış kaynaklar hizmet oluşturulduğunda ayrılır. Bu nedenle, temel alınan donanımın (konum veya düğüm türü) değiştirilmesi yeni bir hizmet gerektirir.

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

Önkoşullar

  • Azure Cloud Shell'de Bash ortamını kullanın. Daha fazla bilgi için bkz . Azure Cloud Shell'de Bash için hızlı başlangıç.

  • CLI başvuru komutlarını yerel olarak çalıştırmayı tercih ediyorsanız Azure CLI'yı yükleyin . Windows veya macOS üzerinde çalışıyorsanız Azure CLI’yi bir Docker kapsayıcısında çalıştırmayı değerlendirin. Daha fazla bilgi için bkz . Docker kapsayıcısında Azure CLI'yi çalıştırma.

    • Yerel yükleme kullanıyorsanız az login komutunu kullanarak Azure CLI ile oturum açın. Kimlik doğrulama işlemini tamamlamak için terminalinizde görüntülenen adımları izleyin. Diğer oturum açma seçenekleri için bkz . Azure CLI ile oturum açma.

    • İstendiğinde, ilk kullanımda Azure CLI uzantısını yükleyin. Uzantılar hakkında daha fazla bilgi için bkz. Azure CLI ile uzantıları kullanma.

    • Yüklü sürümü ve bağımlı kitaplıkları bulmak için az version komutunu çalıştırın. En son sürüme yükseltmek için az upgrade komutunu çalıştırın.

Azure CLI sürümleri GitHub'da listelenir.

az search modülü, Azure CLI'yi tam eşlikle Arama Yönetimi REST API'lerinin kararlı sürümlerine genişletir.

Abonelikteki hizmetleri listeleme

Aşağıdaki komutlar az resource komutundan alınıp aboneliğinizde zaten sağlanan mevcut kaynaklar ve hizmetler hakkında bilgi döndürür. Daha önce kaç arama hizmetinin oluşturulduğunu bilmiyorsanız, bu komutlar bu bilgileri döndürerek portala bir yolculuk yapmanızı sağlar.

İlk komut tüm arama hizmetlerini döndürür.

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

Hizmetler listesinden belirli bir kaynakla ilgili bilgileri döndürebilirsiniz.

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

Tüm az search komutlarını listele

CLI içinden az search'te kullanılabilen alt gruplar ve komutlarla ilgili bilgileri görüntüleyebilirsiniz. Alternatif olarak, belgeleri gözden geçirebilirsiniz.

içinde az searchkullanılabilen alt grupları görüntülemek için aşağıdaki komutu çalıştırın.

az search --help

Yanıt aşağıdaki çıkışa benzer görünmelidir.

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"

Her alt grupta birden çok komut vardır. Aşağıdaki satırı çalıştırarak alt grup için service kullanılabilir komutları görebilirsiniz.

az search service --help

Belirli bir komut için kullanılabilen bağımsız değişkenleri de görebilirsiniz.

az search service create --help

Arama hizmeti bilgilerini alma

Arama hizmetinizi içeren kaynak grubunu biliyorsanız ad, bölge, katman, çoğaltma ve bölüm sayıları dahil olmak üzere hizmet tanımını döndürmek için az search service show komutunu çalıştırın. Bu komut için arama hizmetini içeren kaynak grubunu sağlayın.

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

Hizmeti oluşturma veya silme

Yeni bir arama hizmeti oluşturmak için az search service create komutunu kullanın.

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

Sonuçlar aşağıdaki çıkışa benzer görünmelidir:

{
  "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 hizmeti ve verilerini kaldırır.

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

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, genel IP (v4) adreslerini veya CIDR aralıklarını aşağıda gösterildiği gibi bağımsız değişkene ip-rules geçirin. Kurallar virgülle (,) veya noktalı virgülle (; ) ayrılmalıdır.

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"

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. Bu, komutuna eklenerek --identity-type SystemAssigned gerçekleştirilir.

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

Ö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 lütfen Azure AI Search için özel uç nokta oluşturma belgelerine bakın.

Aşağıdaki örnekte özel uç nokta ile arama hizmetinin nasıl oluşturulacağı gösterilmektedir.

İlk olarak, olarak ayarlanmış bir arama hizmeti PublicNetworkAccess dağıtın 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

Ardından bir sanal ağ ve özel uç nokta oluşturun.

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

Son olarak, özel bir DNS Bölgesi oluşturun.

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

Azure CLI'da ö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 , updateve delete bağlantısını da showoluşturabilirsiniz.

Özel uç nokta bağlantısını almak ve durumunu görmek için az search private-endpoint-connection show komutunu kullanın.

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

Bağlantıyı güncelleştirmek için az search private-endpoint-connection update komutunu kullanın. Aşağıdaki örnek, özel uç nokta bağlantısını reddedildi olarak ayarlar:

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"

Özel uç nokta bağlantısını silmek için az search private-endpoint-connection delete komutunu kullanın.

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

Yönetici anahtarlarını yeniden oluşturma

Yönetici API anahtarlarını almak için az search admin-key renew komutunu kullanın. 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.

Veya anahtarı olarak primary secondary belirtilen 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 kaçı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 portaldan 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. Anahtara başvurular veya primary secondarysabit dizelerdir.

az search admin-key renew \
    --resource-group <search-service-resource-group-name> \
    --service-name <search-service-name> \
    --key-kind 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.

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

Sorgu anahtarlarını oluşturma veya silme

İstemci uygulamalarından Azure AI Search dizinine salt okunur erişim için sorgu API'leri anahtarları oluşturmak için az search query-key create komutunu kullanın. 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.

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

Çoğaltmaları ve bölümleri ölçeklendirme

Çoğaltmaları ve bölümleri artırmak veya azaltmak için az search service update komutunu kullanın. Çoğaltmaların veya bölümlerin artırılması, faturanıza hem sabit hem de değişken ücretler içeren ekler. Daha fazla işleme gücü için geçici bir ihtiyacınız varsa, iş yükünü işlemek 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.

Kaynak oluşturmanı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 artımlı olarak azaltmayı, bir kerede bir çoğaltmayı ve bölümü azaltmayı 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.

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

Çoğaltma ve bölüm sayılarını güncelleştirmenin yanı sıra , public-accessve identity-typedeğerlerini de güncelleştirebilirsinizip-rules.

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.

Paylaşılan özel bağlantı kaynağını oluşturmak için az search shared-private-link-resource create komutunu kullanın. Bu komutu çalıştırmadan önce veri kaynağı için bazı yapılandırmalar gerekebileceğini unutmayın.

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"

Paylaşılan özel bağlantı kaynaklarını almak ve bunların durumunu görüntülemek için az search shared-private-link-resource list komutunu kullanın.

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

Kullanılabilmesi için önce aşağıdaki komutla bağlantıyı onaylamanız gerekir. Özel uç nokta bağlantısının kimliği alt kaynaktan alınmalıdır. Bu durumda, az storage'dan bağlantı kimliğini alacağız.

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

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

Paylaşılan özel bağlantı kaynağını silmek için az search shared-private-link-resource delete komutunu kullanın.

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

Paylaşılan özel bağlantı kaynaklarını ayarlama hakkında daha fazla bilgi için bkz . Özel uç nokta üzerinden dizin oluşturucu bağlantıları oluşturma.

Sonraki adımlar

Bir dizin oluşturun, portalı, REST API'leri veya .NET SDK'sını kullanarak bir dizini sorgular.