Aracılığıyla paylaş

Kimlikleri kullanarak uygulamanızı Azure Yapay Zeka Arama bağlama

Uygulama kodunuzda, kimlik doğrulama ve yetkilendirme için Microsoft Entra ID ve rollerini kullanarak Azure Yapay Zeka Arama'e anahtar gerektirmeyen bir bağlantı ayarlayabilirsiniz. Çoğu Azure hizmete yönelik uygulama isteklerinin kimlik doğrulaması anahtarlarla veya anahtarsız bağlantılarla yapılmalıdır. Geliştiricilerin anahtarları güvenli olmayan bir konumda asla kullanıma sunmaması için dikkatli olması gerekir. Anahtara erişim kazanan herkes hizmette kimlik doğrulaması yapabilir. Anahtarsız kimlik doğrulaması, saklanacak anahtar (veya bağlantı dizesi) olmadığından hesap anahtarına göre gelişmiş yönetim ve güvenlik avantajları sunar.

Bu makalede uygulama kodunuzda nasıl kullanılacağı DefaultAzureCredential açıklanmaktadır.

Kodunuzda anahtarsız bağlantılar uygulamak için şu adımları izleyin:

  • Arama hizmetinizde rol tabanlı erişimi etkinleştirme
  • Ortam değişkenlerini gerektiği gibi ayarlayın.
  • Azure Yapay Zeka Arama istemci nesnesi oluşturmak için bir Azure Kimlik kitaplığı kimlik bilgisi türü kullanın.

Önkoşullar

  • Azure Yapay Zeka Arama, herhangi bir bölge, ancak faturalanabilir bir katman (temel veya daha yüksek) olmalıdır.

  • Arama hizmetinizde rol tabanlı erişim etkinleştirildi.

  • Azure Yapay Zeka Arama rol atamaları. Kimliğinize şu rolleri atayın:

    • Yerel geliştirme için Arama Hizmeti Katkıda Bulunanı ve Arama Dizini Veri Katkıda Bulunanı (tam erişim)
    • Üretim salt okunur sorguları için Dizin Veri Okuyucusu arama

    Adım adım yönergeler için bkz. Geliştirme için rol atama.

Azure Identity istemci kitaplığını yükleyin

Anahtarsız bir yaklaşım kullanmak için AI Search özellikli kodunuzu Azure Identity istemci kitaplığıyla güncelleştirin.

.NET için Azure Identity istemci kitaplığını ve Azure Search Documents istemci kitaplığını yükleyin:

dotnet add package Azure.Identity
dotnet add package Azure.Search.Documents

Kaynak kodu DefaultAzureCredential kullanacak şekilde güncelleştirme

Azure Kimlik kitaplığının DefaultAzureCredential aynı kodu yerel geliştirme ortamında ve Azure bulutta çalıştırmanıza olanak tanır. Tek bir kimlik bilgisi oluşturun ve belirteç önbelleğinden yararlanmak için kimlik bilgisi örneğini gerektiği şekilde yeniden kullanın.

.NET için DefaultAzureCredential hakkında daha fazla bilgi için bkz. Azure Identity istemci kitaplığı .NET için.

using Azure;
using Azure.Search.Documents;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
using Azure.Search.Documents.Models;
using Azure.Identity;
using System;
using static System.Environment;

string endpoint = GetEnvironmentVariable("AZURE_SEARCH_ENDPOINT");
string indexName = "my-search-index";

DefaultAzureCredential credential = new();
SearchClient searchClient = new(new Uri(endpoint), indexName, credential);
SearchIndexClient searchIndexClient = new(endpoint, credential);

Reference:SearchClient, SearchIndexClient, DefaultAzureCredential

Bağlantınızı doğrulama

İstemciyi ayarladıktan sonra basit bir işlem çalıştırarak bağlantınızı doğrulayın. Aşağıdaki örnek, arama hizmetinizdeki dizinleri listeler:

// List indexes to verify connection
var indexes = searchIndexClient.GetIndexNames();
foreach (var name in indexes)
{
    Console.WriteLine(name);
}

