Anahtarları kullanarak Azure AI Search'e bağlanma

Makale
09/01/2024

Azure AI Search, arama hizmetinize bağlantılar için anahtar tabanlı kimlik doğrulaması sunar. API anahtarı, rastgele oluşturulan 52 sayı ve harflerden oluşan benzersiz bir dizedir. Kaynak kodunuzda, bunu bir ortam değişkeni veya projenizde bir uygulama ayarı olarak belirtebilir ve ardından isteğe göre değişkene başvurabilirsiniz. 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.

Bunu, kod tabanınızda sabit kodlanmış anahtarlara olan ihtiyacı ortadan kaldıran rol tabanlı erişimle değiştirebilirsiniz.

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ı, GET nesne tanımları ve sistem bilgileri 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 LIST Dizinleri veya GET Hizmeti İstatistikleri gibi arama hizmetinin kendisine gönderilen isteklerde kullanılır.

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=2024-07-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=2024-07-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 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.
Yönetici ve sorgu anahtarlarını görüntülemek için Ayarlar'ın altında 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'sinde Yönetici Anahtarlarını Listele veya Sorgu Anahtarlarını Listele'yi 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'ın 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'ın 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.

Aracılığıyla paylaş