Azure Yapay Zeka Arama'e anahtarları kullanarak bağlanmak

Azure Yapay Zeka Arama, arama hizmetinize yönelik bağlantılar için hem kimlik tabanlı hem de anahtar tabanlı kimlik doğrulamasını (varsayılan) destekler.

Hem istek hem de API anahtarı geçerliyse ve arama hizmeti bir istekte API anahtarlarına izin verecek şekilde yapılandırılmışsa, arama hizmeti uç noktasına yapılan istek kabul edilir.

Önemli

Arama hizmeti oluşturduğunuzda, anahtar tabanlı kimlik doğrulaması varsayılandır, ancak en güvenli seçenek değildir. Bunu rol tabanlı erişimle değiştirmenizi öneririz.

Önkoşullar

Anahtarları görüntülemek veya yönetmek için Sahip, Katkıda Bulunan veya Arama Hizmeti Katkıda Bulunanı olmanız gerekir.

Varsayılan olarak etkin

Azure portalında kimlik doğrulaması Settings>Keys sayfasında belirtilir. Api anahtarları (varsayılan) veya her ikisi de isteğe bağlı API anahtarlarına izin verir olarak ayarlanmış seçenekler.

Anahtar türleri

API anahtarı, rastgele oluşturulan 52 sayı ve harflerden oluşan benzersiz bir dizedir. Görsel olarak, bir yönetici anahtarıyla sorgu anahtarı arasında ayrım yoktur. Uygulamanızda hangi tür anahtarın belirtildiğini kaybederseniz Azure portalında anahtar değerlerini denetleyebilirsiniz.

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

Tür	İzin düzeyi	Nasıl oluşturulur?	Maksimum
Yönetici	Tüm veri düzlemi (içerik) işlemleri için tam erişim (okuma-yazma)	Birincil veikincil olmak üzere iki yönetici anahtarı, hizmet oluşturulduğunda oluşturulur ve isteğe bağlı olarak ayrı ayrı yeniden oluşturulabilir. İki anahtara sahip olmak, hizmete sürekli erişim için ikinci anahtarı kullanırken bir anahtarı devretmenizi sağlar.	2
Sorgu	Arama dizininin belge koleksiyonu kapsamında salt okunur erişim	Hizmetle bir sorgu anahtarı oluşturulur. Arama hizmeti yöneticisi tarafından isteğe bağlı olarak daha fazlası oluşturulabilir.	50

Mevcut anahtarları bulma

API anahtarlarını Azure portal, PowerShell, Azure CLI veya REST API kullanarak görüntüleyebilir ve yönetebilirsiniz.

Azure portalında arama hizmetinize gidin.
Yönetici ve sorgu anahtarlarını görüntülemek için sol bölmeden Ayarlar>Anahtarları'nı seçin.

Sırasıyla yönetici ve sorgu API anahtarlarını döndürmek için aşağıdaki komutları çalıştırın. REST ile ilgili yardım için bkz. REST API'leriyle Azure Yapay Zeka Arama hizmetinizi yönetme.

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

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

Döndürülen sorgu anahtarları:

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

Başvuru:Yönetici Anahtarları - Alma, Sorgu Anahtarları - Arama Hizmetine Göre Listele

API anahtarlarını program aracılığıyla almak için Python için Azure SDK kullanın. Yönetim SDK'sını yükleyin:

pip install azure-mgmt-search azure-identity

Yönetici ve sorgu API anahtarlarını döndürmek için aşağıdaki kodu çalıştırın:

import os
from azure.identity import DefaultAzureCredential
from azure.mgmt.search import SearchManagementClient

# Set up variables
subscription_id = os.environ["AZURE_SUBSCRIPTION_ID"]
resource_group = "your-resource-group"
search_service_name = "your-search-service"

# Create the management client
credential = DefaultAzureCredential()
client = SearchManagementClient(credential, subscription_id)

# Get admin keys
admin_keys = client.admin_keys.get(resource_group, search_service_name)
print(f"Primary admin key: {admin_keys.primary_key}")
print(f"Secondary admin key: {admin_keys.secondary_key}")

# Get query keys
query_keys = client.query_keys.list_by_search_service(resource_group, search_service_name)
for key in query_keys:
    print(f"Query key '{key.name}': {key.key}")

Reference:SearchManagementClient | AdminKeys | QueryKeys

Sırasıyla yönetici ve sorgu API anahtarlarını döndürmek için aşağıdaki komutları çalıştırın. PowerShell ile ilgili yardım için bkz. PowerShell kullanarak Azure Yapay Zeka Arama hizmetinizi yönetme.

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ı çalıştırın. Azure CLI ile ilgili yardım için bkz. Azure CLI kullanarak Azure Yapay Zeka Arama hizmetinizi yönetme.

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

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

Döndürülen sorgu anahtarları:

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

Bağlantılarda anahtarları kullanma

Anahtar tabanlı kimlik doğrulaması yalnızca dizin oluşturma veya sorgulama gibi veri düzlemi (içerik) istekleri ve Arama Hizmeti REST API'sini kullanarak gerçekleştirilen diğer eylemler için kullanılır.

Kaynak kodunuzda, api anahtarını doğrudan bir istek üst bilgisinde belirtebilirsiniz. Alternatif olarak, bunu projenizde bir ortam değişkeni veya uygulama ayarı olarak depolayabilir ve ardından istekteki değişkene başvurabilirsiniz.

Yönetici anahtarları nesneleri oluşturmak, değiştirmek veya silmek için kullanılır.
Yönetici anahtarları, LIST Dizinleri veya GET Hizmeti İstatistikleri gibi 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.

Anahtar kimlik doğrulamasının varsayılan olarak etkinleştirildiğini ve dizin oluşturma ve sorgular gibi veri düzlemi işlemlerini desteklediğini hatırlayın.

Ancak, API anahtarlarını devre dışı bırakır ve rol atamaları ayarlarsanız, Azure portalı rol atamalarını üzerinize alır.

İstek üst bilgisinde bir yönetici anahtarı ayarlayın. URI'de veya isteğin gövdesinde yönetici anahtarlarını geçiremezsiniz.

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

@baseUrl=https://my-demo-search-service.search.windows.net
@adminApiKey=aaaabbbb-0000-cccc-1111-dddd2222eeee

### Create an index
POST {{baseUrl}}/indexes?api-version=2026-04-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=2026-04-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 Yapay Zeka Arama sorgu anahtarını yalnızca sorgu dizesinde api-key olarak kabul eder. Genel bir kural olarak, api-key ögesini bir istek üst bilgisi olarak geçirmenizi öneririz.

API anahtarını ortam değişkeni olarak ayarlamak en iyi yöntemdir, ancak kolaylık olması için bu örnek bunu bir dize olarak gösterir. Örnek, bir sorgu işlemi için bir sorgu API anahtarı kullanır.

# Import libraries
from azure.search.documents import SearchClient
from azure.core.credentials import AzureKeyCredential
from azure.identity import DefaultAzureCredential, AzureAuthorityHosts

# Variables for endpoint, keys, index
search_endpoint: str = "https://<Put your search service NAME here>.search.windows.net/"
credential = AzureKeyCredential("Your search service query key")
index_name: str = "hotels-quickstart-python"

# Set up the client
search_client = SearchClient(endpoint=search_endpoint,
                      index_name=index_name,
                      credential=credential)

# Run the query
results =  search_client.search(query_type='simple',
    search_text="*" ,
    select='HotelName,Description,Tags',
    include_total_count=True)

print ('Total Documents Matching Query:', results.get_count())
for result in results:
    print(result["@search.score"])
    print(result["HotelName"])
    print(result["Tags"])
    print(f"Description: {result['Description']}")

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' }

Tam sorguyu içeren bir değişken kullanın:

$url = '<YOUR-SEARCH-SERVICE>/indexes/hotels-quickstart/docs?api-version=2026-04-01&search=attached restaurant&searchFields=Description,Tags&$select=HotelId,HotelName,Tags,Description&$count=true'

İsteği arama hizmetine gönderin:

Invoke-RestMethod -Uri $url -Headers $headers | ConvertTo-Json

Diğer işlemler için daha fazla betik örneği Quickstart: REST API'lerini kullanarak PowerShell'de Azure Yapay Zeka Arama dizini oluşturma bulunabilir.

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 arama hizmetinize gidin.
Api anahtarlarını görüntülemek için sol bölmeden Ayarlar>Anahtarları'nı seçin.
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'leriyle Azure Yapay Zeka Arama hizmetinizi yönetme.

POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Search/searchServices/{searchServiceName}/createQueryKey/{name}?api-version=2025-05-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.

Azure portalında arama hizmetinize gidin.
Sol bölmeden Ayarlar>Anahtarlar'ı seçin.
İkincil 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 Azure portalından 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ığınızda içeriğinize (dizinler, dizin oluşturucular, veri kaynakları, eş anlamlı eşlemeler) erişim geri yüklenir.

Anahtarlardan rollere geçiş

Rol tabanlı erişime geçmek istiyorsanız, anahtarların Azure Yapay Zeka Arama içindeki yerleşik rollerle nasıl eşleştiğini anlamak faydalı olur.

Yönetici anahtarı , Arama Hizmeti Katkıda Bulunanı ve Arama Dizini Veri Katkıda Bulunanı rollerine karşılık gelir.
Sorgu anahtarı , Arama Dizini Veri Okuyucusu rolüne karşılık gelir.

Güvenli 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 hizmetinize gidin.
Sol bölmeden 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

Üretim iş yükleri için Microsoft Entra ID ve rol tabanlı erişim geçin. Alternatif olarak, API anahtarlarını kullanmaya devam etmek istiyorsanız, API anahtarlarınız için kimlerin erişimi olduğunu her zaman izlediğinizden ve API anahtarlarını düzenli bir tempoda yeniden oluşturduğunuzdan emin olun.
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 kullanılması hem verilerinizi hem de arama hizmetinizi yetkisiz kullanım riskiyle karşı karşıya bırakır.
API anahtarı kullanıyorsanız, Azure Key Vault gibi başka bir yerde güvenli bir şekilde depolayın. API anahtarını doğrudan kodunuzla eklemeyin ve hiçbir zaman herkese açık olarak göndermeyin.
Api anahtarını yanlışlıkla kullanıma sunmadığınızdan emin olmak için yayımlamadan önce her zaman kodu, örnekleri ve eğitim malzemelerini denetleyin.

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2026-04-07

Azure Yapay Zeka Arama'e anahtarları kullanarak bağlanmak

Önkoşullar

Varsayılan olarak etkin

Anahtar türleri

Mevcut anahtarları bulma

Bağlantılarda anahtarları kullanma

Sorgu anahtarları oluşturma

Yönetici anahtarlarını yeniden oluşturma

Anahtarlardan rollere geçiş

Güvenli anahtarlar

En iyi yöntemler

İlgili içerik

Geri Bildirim

Ek kaynaklar