REST API'leri ile Azure AI Arama hizmeti yönetme

• Portal
• PowerShell
• Azure CLI
• REST API

Bu makalede, Yönetim REST API'lerini kullanarak Azure AI Arama hizmeti oluşturmayı ve yapılandırmayı öğrenin. Yalnızca Yönetim REST API'lerinin önizleme özelliklerine erken erişim sağlaması garanti edilir.

Yönetim REST API'sini kararlı ve önizleme sürümlerinde kullanabilirsiniz. Önizleme özelliklerine erişiyorsanız önizleme API'sini ayarladığınızdan emin olun.

• Hizmet oluşturma veya güncelleştirme
• Veri düzlemi için Azure rol tabanlı erişim denetimini etkinleştirme
• Müşteri tarafından yönetilen anahtar ilkesini zorunlu kılma
• Anlam derecesini devre dışı bırakma
• Dış kaynaklara veri gönderen iş yüklerini devre dışı bırakma
• Sorgu anahtarı oluşturma
• Yönetici anahtarını yeniden oluşturma
• Özel uç nokta bağlantılarını listeleme
• Arama işlemlerini listeleme
• Arama hizmetlerini silme

Tüm Yönetim REST API'lerinin örnekleri vardır. Bu makalede bir görev ele alınmıyorsa bunun yerine API başvurusuna bakın.

Önkoşullar

• Azure aboneliği - Ücretsiz bir abonelik oluşturun.

• REST istemcisi ile Visual Studio Code.

• Erişim belirteci almak için kullanılan Azure CLI . Azure aboneliğinizde sahip veya yönetici olmanız gerekir.

Bir erişim belirteci alma

Yönetim REST API çağrılarının kimliği Microsoft Entra Kimliği aracılığıyla doğrulanır. kaynak oluşturma ve yapılandırma izinleriyle birlikte istekte bir erişim belirteci sağlamanız gerekir.

Erişim belirteci oluşturmak için Azure CLI veya Azure PowerShell kullanabilirsiniz.

1. Azure CLI için bir komut kabuğu açın.

2. Azure aboneliğinizde oturum açın.

   az login
   

3. Kiracı kimliğini ve abonelik kimliğini alın. Birden çok kiracınız veya aboneliğiniz varsa doğru kiracıyı kullandığınızdan emin olun.

   az account show
   

4. Erişim belirteci alma.

   az account get-access-token --query accessToken --output tsv
   

Kiracı kimliğiniz, abonelik kimliğiniz ve taşıyıcı belirtecimiz olmalıdır. Bu değerleri .rest sonraki adımda oluşturduğunuz veya .http dosyasına yapıştıracaksınız.

Visual Studio Code'u ayarlama

Visual Studio Code için REST istemcisi hakkında bilginiz yoksa, bu bölüm bu hızlı başlangıçta görevleri tamamlayabilmeniz için kurulumu içerir.

1. Visual Studio Code'ı başlatın ve Uzantılar kutucuğunu seçin.

2. REST istemcisini arayın ve Yükle'yi seçin.

   

3. veya dosya uzantısıyla adlı yeni bir .rest dosya açın veya .http oluşturun.

4. Önceki adımda aldığınız değerler için değişkenler sağlayın.

   @tenantId = PASTE-YOUR-TENANT-ID-HERE
   @subscriptionId = PASTE-YOUR-SUBSCRIPTION-ID-HERE
   @token = PASTE-YOUR-TOKEN-HERE
   

5. Aboneliğinizdeki arama hizmetlerini listeleyerek oturumun çalışır durumda olduğunu doğrulayın.

    ### List search services
    GET https://management.azure.com/subscriptions/{{subscriptionId}}/providers/Microsoft.Search/searchServices?api-version=2023-11-01
         Content-type: application/json
         Authorization: Bearer {{token}}
   

6. İstek gönder’i seçin. Bir yanıt bitişik bir bölmede görünmelidir. Mevcut arama hizmetleriniz varsa bunlar listelenir. Aksi takdirde liste boş olur, ancak HTTP kodu 200 Tamam olduğu sürece sonraki adımlara hazır olursunuz.

   HTTP/1.1 200 OK
   Cache-Control: no-cache
   Pragma: no-cache
   Content-Length: 22068
   Content-Type: application/json; charset=utf-8
   Expires: -1
   x-ms-ratelimit-remaining-subscription-reads: 11999
   x-ms-request-id: f47d3562-a409-49d2-b9cd-6a108e07304c
   x-ms-correlation-request-id: f47d3562-a409-49d2-b9cd-6a108e07304c
   x-ms-routing-request-id: WESTUS2:20240314T012052Z:f47d3562-a409-49d2-b9cd-6a108e07304c
   Strict-Transport-Security: max-age=31536000; includeSubDomains
   X-Content-Type-Options: nosniff
   X-Cache: CONFIG_NOCACHE
   X-MSEdge-Ref: Ref A: 12401F1160FE4A3A8BB54D99D1FDEE4E Ref B: CO6AA3150217011 Ref C: 2024-03-14T01:20:52Z
   Date: Thu, 14 Mar 2024 01:20:52 GMT
   Connection: close
   
   {
     "value": [ . . . ]
   }
   

Hizmet oluşturma veya güncelleştirme