Başarılı bir bağlantı, dizinlerinizin adlarını (veya dizin yoksa boş bir listeyi) yazdırır. Kimlik doğrulaması hatası alırsanız rol tabanlı erişimin etkinleştirildiğini ve kimliğinizin gerekli rol atamalarına sahip olduğunu doğrulayın.

Varsayılan yetki Azure genel buluttur. Bağımsız veya özel bulutlar için özel audience değerler şunlardır:

  • Azure Kamu için https://search.azure.us
  • 21Vianet tarafından işletilen Azure için https://search.azure.cn
  • Azure Almanya için https://search.microsoftazure.de

Yerel geliştirme

Rolleri kullanarak yerel geliştirme şu adımları içerir:

  • Özel kaynakta RBAC rollerine kişisel kimliğinizi atayın.
  • Azure ile kimlik doğrulaması yapmak için Azure CLI veya Azure PowerShell gibi bir araç kullanın.
  • Kaynağınız için ortam değişkenleri oluşturun.

Yerel geliştirme rolleri

Yerel geliştirici olarak, Azure kimliğinizin veri düzlemi işlemleri üzerinde tam denetime sahip olması gerekir. Önerilen roller şunlardır:

  • Arama Hizmeti Katılımcısı, nesne oluşturma ve yönetme
  • Dizin Veri Katkıcısı olarak, dizin yükle, sorgula ve bilgi bankasından veri al

Aşağıdaki araçlardan biriyle kişisel kimliğinizi bulun. <identity-id> değer olarak bu kimliği kullanın.

Yer tutucular <role-name>, <identity-id>, <subscription-id> ve <resource-group-name> aşağıdaki komutlarda kendi gerçek değerlerinizle değiştirin.

  1. Azure CLI oturum açın.

    az login

    Kimlik doğrulaması için bir tarayıcı penceresi açılır. Oturum açma başarılı olduktan sonra terminal abonelik bilgilerinizi görüntüler.

  2. Kişisel kimliğinizi alın.

    az ad signed-in-user show \
    --query id -o tsv

    Komut, kullanıcı nesne kimliğinizi (GUID) döndürür. Bu değeri sonraki adım için kaydedin.

  3. Rol tabanlı erişim denetimi (RBAC) rolünü kaynak grubunun kimliğine atayın.

    az role assignment create \
    --role "<role-name>" \
    --assignee "<identity-id>" \
    --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>"

    Başarılı bir atama, rol ataması ayrıntılarını içeren bir JSON nesnesi döndürür.

Yerel geliştirme için kimlik doğrulaması

Yerel geliştirme ortamınızda Azure kimliğine kimlik doğrulama yapmak için bir araç kullanın. Kimliğiniz doğrulandıktan sonra, DefaultAzureCredential kaynak kodunuzdaki örnek kimlik doğrulama amacıyla kimliğinizi bulur ve kullanır.

Yerel geliştirme sırasında kimlik doğrulaması için bir araç seçin.

Yerel geliştirme için ortam değişkenlerini yapılandırma

Azure Yapay Zeka Arama bağlanmak için kodunuzun kaynak uç noktanızı bilmesi gerekir.

Azure Yapay Zeka Arama uç noktanız için AZURE_SEARCH_ENDPOINT adlı bir ortam değişkeni oluşturun. Bu URL genellikle biçimindedir https://<YOUR-RESOURCE-NAME>.search.windows.net/.

Üretim iş yükleri

Üretim iş yüklerini dağıtma şu adımları içerir:

  • En az ayrıcalık ilkesine bağlı olan RBAC rollerini seçin.
  • Belirli bir kaynakta üretim kimliğinize RBAC rolleri atayın.
  • Kaynağınız için ortam değişkenlerini ayarlayın.

Üretim iş yükleri için roller ve sorumluluklar

Üretim kaynaklarınızı oluşturmak için kullanıcı tarafından atanan bir yönetilen kimlik oluşturmanız ve ardından bu kimliği doğru rollerle kaynaklarınıza atamanız gerekir.

Bir üretim uygulaması için aşağıdaki rol önerilir:

Rol adı Kimlik
Arama Dizini Veri Okuyucusu 1407120a-92aa-4202-b7e9-c0e197c71c8f

Üretim iş yükleri için kimlik doğrulaması

Kaynağı oluşturmak ve için kimlik doğrulamasını ayarlamak için aşağıdaki Azure Yapay Zeka Arama identityId kullanın. Bicep rol kimliğini gerektirir. Bu Bicep kod parçacığında gösterilen name Azure rolü değildir; Bicep dağıtımına özeldir.

// main.bicep
param environment string = 'production'
param roleGuid string = ''

module aiSearchRoleUser 'core/security/role.bicep' = {
    scope: aiSearchResourceGroup
    name: 'aiSearch-role-user'
    params: {
        principalId: (environment == 'development') ? principalId : userAssignedManagedIdentity.properties.principalId 
        principalType: (environment == 'development') ? 'User' : 'ServicePrincipal'
        roleDefinitionId: roleGuid
    }
}

main.bicep dosyası, herhangi bir rol oluşturmak için aşağıdaki genel Bicep kodunu çağırır. Bir kullanıcı için ve diğeri üretim için olmak üzere birden çok RBAC rolü oluşturma seçeneğiniz vardır. Bu, aynı Bicep dağıtımında hem geliştirme hem de üretim ortamlarını etkinleştirmenizi sağlar.

// core/security/role.bicep
metadata description = 'Creates a role assignment for an identity.'
param principalId string // passed in from main.bicep

@allowed([
    'Device'
    'ForeignGroup'
    'Group'
    'ServicePrincipal'
    'User'
])
param principalType string = 'ServicePrincipal'
param roleDefinitionId string // Role ID

resource role 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
    name: guid(subscription().id, resourceGroup().id, principalId, roleDefinitionId)
    properties: {
        principalId: principalId
        principalType: principalType
        roleDefinitionId: resourceId('Microsoft.Authorization/roleDefinitions', roleDefinitionId)
    }
}

Üretim iş yükleri için ortam değişkenlerini yapılandırma

Azure Yapay Zeka Arama bağlanmak için kodunuzun kaynak uç noktanızı ve yönetilen kimliği bilmesi gerekir.

Dağıtılan ve anahtarsız Azure Yapay Zeka Arama kaynağınız için ortam değişkenleri oluşturun:

  • AZURE_SEARCH_ENDPOINT: Bu URL, Azure Yapay Zeka Arama kaynağınızın erişim noktasıdır. Bu URL genellikle biçimindedir https://<YOUR-RESOURCE-NAME>.search.windows.net/.
  • AZURE_CLIENT_ID: Kimlik doğrulaması için kullanılacak kimlik budur.

Sık karşılaşılan hataları giderme

Hata Nedeni Çözüm
AuthenticationFailedException Eksik veya geçersiz kimlik bilgileri az login (CLI) veya Connect-AzAccount (PowerShell) ile oturum açtığınızdan emin olun. Azure hesabınızın aboneliğe erişimi olduğunu doğrulayın.
403 Forbidden Kimlikte gerekli rol yok Uygun rolü atayın (Sorgular için Arama Dizini Okuyucusu, dizin oluşturma için Arama Dizini Katılımcısı). Rol atamalarının yayılması 10 dakika kadar sürebilir.
401 Unauthorized Arama hizmetinde RBAC etkin değil Azure portalında Settings>Keys>Role tabanlı erişim denetimi altında rol tabanlı erişimi etkinleştirin.
ResourceNotFoundException Geçersiz uç nokta veya dizin adı Ortam değişkeninin AZURE_SEARCH_ENDPOINT arama hizmeti URL'nizle eşleştiklerini doğrulayın (biçim: https://<service-name>.search.windows.net).
CredentialUnavailableException Geçerli kimlik bilgisi bulunamadı DefaultAzureCredential birden çok kimlik doğrulama yöntemini dener. En az birinin yapılandırıldığından emin olun (Azure CLI, Visual Studio, ortam değişkenleri).

İlgili içerik

  • Last updated on