Menyambungkan ke Pencarian Azure AI menggunakan kunci

Pencarian Azure AI mendukung autentikasi berbasis identitas dan berbasis kunci (default) untuk koneksi ke layanan pencarian Anda.

Permintaan yang dibuat ke titik akhir layanan pencarian diterima jika permintaan dan kunci API valid dan jika layanan pencarian dikonfigurasi untuk mengizinkan kunci API berdasarkan permintaan.

Penting

Saat Anda membuat layanan pencarian, autentikasi berbasis kunci adalah default, tetapi ini bukan opsi yang paling aman. Kami menyarankan agar Anda menggantinya dengan akses berbasis peran.

Prasyarat

Anda harus menjadi Pemilik, Kontributor, atau Kontributor Layanan Pencarian untuk melihat atau mengelola kunci.

Diaktifkan secara default

Di portal Azure, autentikasi ditentukan pada halaman Settings>Keys. Opsi diatur ke kunci API (default) atau Keduanya mengizinkan kunci API berdasarkan permintaan.

Jenis kunci

Kunci API adalah string unik yang terdiri dari 52 angka dan huruf yang dihasilkan secara acak. Secara visual, tidak ada perbedaan antara kunci admin atau kunci kueri. Jika Anda kehilangan jejak jenis kunci apa yang ditentukan dalam aplikasi, Anda dapat memeriksa nilai kunci di portal Azure.

Ada dua jenis kunci yang digunakan untuk mengautentikasi permintaan:

Jenis	Tingkat izin	Cara pembuatannya	Maksimum
Pengelola	Akses penuh (baca-tulis) untuk semua operasi sarana data (konten)	Dua kunci admin, primer dan sekunder, dihasilkan ketika layanan dibuat dan dapat diregenerasi secara individual sesuai permintaan. Memiliki dua memungkinkan Anda untuk mengganti satu kunci saat menggunakan kunci kedua untuk akses berkelanjutan ke layanan.	2
Kueri	Akses hanya-baca, terbatas pada kumpulan dokumen indeks pencarian	Satu kunci kueri dihasilkan oleh layanan. Lainnya dapat dibuat sesuai permintaan oleh administrator layanan pencarian.	50

Temukan kunci yang ada

Anda dapat melihat dan mengelola kunci API menggunakan portal Azure, PowerShell, Azure CLI, atau REST API.

Buka layanan pencarian Anda di portal Azure.
Dari panel kiri, pilihTombol> untuk menampilkan kunci admin dan kueri.

Jalankan perintah berikut untuk mengembalikan kunci API admin dan kueri. Untuk bantuan terkait REST, lihat Kelola layanan Pencarian Azure AI Anda dengan REST API.

Mengembalikan kunci admin:

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

Mengembalikan kunci kueri:

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

Referensi:Kunci Admin - Ambil, Kunci Kueri - Tampilkan Berdasarkan Layanan Pencarian

Gunakan Azure SDK untuk Python mengambil kunci API secara terprogram. Instal SDK manajemen:

pip install azure-mgmt-search azure-identity

Jalankan kode berikut untuk mengembalikan kunci API admin dan kueri:

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}")

Referensi:SearchManagementClient | AdminKeys | QueryKeys

Jalankan perintah berikut untuk mengembalikan kunci API admin dan kueri. Untuk bantuan terkait PowerShell, lihat Kelola layanan Pencarian Azure AI Anda menggunakan PowerShell.

Az.Search Instal modul:
```
Install-Module Az.Search
```

Mengembalikan kunci admin:

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

Mengembalikan kunci kueri:

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

Jalankan perintah berikut untuk mengembalikan kunci API admin dan kueri. Untuk bantuan tentang Azure CLI, lihat Kelola layanan Pencarian Azure AI Anda menggunakan Azure CLI.

Mengembalikan kunci admin:

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

Mengembalikan kunci kueri:

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

Menggunakan kunci pada koneksi

Autentikasi berbasis kunci hanya digunakan untuk permintaan sarana data (konten), seperti membuat atau mengkueri indeks dan tindakan lain yang dilakukan menggunakan REST API Layanan Pencarian.

