Aracılığıyla paylaş

Azure CLI kullanarak Azure AI Search hizmetinizi yönetme

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.

Bir hizmetin adını veya bölgesini program aracılığıyla veya Azure portalında değiştiremezsiniz. Bir hizmet oluşturulduğunda, ayrılmış kaynaklar tahsis edilir, bu nedenle altyapı donanımının (konumunun veya düğüm türünün) değiştirilmesi için yeni bir hizmet gerekir.

Uyarı

Arama Yönetimi REST API'leri ve Azure portalı fiyatlandırma katmanınızı değiştirmeyi destekler. Şu anda yalnızca Temel ve Standart (S1, S2 ve S3) katmanları arasında geçiş yapabilirsiniz.

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'i kullanmaya başlama.

  • 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 kullanarak Azure'da kimlik doğrulaması.

    • İ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 ve yönetme.

    • 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 Azure portalına gitmenize gerek kalmadan size yardımcı olur.

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

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 ip-rules argümanına 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, komuta --identity-type SystemAssigned ekleyerek yapılır.

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.

Önce, PublicNetworkAccess olarak ayarlanan Disabled ile bir arama hizmeti dağıtın.

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, bağlantıyı show, update ve delete yapabilirsiniz.

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

Gizli bilgi işlem ile hizmet oluşturma

Gizli bilgi işlem , kullanımdaki verilerin korunması için isteğe bağlı bir işlem türüdür. Yapılandırıldığında, arama hizmetiniz standart VM'ler yerine gizli VM'lere (DCasv5 veya DCesv5) dağıtılır. Bu işlem türü ayrıca faturalanabilir katmanlar için 10% ek ücrete tabidir. Daha fazla bilgi için bkz. fiyatlandırma sayfası.

Günlük kullanım için gizli bilgi işlem gerekli değildir. Bu işlem türünü yalnızca sıkı mevzuat, uyumluluk veya güvenlik gereksinimleri için öneririz. Daha fazla bilgi için bkz . Gizli bilgi işlem kullanım örnekleri.

İşlem türü, arama hizmetinizin ömrü boyunca sabittir. Gizli bilgi işlem özelliğini kalıcı olarak yapılandırmak için, yeni bir hizmette compute-type özelliğini confidential olarak ayarlayın.

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

Yönetici anahtarlarını yeniden oluşturma

Yönetici API anahtarlarını yenilemek 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.

Yalnızca bir kerede bir anahtarı yeniden oluşturabilirsiniz: ya primary anahtarını ya da secondary anahtarını belirtmelisiniz. 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 azure portalı üzerinden 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 referanslar, ya primary ya da secondary şeklinde sabit 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 anahtarları oluşturmak amacıyla `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>

Replikaları 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ı, hem sabit hem de değişken ücretler içeren fatura üzerinde artışa yol açar. 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, ip-rules, public-access, ve identity-type değerlerini de güncelleştirebilirsiniz.

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 kaynak öğesinden 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

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

  • Last updated on