Mulai cepat: Menyambungkan ke layanan pencarian

Dalam panduan cepat ini, Anda menggunakan kontrol akses berbasis peran (RBAC) dan ID Microsoft Entra untuk membuat koneksi tanpa autentikasi kunci ke layanan Azure AI Search Anda. Anda kemudian menggunakan Python di Visual Studio Code untuk berinteraksi dengan layanan Anda.

Koneksi tanpa kunci memberikan keamanan yang ditingkatkan melalui izin terperinci dan autentikasi berbasis identitas. Kami tidak merekomendasikan kunci API yang dikodekan secara permanen, tetapi jika Anda lebih suka, lihat Menyambungkan ke Azure AI Search menggunakan kunci.

Prasyarat

Mengonfigurasi akses berbasis peran

Di bagian ini, Anda mengaktifkan RBAC pada layanan Azure AI Search dan menetapkan peran yang diperlukan untuk membuat, memuat, dan mengkueri objek pencarian. Untuk informasi selengkapnya tentang langkah-langkah ini, lihat Menyambungkan ke Pencarian Azure AI menggunakan peran.

Untuk mengonfigurasi akses:

  1. Buka layanan pencarian Anda di portal Microsoft Azure.

  2. Dari panel kiri, pilih Tombol Pengaturan>.

  3. Pilih Kontrol akses berbasis peran atau Keduanya jika Anda memerlukan waktu untuk transisi klien ke RBAC.

    Cuplikan layar opsi kontrol akses di portal Microsoft Azure.

  4. Dari panel kiri, pilih Kontrol akses (IAM).

  5. Pilih Tambah>Tambahkan penugasan peran.

    Cuplikan layar menu dropdown untuk menambahkan penetapan peran di portal Microsoft Azure.

  6. Tetapkan peran Kontributor Layanan Pencarian ke akun pengguna atau identitas terkelola Anda.

  7. Ulangi penetapan peran untuk Kontributor Data Indeks Pencarian.

Mendapatkan informasi layanan

Di bagian ini, Anda mengambil ID langganan dan titik akhir layanan Azure AI Search Anda. Jika Anda hanya memiliki satu langganan, lewati ID langganan dan hanya ambil titik akhir. Anda menggunakan nilai-nilai ini di bagian yang tersisa dari panduan cepat ini.

Untuk mendapatkan informasi layanan Anda:

  1. Buka layanan pencarian Anda di portal Microsoft Azure.

  2. Dari panel kiri, pilih Gambaran Umum.

  3. Catat ID langganan dan titik akhir.

    Cuplikan layar ID langganan dan titik akhir di portal Microsoft Azure.

Masuk ke Azure

Sebelum Anda menyambungkan ke layanan Azure AI Search, gunakan Azure CLI untuk masuk ke langganan yang berisi layanan Anda. Langkah ini menetapkan identitas Microsoft Entra Anda, yang DefaultAzureCredential digunakan untuk mengautentikasi permintaan di bagian berikutnya.

Untuk masuk:

  1. Pada sistem lokal Anda, buka alat baris perintah.

  2. Periksa langganan aktif dan penyewa di lingkungan lokal Anda.

    az account show

  3. Jika langganan dan penyewa aktif tidak valid untuk layanan pencarian Anda, jalankan perintah berikut untuk memperbarui nilainya. Anda dapat menemukan ID langganan di halaman Gambaran Umum layanan pencarian di portal Microsoft Azure. Untuk menemukan ID penyewa, pilih nama langganan Anda di halaman Gambaran Umum , lalu temukan nilai Grup manajemen induk .

     az account set --subscription <your-subscription-id>

 az login --tenant <your-tenant-id>

Nota

Bagian ini mengilustrasikan pola Python dasar untuk koneksi tanpa kunci. Untuk panduan komprehensif, lihat tutorial tertentu atau panduan memulai cepat, seperti Panduan Memulai Cepat: Pengambilan berbasis agen.

Anda bisa menggunakan buku catatan Python di Visual Studio Code untuk mengirim permintaan ke layanan Azure AI Search Anda. Untuk autentikasi permintaan, gunakan DefaultAzureCredential kelas dari pustaka Azure Identity.