Dalam kode sumber, Anda dapat langsung menentukan kunci API di header permintaan. Atau, Anda dapat menyimpannya sebagai variabel lingkungan atau pengaturan aplikasi di proyek Anda lalu mereferensikan variabel dalam permintaan.

Kunci admin digunakan untuk membuat, memodifikasi, atau menghapus objek.
Kunci admin juga digunakan untuk MENDAPATKAN definisi objek dan informasi sistem, seperti Indeks LIST atau Statistik Layanan GET.
Kunci kueri biasanya didistribusikan ke aplikasi klien yang mengeluarkan kueri.

Ingat bahwa autentikasi kunci diaktifkan secara default dan mendukung operasi sarana data seperti pengindeksan dan kueri.

Namun, jika Anda menonaktifkan kunci API dan mengatur penetapan peran, portal Azure menggunakan penetapan peran sebagai penggantinya.

Atur kunci admin di header permintaan. Anda tidak dapat mengirimkan kunci admin pada URI, atau dalam isi permintaan.

Berikut adalah contoh penggunaan kunci API admin pada permintaan buat indeks:

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

### Create an index
POST {{baseUrl}}/indexes?api-version=2025-09-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 }
         ]
   }

Atur kunci kueri di header permintaan untuk POST, atau di URI untuk GET. Kunci kueri digunakan untuk operasi yang menargetkan index/docs koleksi: Pencarian Dokumen, Pelengkapan Otomatis, Saran, atau GET Dokumen.

Berikut adalah contoh penggunaan kunci API kueri pada permintaan Dokumen Pencarian (GET):

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

Catatan

Dianggap sebagai praktik keamanan yang buruk untuk meneruskan data sensitif seperti api-key dalam URI permintaan. Untuk alasan ini, Pencarian Azure AI hanya menerima kunci kueri sebagai api-key dalam string kueri. Sebagai aturan umum, kami sarankan mengirimkan api-key sebagai header permintaan Anda.

Ini adalah praktik terbaik untuk mengatur kunci API sebagai variabel lingkungan, tetapi untuk kesederhanaan, contoh ini menunjukkannya sebagai string. Contoh menggunakan kunci API kueri untuk operasi kueri.

# 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']}")

Atur kunci API di header permintaan menggunakan sintaks berikut:

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

Gunakan variabel untuk berisi kueri yang sepenuhnya memenuhi syarat:

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

Kirim permintaan ke layanan pencarian:

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

Contoh skrip lainnya untuk operasi lain dapat ditemukan di Quickstart: Membuat indeks Pencarian Azure AI di PowerShell menggunakan REST API.

Membuat kunci kueri

Kunci kueri digunakan untuk akses baca-saja ke dokumen di dalam indeks untuk operasi yang menargetkan kumpulan dokumen. Kueri pencarian, filter, dan saran semua merupakan operasi yang menggunakan kunci kueri. Setiap operasi baca-saja yang mengembalikan data sistem atau definisi objek, seperti definisi indeks atau status pengindeks, membutuhkan kunci admin.

Membatasi akses dan operasi di aplikasi klien sangat penting untuk melindungi aset pencarian pada layanan Anda. Selalu gunakan kunci kueri, ketimbang kunci admin, untuk setiap kueri yang berasal dari aplikasi klien.

Buka layanan pencarian Anda di portal Azure.
Dari panel kiri, pilihKunci> untuk melihat kunci API.
Di bawah Kelola kunci kueri, gunakan kunci kueri yang sudah dibuat untuk layanan Anda, atau buat kunci kueri baru. Kunci kueri default tidak dinamai, tetapi kunci kueri lain yang dihasilkan dapat dinamai untuk pengelolaan.

Gunakan Buat Kunci Kueri di REST API Manajemen.

Anda harus memiliki penetapan peran yang valid untuk membuat atau mengelola kunci API. Lihat Kelola layanan Pencarian Azure AI Anda dengan REST API untuk panduan tentang memenuhi persyaratan peran menggunakan REST API.

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

Meregenerasi kunci admin