Geçerli abonelik altında bir arama hizmeti oluşturur veya güncelleştirir. Bu örnekte, arama hizmeti adı ve bölgesi için henüz tanımlanmamış değişkenler kullanılmaktadır. Adları doğrudan sağlayın veya koleksiyona yeni değişkenler ekleyin.

### Create a search service (provide an existing resource group)
@resource-group = my-rg
@search-service-name = my-search
PUT https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

    {
        "location": "North Central US",
        "sku": {
            "name": "basic"
        },
        "properties": {
            "replicaCount": 1,
            "partitionCount": 1,
            "hostingMode": "default"
        }
      }

S3HD hizmeti oluşturma

S3HD hizmeti oluşturmak için ve hostingMode özelliklerinin birleşimini sku kullanın. olarak standard3 ve "hostingMode" değerini olarak HighDensityayarlayınsku.

@resource-group = my-rg
@search-service-name = my-search
PUT https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

    {
        "location": "{{region}}",
        "sku": {
          "name": "standard3"
        },
        "properties": {
          "replicaCount": 1,
          "partitionCount": 1,
          "hostingMode": "HighDensity"
        }
    }

Veri düzlemi için rol tabanlı erişimi yapılandırma

Şunlar için geçerlidir: Arama Dizini Veri Katkıda Bulunanı, Arama Dizini Veri Okuyucusu, Arama Hizmeti Katkıda Bulunanı

Bu adımda, arama hizmetinizi OAuth2 erişim belirteci sağlayan veri isteklerindeki yetkilendirme üst bilgisini tanıyacak şekilde yapılandırın.

Veri düzlemi işlemleri için rol tabanlı erişim denetimini kullanmak için olarak ayarlayın authOptions aadOrApiKey ve isteği gönderin.

Rol tabanlı erişim denetimini özel olarak kullanmak için, ikinci bir isteği izleyerek API anahtarı kimlik doğrulamasını kapatın ve bu kez true olarak ayarlayın disableLocalAuth .

PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

    {
        "properties": {
            "disableLocalAuth": false,
            "authOptions": {
                "aadOrApiKey": {
                    "aadAuthFailureMode": "http401WithBearerChallenge"
                }
            }
        }
    }

Müşteri tarafından yönetilen anahtar ilkesini zorunlu kılma

Müşteri tarafından yönetilen şifreleme kullanıyorsanız, arama hizmetinin uyumluluk durumunu bildirmesini istiyorsanız "zorlama" ayarı "Etkin" olarak ayarlanmış "encryptionWithCMK" özelliğini etkinleştirebilirsiniz.

Bu ilkeyi etkinleştirdiğinizde, bir şifreleme anahtarı sağlanmazsa, veri kaynağı içindeki bağlantı dizesi gibi hassas veriler içeren nesneler oluşturan rest çağrıları başarısız olur:"Error creating Data Source: "CannotCreateNonEncryptedResource: The creation of non-encrypted DataSources is not allowed when encryption policy is enforced."

PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}
     
     {
        "properties": {
            "encryptionWithCmk": {
                "enforcement": "Enabled"
            }
        }
    }

Anlam derecesini devre dışı bırakma

Semantik dereceleyici varsayılan olarak etkinleştirilmemiş olsa da, kullanılamayacağından emin olmak için özelliği hizmet düzeyinde kilitleyebilirsiniz.

### disable semantic ranker
PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}
     
     {
        "properties": {
            "semanticSearch": "Disabled"
        }
    }

Dış kaynaklara veri gönderen iş yüklerini devre dışı bırakma

Azure AI Search bilgi depolarını güncelleştirirken, hata ayıklama oturum durumunu kaydederken veya zenginleştirmeleri önbelleğe alırken dış veri kaynaklarına yazar. Aşağıdaki örnek, bu iş yüklerini hizmet düzeyinde devre dışı bırakır.

### disable-external-access
PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}
     
     {
        "properties": {
            "publicNetworkAccess": "Disabled"
        }
    }

Arama hizmetini silme

### delete a search service
DELETE https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

Yönetici API anahtarlarını listeleme

### List admin keys
POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}/listAdminKeys?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

Yönetici API anahtarlarını yeniden oluşturma

Aynı anda yalnızca bir yönetici API anahtarını yeniden oluşturabilirsiniz.

### Regnerate admin keys
POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}/regenerateAdminKey/primary?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

Sorgu API anahtarları oluşturma

### Create a query key
@query-key-name = myQueryKey
POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}/createQueryKey/{name}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

Özel uç nokta bağlantılarını listeleme

### List private endpoint connections
GET https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}/privateEndpointConnections?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

Arama işlemlerini listeleme

### List search operations
GET https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups?api-version=2021-04-01 HTTP/1.1
  Content-type: application/json
  Authorization: Bearer {{token}}

Sonraki adımlar

Bir arama hizmeti yapılandırıldıktan sonra sonraki adımlar arasında portal, REST API'leri veya Azure SDK kullanarak dizin oluşturma veya dizin sorgulama yer alır.

• Azure portalında Azure AI Search dizini oluşturma
• Diğer hizmetlerden veri yüklemek için dizin oluşturucu ayarlama
• Azure portalında Arama gezginini kullanarak Azure AI Search dizinini sorgulama
• .NET'te Azure AI Search'i kullanma