Untuk menyambungkan menggunakan Python:

  1. Di sistem lokal Anda, buka Visual Studio Code.

  2. Buat file .ipynb.

  3. Buat sel kode untuk menginstal pustaka-pustaka azure-identity dan azure-search-documents.

    pip install azure-identity azure-search-documents

  4. Buat sel kode lain untuk mengautentikasi dan menyambungkan ke layanan pencarian Anda.

    import json
from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient

service_endpoint = "PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE"
credential = DefaultAzureCredential()
client = SearchIndexClient(endpoint = service_endpoint, credential = credential)

# List existing indexes
indexes = client.list_indexes()

for index in indexes:
   index_dict = index.as_dict()
   print(json.dumps(index_dict, indent = 2))

  5. Atur service_endpoint ke nilai yang Anda peroleh di Dapatkan informasi layanan.

  6. Pilih Jalankan Semua untuk menjalankan kedua sel kode.

    Output harus mencantumkan indeks yang ada (jika ada) pada layanan pencarian Anda, menunjukkan koneksi yang berhasil.

Memecahkan masalah kesalahan 401

Jika Anda mengalami kesalahan 401, ikuti langkah-langkah pemecahan masalah berikut:

  • Tinjau kembali Mengonfigurasi akses berbasis peran. Layanan pencarian Anda harus memiliki kontrol akses berbasis Peran atau Keduanya diaktifkan. Kebijakan di tingkat langganan atau grup sumber daya mungkin menimpa penetapan peran Anda.

  • Kunjungi Kembali Masuk ke Azure. Anda harus masuk ke langganan yang berisi layanan pencarian Anda.

  • Pastikan variabel titik akhir Anda memiliki tanda kutip di sekitarnya.

  • Jika semua gagal, mulai ulang perangkat Anda untuk menghapus token yang di-cache lalu ulangi langkah-langkah dalam mulai cepat ini, dimulai dengan Masuk ke Azure.

Dalam panduan cepat ini, Anda menggunakan kontrol akses berbasis peran (RBAC) dan ID Microsoft Entra untuk membuat koneksi tanpa autentikasi kunci ke layanan Azure AI Search Anda. Anda kemudian menggunakan REST di Visual Studio Code untuk berinteraksi dengan layanan Anda.

Koneksi tanpa kunci memberikan keamanan yang ditingkatkan melalui izin terperinci dan autentikasi berbasis identitas. Kami tidak merekomendasikan kunci API yang dikodekan secara permanen, tetapi jika Anda lebih suka, lihat Menyambungkan ke Azure AI Search menggunakan kunci.

Prasyarat

Mengonfigurasi akses berbasis peran

Di bagian ini, Anda mengaktifkan RBAC pada layanan Azure AI Search dan menetapkan peran yang diperlukan untuk membuat, memuat, dan mengkueri objek pencarian. Untuk informasi selengkapnya tentang langkah-langkah ini, lihat Menyambungkan ke Pencarian Azure AI menggunakan peran.

Untuk mengonfigurasi akses:

  1. Buka layanan pencarian Anda di portal Microsoft Azure.

  2. Dari panel kiri, pilih Tombol Pengaturan>.

  3. Pilih Kontrol akses berbasis peran atau Keduanya jika Anda memerlukan waktu untuk transisi klien ke RBAC.

    Cuplikan layar opsi kontrol akses di portal Microsoft Azure.

  4. Dari panel kiri, pilih Kontrol akses (IAM).

  5. Pilih Tambah>Tambahkan penugasan peran.

    Cuplikan layar menu dropdown untuk menambahkan penetapan peran di portal Microsoft Azure.

  6. Tetapkan peran Kontributor Layanan Pencarian ke akun pengguna atau identitas terkelola Anda.

  7. Ulangi penetapan peran untuk Kontributor Data Indeks Pencarian.

Mendapatkan informasi layanan

Di bagian ini, Anda mengambil ID langganan dan titik akhir layanan Azure AI Search Anda. Jika Anda hanya memiliki satu langganan, lewati ID langganan dan hanya ambil titik akhir. Anda menggunakan nilai-nilai ini di bagian yang tersisa dari panduan cepat ini.

