Anahtar kimlik doğrulaması kullanarak Azure AI Search'e Bağlan

Makale
04/25/2024

Azure AI Search, arama hizmetinize yönelik bağlantılarda kullanabileceğiniz anahtar tabanlı kimlik doğrulaması sunar. API anahtarı, rastgele oluşturulan 52 sayı ve harflerden oluşan benzersiz bir dizedir. Hem istek hem de API anahtarı geçerliyse, arama hizmeti uç noktasına yapılan istek kabul edilir.

Anahtar tabanlı kimlik doğrulaması varsayılandır. Rol tabanlı kimlik doğrulamasını seçerseniz devre dışı bırakabilirsiniz.

Not

Anahtar terminolojisi hakkında hızlı bir not. API anahtarı, kimlik doğrulaması için kullanılan bir GUID'dir. Ayrı bir terim olan belge anahtarı, dizine alınan içeriğinizde arama dizinindeki belgeleri benzersiz olarak tanımlayan benzersiz bir dizedir.

API anahtarı türleri

İsteğin kimliğini doğrulamak için kullanılan iki tür anahtar vardır:

Tür	İzin düzeyi	En Büyük	Nasıl oluşturuldu?
Yönetici	Tüm içerik işlemleri için tam erişim (okuma-yazma)	2 ¹	Portalda birincil ve ikincil anahtarlar olarak adlandırılan iki yönetici anahtarı, hizmet oluşturulduğunda oluşturulur ve isteğe bağlı olarak ayrı ayrı yeniden oluşturulabilir.
Sorgu	Arama dizininin belge koleksiyonu kapsamında salt okunur erişim	50	Hizmetle bir sorgu anahtarı oluşturulur. Arama hizmeti yöneticisi tarafından isteğe bağlı olarak daha fazlası oluşturulabilir.

¹ İki anahtara sahip olmak, hizmete sürekli erişim için ikinci anahtarı kullanırken bir anahtarı devretmenizi sağlar.

Görsel olarak, bir yönetici anahtarıyla sorgu anahtarı arasında ayrım yoktur. Her iki anahtar da rastgele oluşturulan 52 alfasayısal karakterden oluşan dizelerdir. Uygulamanızda hangi tür anahtarın belirtildiğini izlerseniz portalda anahtar değerlerini de kontrol edebilirsiniz.

Bağlantılarda API anahtarlarını kullanma

API anahtarları, dizin oluşturma veya dizine erişme gibi veri düzlemi (içerik) istekleri veya Arama REST API'lerinde temsil edilen diğer istekler için kullanılır. Hizmet oluşturma işleminde, api anahtarı veri düzlemi işlemleri için tek kimlik doğrulama mekanizmasıdır, ancak kodunuzda sabit kodlanmış anahtarlar kullanamıyorsanız anahtar kimlik doğrulamasını Azure rolleriyle değiştirebilir veya destekleyebilirsiniz.

Yönetici anahtarları nesneleri oluşturmak, değiştirmek veya silmek için kullanılır. Yönetici anahtarları, nesne tanımlarını ve sistem bilgilerini ALMAK için de kullanılır.

Sorgu anahtarları genellikle sorgular veren istemci uygulamalarına dağıtılır.

API anahtarları REST çağrılarında nasıl kullanılır:

İstek üst bilgisinde bir yönetici anahtarı ayarlayın. URI'de veya isteğin gövdesinde yönetici anahtarlarını geçiremezsiniz. Yönetici anahtarları create-read-update-delete işlemi için ve arama hizmetinin kendisine gönderilen isteklerde kullanılır, örneğin LIST Dizinleri veya GET Hizmeti İstatistikleri.

Aşağıda, dizin oluşturma isteğinde yönetici API anahtarı kullanımı örneği verilmiştir:

### Create an index
POST {{baseUrl}}/indexes?api-version=2023-11-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{adminApiKey}}

    {
        "name": "my-new-index",  
        "fields": [
            {"name": "docId", "type": "Edm.String", "key": true, "filterable": true},
            {"name": "Name", "type": "Edm.String", "searchable": true }
         ]
   }

POST için istek üst bilgisinde veya GET için URI'de bir sorgu anahtarı ayarlayın. Sorgu anahtarları koleksiyonu hedefleyen index/docs işlemler için kullanılır: Arama Belgeleri, Otomatik Tamamlama, Öneri veya GET Belgesi.

