Yönetilen kimlik kullanarak arama hizmetini başka Azure kaynaklarına bağlama

Bir Azure AI Arama hizmeti, sistem tarafından atanan veya kullanıcı tarafından atanan yönetilen kimliği ve Azure rol atamasını kullanarak diğer Azure kaynaklarına bağlanacak şekilde yapılandırabilirsiniz. Yönetilen kimlikler ve rol atamaları, gizli dizileri ve kimlik bilgilerini bağlantı dizesi veya koda geçirme gereksinimini ortadan kaldırır.

Önkoşullar

• Temel katmanda veya üzerinde bir arama hizmeti.

• Geçerli bir rol ataması olan bir Microsoft Entra oturum açma hesabından gelen istekleri kabul eden bir Azure kaynağı.

Desteklenen senaryolar

Azure AI Search, Azure kaynaklarına giden bağlantılarda sistem tarafından atanan veya kullanıcı tarafından atanan yönetilen kimliği kullanabilir. Sistem tarafından yönetilen kimlik, bir bağlantı dizesi Microsoft Entra Kimliği kullanan bir hizmet veya uygulamanın benzersiz kaynak kimliği olduğunda belirtilir. Kullanıcı tarafından atanan yönetilen kimlik bir "identity" özelliği aracılığıyla belirtilir.

Arama hizmeti azure Depolama dizin oluşturucu veri kaynağı olarak ve hata ayıklama oturumları, zenginleştirme önbelleğe alma ve bilgi deposu için veri havuzu olarak kullanır. Depolama alanına geri yazan arama özellikleri için, yönetilen kimliğin "Rol atama" bölümünde açıklandığı gibi katkıda bulunan rolü ataması gerekir.

Senaryo	Sistem tarafından yönetilen kimlik	Kullanıcı tarafından atanan yönetilen kimlik (önizleme)
Desteklenen Azure veri kaynaklarınadizin oluşturucu bağlantıları 1,3	Yes	Yes
Müşteri tarafından yönetilen anahtarlar için Azure Key Vault	Yes	Yes
Oturumlarda hata ayıklama (Azure Depolama'de barındırılan)1	Yes	Hayır
Zenginleştirme önbelleği (Azure Depolama'de barındırılıyor)1,2	Yes	Yes
Bilgi Deposu (Azure Depolama'de barındırılıyor)1	Yes	Yes
Özel beceriler (Azure İşlevleri veya eşdeğerinde barındırılıyor)	Yes	Yes
Azure OpenAI ekleme becerisi	Yes	Yes
Azure OpenAI vektörleştiricisi	Yes	Yes

¹ Arama ve depolama arasındaki bağlantı için ağ güvenlik yapılandırmanız, hangi yönetilen kimlik türünü kullanabileceğiniz konusunda kısıtlamalar uygular. Güvenilen hizmet özel durumu veya kaynak örneği kuralı aracılığıyla depolamaya aynı bölge bağlantısı için yalnızca sistem tarafından yönetilen kimlik kullanılabilir. Ayrıntılar için bkz . Ağ korumalı depolama hesabına erişim.

² Zenginleştirme önbelleğini belirtmek için bir yöntem, Verileri içeri aktarma sihirbazındadır. Sihirbaz şu anda zenginleştirme önbelleği için yönetilen kimlik bağlantı dizesi kabul etmez. Ancak sihirbaz tamamlandıktan sonra, dizin oluşturucu JSON tanımındaki bağlantı dizesi sistem veya kullanıcı tarafından atanan yönetilen kimliği belirtecek şekilde güncelleştirebilir ve sonra dizin oluşturucuyu yeniden çalıştırabilirsiniz.

³ Azure depolama hesabında anahtarları devre dışı bırakmanın şu anda veri kaynağı olarak kullanılan Azure Tablosu için desteklenmediğini unutmayın. Yönetilen kimlik, depolama anahtarlarını açıkça sağlamamak için kullanılsa da, yapay zeka arama hizmeti yine de bu uygulama için anahtarları kullanır.

Sistem tarafından yönetilen kimlik oluşturma

Sistem tarafından atanan yönetilen kimlik etkinleştirildiğinde Azure, arama hizmetiniz için aynı kiracı ve abonelik içindeki diğer Azure hizmetlerinde kimlik doğrulaması yapmak için kullanılabilecek bir kimlik oluşturur. Daha sonra bu kimliği dizin oluşturma sırasında verilere erişime izin veren Azure rol tabanlı erişim denetimi (Azure RBAC) atamalarında kullanabilirsiniz.

Sistem tarafından atanan yönetilen kimlik, arama hizmetinize özgüdür ve kullanım ömrü boyunca hizmete bağlıdır.

Azure portalı

1. Azure portalında oturum açın ve arama hizmetinizi bulun.

2. Ayarlar altında Kimlik'i seçin.

3. Sistem tarafından atanan sekmesinde, Durum'un altında Açık'ı seçin.

4. Kaydet'i seçin.

   

   Kaydettikten sonra, arama hizmetinize atanmış bir nesne tanımlayıcısı görürsünüz.

   

REST API

Bkz. Hizmet Oluşturma veya Güncelleştirme (Yönetim REST API'si).

Kullanıcı tarafından atanan bir yönetilen kimlik atamak için portal yerine Yönetim REST API'sini kullanabilirsiniz.

1. Arama hizmeti oluşturma veya güncelleştirme isteğini formüle etme.

   PUT https://management.azure.com/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.Search/searchServices/mysearchservice?api-version=2023-11-01
   {
     "location": "[region]",
     "sku": {
       "name": "[sku]"
     },
     "properties": {
       "replicaCount": [replica count],
       "partitionCount": [partition count],
       "hostingMode": "default"
     },
     "identity": {
       "type": "SystemAssigned"
     }
   } 
   

2. Onay ve sistem tarafından yönetilen kimlik için bir nesne tanımlayıcısı yanıtta döndürülür.

Azure PowerShell

Bkz. Sistem tarafından atanan yönetilen kimlikle (Azure PowerShell) arama hizmeti oluşturma.

Azure CLI

Bkz. Sistem tarafından atanan yönetilen kimlikle (Azure CLI) arama hizmeti oluşturma.

Kullanıcı tarafından atanan yönetilen kimlik oluşturma (önizleme)

Kullanıcı tarafından atanan yönetilen kimlik, Azure'da bulunan bir kaynaktır. Farklı uygulamalar ve senaryolar için ayrı kimlikler oluşturabildiğiniz için rol atamalarında daha fazla ayrıntı düzeyine ihtiyacınız varsa kullanışlıdır.

Önemli

Bu özellik, ek kullanım koşulları altında genel önizleme aşamasındadır. Kullanıcı tarafından atanan yönetilen kimlikler şu anda ağ korumalı depolama hesabına yapılan bağlantılar için desteklenmemektedir. Arama isteği şu anda bir genel IP adresi gerektiriyor.

Azure portalı

1. Azure portalda oturum açma

2. + Kaynak oluştur’u seçin.

3. "Arama hizmeti s ve market" arama çubuğunda "Kullanıcı Tarafından Atanan Yönetilen Kimlik" araması yapın ve Oluştur'u seçin.

   

4. Aboneliği, kaynak grubunu ve bölgeyi seçin. Kimliğe açıklayıcı bir ad verin.

5. Oluştur'u seçin ve kaynağın dağıtımı tamamlanmasını bekleyin.

   Sonraki birkaç adımda, kullanıcı tarafından atanan yönetilen kimliği arama hizmetinize atayacaksınız.

6. Arama hizmeti sayfanızdaki Ayarlar altında Kimlik'i seçin.

7. Kullanıcı tarafından atanan sekmesinde Ekle'yi seçin.

8. Aboneliği seçin ve ardından önceki adımda oluşturduğunuz kullanıcı tarafından atanan yönetilen kaynağı seçin.

REST API

Kullanıcı tarafından atanan bir yönetilen kimlik atamak için portal yerine Yönetim REST API'sini kullanabilirsiniz. Bu görev için 2021-04-01-preview sürümünü kullandığınızdan emin olun.

1. Arama hizmeti oluşturma veya güncelleştirme isteğini formüle etme.

   PUT https://management.azure.com/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.Search/searchServices/mysearchservice?api-version=2021-04-01-preview
   {
     "location": "[region]",
     "sku": {
       "name": "[sku]"
     },
     "properties": {
       "replicaCount": [replica count],
       "partitionCount": [partition count],
       "hostingMode": "default"
     },
     "identity": {
       "type": "UserAssigned",
       "userAssignedIdentities": {
         "/subscriptions/[subscription ID]/resourcegroups/[resource group name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[name of managed identity]": {}
       }
     }
   } 
   

2. Tam yönetilen kimlik belirtmek için "identity" özelliğini ayarlayın:

   • "type" kimlik türüdür. Geçerli değerler her ikisi için de "SystemAssigned", "UserAssigned" veya "SystemAssigned, UserAssigned" değerleridir. "Hiçbiri" değeri, arama hizmetinden daha önce atanmış tüm kimlikleri temizler.

   • "userAssignedIdentities", kullanıcı tarafından atanan yönetilen kimliğin ayrıntılarını içerir. Hizmeti Oluştur veya Güncelleştir isteğinde belirtebilmeniz için önce bu kimliğin zaten mevcut olması gerekir.

Güvenlik duvarı erişimine izin ver

Azure kaynağınız bir güvenlik duvarının arkasındaysa, arama hizmetinizden gelen istekleri kabul eden bir gelen kuralı olduğundan emin olun.

• Azure Blob Depolama veya Azure Data Lake Storage 2. Nesil ile aynı bölge bağlantıları için sistem tarafından yönetilen bir kimlik ve güvenilen hizmet özel durumu kullanın. İsteğe bağlı olarak, istekleri kabul etmek için bir kaynak örneği kuralı yapılandırabilirsiniz.

• Diğer tüm kaynaklar ve bağlantılar için, Arama'dan gelen istekleri kabul eden bir IP güvenlik duvarı kuralı yapılandırın. Ayrıntılar için bkz . Azure ağ güvenliği özellikleri tarafından korunan içeriğe dizin oluşturucu erişimi.

Rol atama

Yönetilen kimlik, Azure kaynağı üzerindeki izinleri belirleyen bir Azure rolüyle eşlenmelidir.

• Dizin oluşturucu veri bağlantıları ve Azure Key Vault'ta müşteri tarafından yönetilen bir anahtara erişmek için veri okuyucu izinleri gereklidir.

• Bir bilgi deposunda hata ayıklama oturumu verilerini barındırmak, zenginleştirme önbelleğini ve uzun süreli içerik depolamayı barındırmak için Azure Depolama kullanan yapay zeka zenginleştirme özellikleri için katkıda bulunan (yazma) izinleri gereklidir.

Aşağıdaki adımlar Azure Depolama içindir. Kaynağınız Azure Cosmos DB veya Azure SQL ise, adımlar benzerdir.

1. Azure portalında oturum açın ve arama hizmetinin erişmesi gereken Azure kaynağınızı bulun.

2. Azure Depolama'da sol gezinti bölmesinde Erişim denetimi (AIM) öğesini seçin.

3. Rol ataması ekle’yi seçin.

4. Rol sayfasında, arama hizmetiniz için gereken rolleri seçin:

   Görev	Rol ataması
   Dizin oluşturucu kullanarak blob dizin oluşturma	Depolama Blob Veri Okuyucusu Ekleme
   Dizin oluşturucu kullanarak ADLS 2. Nesil dizin oluşturma	Depolama Blob Veri Okuyucusu Ekleme
   Dizin oluşturucu kullanarak tablo dizin oluşturma	Okuyucu ve Veri Erişimi Ekleme
   Dizin oluşturucu kullanarak dosya dizini oluşturma	Okuyucu ve Veri Erişimi Ekleme
   Bilgi deposuna yazma	Nesne ve dosya projeksiyonları için Depolama Blob DataContributor ve tablo projeksiyonları için Okuyucu ve Veri Erişimi ekleyin.
   Zenginleştirme önbelleğine yazma	Depolama Blob Veri Katkıda Bulunanı Ekleme
   Hata ayıklama oturum durumunu kaydetme	Depolama Blob Veri Katkıda Bulunanı Ekleme
   Azure OpenAI ekleme modellerini kullanarak veri ekleme (vektörleştirme)	Bilişsel Hizmetler OpenAI Kullanıcısı Ekleme

5. Üyeler sayfasında Yönetilen Kimlik'i seçin.

6. Üyeleri seçin. Yönetilen kimlik seçin sayfasında aboneliğinizi seçin, ardından hizmet türüne göre filtreleyin ve ardından hizmeti seçin. Yalnızca yönetilen kimliğe sahip olan hizmetler seçilebilir.

   

7. Gözden geçir + ata'yı seçin.

Bağlan ion dizesi örnekleri

Arama hizmeti için yönetilen kimlik tanımlanıp bir rol ataması verildikten sonra, giden bağlantılar diğer Azure kaynağının benzersiz kaynak kimliğini kullanacak şekilde değiştirilebilir. Çeşitli senaryolar için bazı bağlantı dizesi örnekleri aşağıda verilmiştir.

Blob veri kaynağı (sistem):

Dizin oluşturucu veri kaynağı, veri kaynağına bağlantının nasıl yapıldığını belirleyen bir "credentials" özelliği içerir. Aşağıdaki örnekte, depolama hesabının benzersiz kaynak kimliğini belirten bir bağlantı dizesi gösterilmektedir. Microsoft Entra Id, arama hizmetinin sistem tarafından yönetilen kimliğini kullanarak isteğin kimliğini doğrular. bağlantı dizesi kapsayıcı içermediğini fark edin. Veri kaynağı tanımında, kapsayıcı adı bağlantı dizesi değil "container" özelliğinde (gösterilmez) belirtilir.

"credentials": {
    "connectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name};"
    }

Blob veri kaynağı (kullanıcı):

Azure Depolama arama isteği, şu anda önizleme aşamasında olan kullanıcı tarafından atanan yönetilen kimlik altında da yapılabilir. Arama hizmeti kullanıcı kimliği "identity" özelliğinde belirtilir. Kimliği ayarlamak için portalı veya REST API önizleme sürümü 2021-04-30-Preview'ı kullanabilirsiniz.

"credentials": {
    "connectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name};"
    },
  . . .
"identity": {
    "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
    "userAssignedIdentity": "/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{user-assigned-managed-identity-name}"
  }

Bilgi deposu:

Bilgi deposu tanımı, Azure Depolama için bir bağlantı dizesi içerir. Azure Depolama'da bir bilgi deposu blob ve tablo olarak projeksiyonlar oluşturur. bağlantı dizesi, depolama hesabınızın benzersiz kaynak kimliğidir. Dizenin yolda kapsayıcılar veya tablolar içermediğini fark edin. Bunlar, bağlantı dizesi değil, eklenmiş projeksiyon tanımında tanımlanır.

"knowledgeStore": {
  "storageConnectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/storage-account-name};"
}

Zenginleştirme önbelleği:

Dizin oluşturucu önbelleğe alınmış zenginleştirmeler için kullanılan kapsayıcıyı oluşturur, kullanır ve hatırlar. Kapsayıcının önbellek bağlantı dizesi dahil edilmesi gerekmez. Nesne kimliğini portalda arama hizmetinizin Kimlik sayfasında bulabilirsiniz.

"cache": {
  "enableReprocessing": true,
  "storageConnectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name};"
}

Hata ayıklama oturumu:

Hata ayıklama oturumu portalda çalışır ve oturumu başlattığınızda bir bağlantı dizesi alır. Aşağıdaki örneğe benzer bir dize yapıştırabilirsiniz.

"ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name}/{container-name};",

Özel beceri:

Özel beceri, özel kodu barındıran bir Azure işlevinin veya uygulamanın uç noktasını hedefler. Uç nokta özel beceri tanımında belirtilir. "authResourceId" varlığının olması, arama hizmetine yönetilen bir kimlik kullanarak bağlanmasını ve özellikteki hedef işlevin veya uygulamanın uygulama kimliğini geçirmesini söyler.

{
  "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
  "description": "A custom skill that can identify positions of different phrases in the source text",
  "uri": "https://contoso.count-things.com",
  "authResourceId": "<Azure-AD-registered-application-ID>",
  "batchSize": 4,
  "context": "/document",
  "inputs": [ ... ],
  "outputs": [ ...]
}

Azure OpenAI ekleme becerisi ve Azure OpenAI vektörleştiricisi:

AI Search'teki Azure OpenAI ekleme becerisi ve vektörleştiricisi, ekleme modelini barındıran bir Azure OpenAI hizmetinin uç noktasını hedefler. Uç nokta, Azure OpenAI ekleme beceri tanımında ve/veya Azure OpenAI vektörleştirici tanımında belirtilir. Sistem tarafından yönetilen kimlik yapılandırıldıysa ve "apikey" ve "authIdentity" boşsa kullanılır. "authIdentity" özelliği yalnızca kullanıcı tarafından atanan yönetilen kimlik için kullanılır.

{
  "@odata.type": "#Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill",
  "description": "Connects a deployed embedding model.",
  "resourceUri": "https://url.openai.azure.com/",
  "deploymentId": "text-embedding-ada-002",
  "inputs": [
    {
      "name": "text",
      "source": "/document/content"
    }
  ],
  "outputs": [
    {
      "name": "embedding"
    }
  ]
}

 "vectorizers": [
    {
      "name": "my_azure_open_ai_vectorizer",
      "kind": "azureOpenAI",
      "azureOpenAIParameters": {
        "resourceUri": "https://url.openai.azure.com",
        "deploymentId": "text-embedding-ada-002"
      }
    }
  ]

Ayrıca bkz.

• Güvenliğe genel bakış
• Yapay zeka zenginleştirmeye genel bakış
• Dizin oluşturuculara genel bakış
• Microsoft Entra ID ile kimlik doğrulaması
• Yönetilen kimlikler hakkında (Microsoft Entra Id)