REST API'lerini kullanarak Azure Yapay Zeka Arama hizmetinizi yönetme

Not

Azure Yapay Zeka Arama Azure portalı, REST API'leri ve Azure SDK’ları aracılığıyla kullanılabilir. Ayrıca kuruluş içeriğini Microsoft Foundry portalındaki aracılar için yeniden kullanılabilir, izin kullanan bilgi bankalarına dönüştüren yönetilen bilgi katmanı Foundry IQ'yu temel alır.

Management REST API'lerini kullanarak bir Azure Yapay Zeka 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
• Hizmeti yükseltme
• Fiyatlandırma katmanlarını değiştirme
• Veri düzlemi için rol tabanlı erişim denetimini yapılandırma
• Gizli bilgi işlemenin yapılandırılması
• Azure veri düzlemi için rol tabanlı erişim denetimini etkinleştir
• Müşteri tarafından yönetilen anahtar ilkesini zorunlu kılma
• 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 hizmetini 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.

Ipucu

Yönetim REST API'sini çağırmak için CURL kullanıyorsanız, bir içerik türü üst bilgisini application/json: olarak ayarladığınızdan emin olun. -H "Content-Type: application/json" Alternatif olarak, JSON eklemek istiyorsanız bayrağını kullanabilirsiniz --JSON .

Önkoşullar

• Etkin aboneliği olan bir Azure hesabı. Ücretsiz bir hesap oluşturun.

• REST istemcisi ile Visual Studio Code.

• Aşağıdaki adımlarda açıklandığı gibi erişim belirteci almak için Azure CLI. Azure aboneliğinizde sahip veya yönetici olmanız gerekir.

  Yönetim REST API çağrılarının kimliği Microsoft Entra ID aracılığıyla doğrulanır. İstekte bir erişim belirteci ve kaynak oluşturma ve yapılandırma izinleri sağlamanız gerekir. Azure CLI ek olarak, erişim belirteci oluşturmak için Azure PowerShell kullanabilirsiniz.

  1. Azure CLI için bir komut satırı açın.

  2. Azure aboneliğinizde oturum açın. Birden çok kiracınız veya aboneliğiniz varsa doğru kiracıyı seçtiğinizden emin olun.

     az login
     

  3. Kiracı kimliğini ve abonelik kimliğini alın.

     az account show
     

  4. Erişim belirteci alın.

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

     Kiracı kimliğiniz, abonelik kimliğiniz ve taşıyıcı belirteç bulundurmanız gereklidir. Bu değerleri sonraki adımda oluşturduğunuz (.rest veya .http) dosyasına yapıştıracaksınız.

Visual Studio Code'u Kurun

Visual Studio Code için REST istemcisi hakkında bilginiz yoksa, bu makaledeki görevleri tamamlayabilmeniz için bu bölüm kurulumu içerir.

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

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

   

3. Yeni bir .rest veya .http dosya uzantısına sahip dosyayı açın veya oluşturun.

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

   @tenant-id = PUT-YOUR-TENANT-ID-HERE
   @subscription-id = PUT-YOUR-SUBSCRIPTION-ID-HERE
   @token = PUT-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/{{subscription-id}}/providers/Microsoft.Search/searchServices?api-version=2025-05-01  HTTP/1.1
         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 = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

PUT https://management.azure.com/subscriptions/{{subscription-id}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-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"
        }
      }

Hizmeti yükseltme

Bazı Azure Yapay Zeka Arama özellikleri yalnızca yeni hizmetler tarafından kullanılabilir. Hizmet rekreasyonundan kaçınmak ve bu özellikleri mevcut bir hizmete getirmek için hizmetinizi yükseltebilirsiniz.

### Upgrade a search service
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

POST https://management.azure.com/subscriptions/{{subscription-id}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}/upgrade?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

Fiyatlandırma katmanlarını değiştirme

Daha fazla veya daha az kapasiteye ihtiyacınız varsa farklı bir fiyatlandırma katmanına geçebilirsiniz. Şu anda yalnızca Temel ve Standart (S1, S2 ve S3) katmanları arasında geçiş yapabilirsiniz. sku Yeni katmanı belirtmek için özelliğini kullanın.

### Change pricing tiers
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

PATCH https://management.azure.com/subscriptions/{{subscription-id}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

    {
        "sku": {
            "name": "standard2"
        }
    }

S3HD hizmeti oluşturma

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

### Create an S3HD service
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

PUT https://management.azure.com/subscriptions/{{subscription-id}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-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ı

Arama hizmetinizi OAuth2 erişim belirteci sağlayan veri isteklerinde yetkilendirme üst bilgisini tanıyacak şekilde yapılandırın.

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

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

### Configure role-based access
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

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

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

Gizli bilgi işlem yapılandırması

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 fiyatlandırma sayfasına bakın.

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 computeType özelliğini confidential olarak yeni bir hizmette ayarlayın.

### Configure confidential computing
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE
PUT https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-01  HTTP/1.1
    Content-type: application/json
    Authorization: Bearer {{token}}
    {
        "location": "{{region}}",
        "sku": {
            "name": "basic"
        },
        "properties": {
            "computeType": "confidential"
        }
    }

Müşteri tarafından yönetilen anahtar politikasını 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 veri kaynağındaki bağlantı dizesi gibi hassas veriler içeren nesneler oluşturan rest çağrıları, şifreleme anahtarı sağlanmazsa başarısız olur: "Error creating Data Source: "CannotCreateNonEncryptedResource: The creation of non-encrypted DataSources is not allowed when encryption policy is enforced."

### Enforce a customer-managed key policy
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

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

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

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

### Disable external access
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

PATCH https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}
     
     {
        "properties": {
            "publicNetworkAccess": "Disabled"
        }
    }

Arama hizmetini silme

### Delete a search service
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

DELETE https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

Yönetici API anahtarlarını listeleme

### List admin keys
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

POST https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}/listAdminKeys?api-version=2025-05-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
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

POST https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}/regenerateAdminKey/primary?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

Sorgu API anahtarları oluşturma

### Create a query key
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE
@query-key = PUT-YOUR-QUERY-KEY-NAME-HERE

POST https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}/createQueryKey/{query-key}?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

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

### List private endpoint connections
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

GET https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}/privateEndpointConnections?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

Arama işlemlerini listeleme

### List search operations
GET https://management.azure.com/subscriptions/{{subscription-id}}/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ınız dizin oluşturma veya dizin sorgulama Azure portalını, REST API'lerini veya Azure SDK kullanarak içerir.

• Azure portalında Azure Yapay Zeka Arama dizini oluşturun
• Diğer hizmetlerden veri yüklemek için dizin oluşturucu ayarlama
• Azure portalında Arama gezginini kullanarak bir Azure Yapay Zeka Arama dizinini sorgulama
• .NET