Arama Belgeleri (GET) isteğinde sorgu API anahtarı kullanımı örneği aşağıda verilmiştir:

### Query an index
GET /indexes/my-new-index/docs?search=*&api-version=2023-11-01&api-key={{queryApiKey}}

Not

İstek URI'sindeki gibi hassas verileri geçirmek kötü bir api-key güvenlik uygulaması olarak kabul edilir. Bu nedenle Azure AI Search, sorgu dizesinde yalnızca bir sorgu anahtarını kabul api-key eder. Genel bir kural olarak, isteğinizi istek üst bilgisi olarak geçirmenizi api-key öneririz.

API anahtarları PowerShell'de nasıl kullanılır:

aşağıdaki söz dizimini kullanarak istek üst bilgisinde API anahtarlarını ayarlayın:

$headers = @{
'api-key' = '<YOUR-ADMIN-OR-QUERY-API-KEY>'
'Content-Type' = 'application/json' 
'Accept' = 'application/json' }

Çeşitli işlemler için API anahtarı kullanımını gösteren bir betik örneği, Hızlı Başlangıç: REST API'lerini kullanarak PowerShell'de Azure AI Search dizini oluşturma makalesinde bulunabilir.

API anahtarlarını görüntüleme veya yönetme izinleri

API anahtarlarını görüntüleme ve yönetme izinleri rol atamaları aracılığıyla iletilir. Aşağıdaki rollerin üyeleri anahtarları görüntüleyebilir ve yeniden oluşturabilir:

Sahip
Katılımcı
Arama Hizmeti Katkıda Bulunanı
Yönetici istrator ve ortak yönetici (klasik)

Aşağıdaki rollerin API anahtarlarına erişimi yoktur:

Okuyucu
Arama Dizini Veri Katkıda Bulunanı
Arama Dizini Veri Okuyucusu

Mevcut anahtarları bulma

API anahtarlarını Azure portalında veya PowerShell , Azure CLI veya REST API aracılığıyla görüntüleyebilir ve yönetebilirsiniz.

Azure portalında oturum açın ve arama hizmetinizi bulun.
Ayarlar altında, yönetici ve sorgu anahtarlarını görüntülemek için Anahtarlar'ı seçin.

Az.Search Modülü yükleyin:
```
Install-Module Az.Search
```

Yönetici anahtarlarını döndür:

Get-AzSearchAdminKeyPair -ResourceGroupName <resource-group-name> -ServiceName <search-service-name>

Döndürülen sorgu anahtarları:

Get-AzSearchQueryKey -ResourceGroupName <resource-group-name> -ServiceName <search-service-name>

Sırasıyla yönetici ve sorgu API anahtarlarını döndürmek için aşağıdaki komutları kullanın:

az search admin-key show --resource-group <myresourcegroup> --service-name <myservice>

az search query-key list --resource-group <myresourcegroup> --service-name <myservice>

API anahtarlarını döndürmek için Yönetim REST API'sindeki Liste Yönetici Anahtarlarını veya Liste Sorgu Anahtarlarını kullanın.

API anahtarlarını döndürmek veya güncelleştirmek için geçerli bir rol atamanız olmalıdır. REST API'lerini kullanarak rol gereksinimlerini karşılama yönergeleri için bkz. REST API'lerle Azure AI Arama hizmeti yönetme.

POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resource-group}}/providers//Microsoft.Search/searchServices/{{search-service-name}}/listAdminKeys?api-version=2023-11-01

Sorgu anahtarları oluşturma

Sorgu anahtarları, bir belge koleksiyonunu hedefleyen işlemler için dizin içindeki belgelere salt okunur erişim için kullanılır. Arama, filtreleme ve öneri sorguları, sorgu anahtarı kullanan tüm işlemlerdir. Dizin tanımı veya dizin oluşturucu durumu gibi sistem verilerini veya nesne tanımlarını döndüren herhangi bir salt okunur işlem için yönetici anahtarı gerekir.

İstemci uygulamalarında erişimi ve işlemleri kısıtlamak, hizmetinizdeki arama varlıklarını korumak için gereklidir. İstemci uygulamasından kaynaklanan tüm sorgular için her zaman yönetici anahtarı yerine sorgu anahtarı kullanın.

Azure portalında oturum açın ve arama hizmetinizi bulun.
Ayarlar altında Anahtarlar'ı seçerek API anahtarlarını görüntüleyin.
Sorgu anahtarlarını yönet altında, hizmetiniz için önceden oluşturulmuş olan sorgu anahtarını kullanın veya yeni sorgu anahtarları oluşturun. Varsayılan sorgu anahtarı adlandırılmasa da, yönetilebilirlik için oluşturulan diğer sorgu anahtarları adlandırılabilir.

Yönetim REST API'sinde Sorgu Anahtarları Oluştur'u kullanın.

API anahtarları oluşturmak veya yönetmek için geçerli bir rol atamanız olmalıdır. REST API'lerini kullanarak rol gereksinimlerini karşılama yönergeleri için bkz. REST API'lerle Azure AI Arama hizmeti yönetme.

POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Search/searchServices/{searchServiceName}/createQueryKey/{name}?api-version=2023-11-01

Yönetici anahtarlarını yeniden oluşturma

İş sürekliliği için ikincil anahtarı kullanırken birincil anahtarı döndürebilmeniz için her hizmet için iki yönetici anahtarı oluşturulur.

Ayarlar altında Anahtarlar'ı seçin ve ikincil anahtarı kopyalayın.
Tüm uygulamalar için API anahtarı ayarlarını ikincil anahtarı kullanacak şekilde güncelleştirin.
Birincil anahtarı yeniden oluşturma.
Tüm uygulamaları yeni birincil anahtarı kullanacak şekilde güncelleştirin.

Her iki anahtarı da yanlışlıkla aynı anda yeniden oluşturursanız, bu anahtarları kullanan tüm istemci istekleri HTTP 403 Yasak ile başarısız olur. Ancak içerik silinmez ve kalıcı olarak kilitlenmezsiniz.

Hizmete portaldan veya program aracılığıyla erişmeye devam edebilirsiniz. Yönetim işlevleri, hizmet API'si anahtarı değil abonelik kimliği üzerinden çalışır ve BU nedenle API anahtarlarınız olmasa bile kullanılabilir.

Portal veya yönetim katmanı aracılığıyla yeni anahtarlar oluşturduktan sonra, isteklerde bu anahtarları sağladıktan sonra içeriğinize (dizinler, dizin oluşturucular, veri kaynakları, eş anlamlı eşlemeler) erişim geri yüklenir.

Güvenli API anahtarları

API anahtarlarına erişimi kısıtlamak için rol atamalarını kullanın.

API anahtarlarını şifrelemek için müşteri tarafından yönetilen anahtar şifrelemesi kullanmak mümkün değildir. Yalnızca arama hizmetinin içindeki hassas veriler (örneğin, dizin içeriği veya veri kaynağı nesne tanımlarındaki bağlantı dizesi) CMK ile şifrelenebilir.

Azure portalında arama hizmeti sayfanıza gidin.
Sol gezinti bölmesinde Erişim denetimi (IAM) öğesini ve ardından Rol atamaları sekmesini seçin.
Rol filtresinde anahtarları görüntüleme veya yönetme izni olan rolleri seçin (Sahip, Katkıda Bulunan, Arama Hizmeti Katkıda Bulunanı). Bu rollere atanan sonuçta elde edilen güvenlik sorumlularının arama hizmetinizde önemli izinleri vardır.
Önlem olarak, yöneticilerin ve ortak yöneticilerin erişimi olup olmadığını belirlemek için Klasik yöneticiler sekmesini de denetleyin.

En iyi yöntemler

API anahtarlarını yalnızca verilerin açığa çıkması bir risk değilse (örneğin, örnek verileri kullanırken) ve bir güvenlik duvarının arkasında çalışıyorsanız kullanın. API anahtarlarının kullanıma açık olması hem veriler hem de arama hizmetinizin yetkisiz kullanımı için bir risktir.
Geçerli API anahtarlarını geride bırakmadığınızdan emin olmak için yayımlamadan önce her zaman kodu, örnekleri ve eğitim malzemelerini denetleyin.
Üretim iş yükleri için Microsoft Entra Kimliği'ne ve rol tabanlı erişime geçin. Api anahtarlarını kullanmaya devam etmek istiyorsanız, API anahtarlarınıza kimlerin erişdiğini her zaman izlediğinizden ve API anahtarlarını normal bir tempoda yeniden oluşturduğunuzdan emin olun.