Untuk mendapatkan informasi layanan Anda:

  1. Buka layanan pencarian Anda di portal Microsoft Azure.

  2. Dari panel kiri, pilih Gambaran Umum.

  3. Catat ID langganan dan titik akhir.

    Cuplikan layar ID langganan dan titik akhir di portal Microsoft Azure.

Masuk ke Azure

Sebelum Anda menyambungkan ke layanan Azure AI Search, gunakan Azure CLI untuk masuk ke langganan yang berisi layanan Anda.

Untuk masuk:

  1. Pada sistem lokal Anda, buka alat baris perintah.

  2. Periksa langganan aktif dan penyewa di lingkungan lokal Anda.

    az account show

  3. Jika langganan dan penyewa aktif tidak valid untuk layanan pencarian Anda, jalankan perintah berikut untuk memperbarui nilainya. Anda dapat menemukan ID langganan di halaman Gambaran Umum layanan pencarian di portal Microsoft Azure. Untuk menemukan ID penyewa, pilih nama langganan Anda di halaman Gambaran Umum , lalu temukan nilai Grup manajemen induk .

     az account set --subscription <your-subscription-id>

 az login --tenant <your-tenant-id>

Dapatkan token

Panggilan REST API memerlukan penyertaan token ID Microsoft Entra. Anda menggunakan token ini untuk mengautentikasi permintaan di bagian berikutnya.

Untuk mendapatkan token Anda:

  1. Menggunakan alat baris perintah yang sama, hasilkan token akses.

    az account get-access-token --scope https://search.azure.com/.default --query accessToken --output tsv

  2. Catat keluaran token.

Nota

Bagian ini mengilustrasikan pola REST dasar untuk koneksi tanpa kunci. Untuk panduan komprehensif, lihat tutorial tertentu atau panduan memulai cepat, seperti Panduan Memulai Cepat: Pengambilan berbasis agen.

Anda dapat menggunakan ekstensi Klien REST di Visual Studio Code untuk mengirim permintaan ke layanan Azure AI Search Anda. Untuk autentikasi permintaan, sertakan Authorization header dengan token ID Microsoft Entra yang sebelumnya Anda buat.

Untuk menyambungkan menggunakan REST:

  1. Di sistem lokal Anda, buka Visual Studio Code.

  2. Buat .rest file atau .http .

  3. Tempelkan variabel dan permintaan berikut ke dalam file.

    @baseUrl = PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE
@token = PUT-YOUR-PERSONAL-IDENTITY-TOKEN-HERE

### List existing indexes
GET {{baseUrl}}/indexes?api-version=2025-09-01  HTTP/1.1
   Content-Type: application/json
   Authorization: Bearer {{token}}

  4. Atur @baseUrl ke nilai yang Anda peroleh di Dapatkan informasi layanan.

  5. Atur @token ke nilai yang Anda peroleh di Dapatkan token.

  6. Di bawah ### List existing indexes, pilih Kirim Permintaan.

    Anda harus menerima HTTP/1.1 200 OK respons, yang menunjukkan keberhasilan koneksi ke layanan pencarian Anda.

Memecahkan masalah kesalahan 401

Jika Anda mengalami kesalahan 401, ikuti langkah-langkah pemecahan masalah berikut:

  • Tinjau kembali Mengonfigurasi akses berbasis peran. Layanan pencarian Anda harus memiliki kontrol akses berbasis Peran atau Keduanya diaktifkan. Kebijakan di tingkat langganan atau grup sumber daya mungkin menimpa penetapan peran Anda.

  • Kunjungi Kembali Masuk ke Azure. Anda harus masuk ke langganan yang berisi layanan pencarian Anda.

  • Pastikan titik akhir dan variabel token Anda tidak memiliki tanda kutip atau spasi tambahan di sekitarnya.

  • Pastikan token Anda tidak memiliki @ simbol di header permintaan. Misalnya, jika variabel adalah @token, referensi dalam permintaan harus {{token}}.

  • Jika semua gagal, mulai ulang perangkat Anda untuk menghapus token yang di-cache lalu ulangi langkah-langkah dalam mulai cepat ini, dimulai dengan Masuk ke Azure.

Konten terkait

  • Last updated on