Dua kunci admin dibuat untuk setiap layanan sehingga Anda dapat memutar kunci primer saat menggunakan kunci sekunder untuk kelangsungan bisnis.

Buka layanan pencarian Anda di portal Azure.
Dari panel kiri, pilih Pengaturan>Tombol.
Salin kunci sekunder.
Untuk semua aplikasi, perbarui pengaturan kunci API untuk memakai kunci sekunder.
Regenerasikan kunci primer.
Perbarui semua aplikasi untuk menggunakan kunci primer baru.

Jika Anda meregenerasi kedua kunci pada saat yang sama secara tidak sengaja, semua permintaan klien yang menggunakan kunci tersebut akan gagal dengan HTTP 403 Terlarang. Namun, konten tidak dihapus dan Anda tidak dikunci secara permanen.

Anda masih dapat mengakses layanan melalui portal Azure atau secara terprogram. Fungsi manajemen beroperasi melalui ID langganan bukan kunci API layanan, dan dengan demikian masih tersedia meskipun kunci API Anda tidak.

Setelah Anda membuat kunci baru melalui portal atau lapisan manajemen, akses dipulihkan ke konten Anda (indeks, pengindeks, sumber data, peta sinonim) setelah Anda memberikan kunci tersebut pada permintaan.

Bermigrasi dari kunci ke peran

Jika Anda ingin beralih ke akses berbasis peran, sangat berguna untuk memahami bagaimana kunci akses dipetakan ke peran bawaan dalam Pencarian Azure AI:

Kunci admin sesuai dengan peran Kontributor Layanan Pencarian dan Kontributor Data Indeks Pencarian .
Kunci kueri sesuai dengan peran Pembaca Data Indeks Pencarian .

Kunci aman

Gunakan penetapan peran untuk membatasi akses ke kunci API.

Tidak dimungkinkan untuk menggunakan enkripsi kunci yang dikelola pelanggan untuk mengenkripsi kunci API. Hanya data sensitif dalam layanan pencarian itu sendiri (misalnya, konten indeks atau string koneksi dalam definisi objek sumber data) yang dapat dienkripsi CMK.

Buka layanan pencarian Anda di portal Azure.
Dari panel kiri, pilih Kontrol akses (IAM), lalu pilih tab Penetapan peran .
Di filter Peran, pilih peran yang memiliki izin untuk melihat atau mengelola kunci (Pemilik, Kontributor, Kontributor Layanan Pencarian). Prinsipal keamanan yang dihasilkan dan ditetapkan untuk peran tersebut memiliki izin kunci pada layanan pencarian Anda.
Sebagai tindakan pencegahan, periksa juga tab Administrator klasik untuk menentukan apakah administrator dan rekan administrator memiliki akses.

Praktik terbaik

Untuk beban kerja produksi, beralihlah ke Microsoft Entra ID dan akses berbasis peran. Atau, jika Anda ingin terus menggunakan kunci API, pastikan untuk selalu memantau siapa yang memiliki akses ke kunci API Anda dan meregenerasi kunci API pada irama biasa.
Hanya gunakan kunci API jika pengungkapan data bukan risiko (misalnya, saat menggunakan data sampel) dan jika Anda beroperasi di belakang firewall. Mengekspos kunci API membuat data dan layanan pencarian Anda berisiko digunakan secara tidak sah.
Jika Anda menggunakan kunci API, simpan dengan aman di tempat lain, seperti di Azure Key Vault. Jangan sertakan kunci API langsung dalam kode Anda, dan jangan pernah mempostingnya secara publik.
Selalu periksa kode, sampel, dan materi pelatihan sebelum menerbitkan untuk memastikan Anda tidak secara tidak sengaja mengekspos kunci API.

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-04-07

Bagikan melalui

Menyambungkan ke Pencarian Azure AI menggunakan kunci

Prasyarat

Diaktifkan secara default

Jenis kunci

Temukan kunci yang ada

Menggunakan kunci pada koneksi

Membuat kunci kueri

Meregenerasi kunci admin

Bermigrasi dari kunci ke peran

Kunci aman

Praktik terbaik

Konten terkait

Saran dan Komentar

Sumber Daya Tambahan: