Buat koneksi keluar menggunakan tautan privat yang dibagikan

Artikel ini menjelaskan cara mengonfigurasi tautan privat bersama untuk koneksi privat dan keluar dari Pencarian Azure AI ke sumber daya Azure yang berjalan di jaringan virtual. Dengan tautan privat bersama, layanan pencarian terhubung ke alamat IP jaringan virtual alih-alih titik akhir publik.

Tautan privat bersama adalah fitur premium yang ditagih berdasarkan penggunaan. Untuk detailnya, lihat Harga Azure Private Link.

Prasyarat

• Sumber daya Azure yang didukung dikonfigurasi untuk berjalan di jaringan virtual.

• Layanan Pencarian Azure AI. Persyaratan bervariasi menurut beban kerja:

  Beban kerja	Persyaratan tingkat	Persyaratan wilayah	Persyaratan pembuatan layanan
  Pengindeks tanpa keterampilan	Dasar dan lebih tinggi	Tidak	Tidak
  Kumpulan keterampilan dengan keterampilan penyematan (vektorisasi yang terintegrasi)	Dasar dan lebih tinggi	Wilayah kapasitas tinggi	Setelah 3 April 2024
  Keterampilan menggunakan keterampilan bawaan atau kustom lainnya	Standar 1 (S1) dan yang lebih tinggi	Tidak	Setelah 3 April 2024
  Pangkalan pengetahuan memanggil Azure OpenAI	Dasar dan lebih tinggi	Tidak	Tidak

• Kontributor atau Pemilik pada Pencarian Azure AI dan sumber daya Azure yang menjadi target, atau izin spesifik berikut:

  Sumber daya	Izin Akses
  Pencarian Azure AI	Microsoft.Search/searchServices/sharedPrivateLinkResources/write Microsoft.Search/searchServices/sharedPrivateLinkResources/read Microsoft.Search/searchServices/sharedPrivateLinkResources/operationStatuses/read
  Sumber daya Azure lainnya	Izin untuk menyetujui koneksi titik akhir privat. Misalnya, di Azure Storage, Anda memerlukan Microsoft.Storage/storageAccounts/privateEndpointConnectionsApproval/action.

Jenis sumber daya yang didukung

Anda dapat membuat tautan privat bersama untuk sumber daya berikut.

¹ Jika Azure Storage dan Pencarian Azure AI berada di wilayah yang sama, koneksi ke penyimpanan dibuat melalui jaringan backbone Microsoft, yang berarti tautan privat bersama tidak diperlukan untuk konfigurasi ini. Namun, jika Anda sudah menyiapkan titik akhir privat untuk Azure Storage, Anda juga harus menyiapkan tautan privat bersama atau koneksi ditolak di sisi penyimpanan. Selain itu, jika Anda menggunakan beberapa format penyimpanan untuk berbagai skenario dalam pencarian, pastikan untuk membuat tautan privat bersama terpisah untuk setiap sub-sumber daya.

² Jenis Microsoft.DocumentDB/databaseAccounts sumber daya digunakan untuk koneksi pengindeks ke Azure Cosmos DB for NoSQL. Nama penyedia dan ID grup peka huruf besar/kecil.

³ Jenis Microsoft.Sql/servers sumber daya digunakan untuk koneksi ke database Azure SQL. Saat ini tidak ada dukungan untuk tautan privat bersama ke Azure Synapse SQL.

⁴ Jenis Microsoft.Web/sites sumber daya digunakan untuk Layanan aplikasi dan fungsi Azure. Dalam konteks Pencarian Azure AI, fungsi Azure adalah skenario yang lebih mungkin. Fungsi Azure umumnya digunakan untuk menghosting logika keterampilan kustom. Azure Function memiliki paket hosting Consumption, Premium, dan Dedicated App Service. App Service Environment (ASE) dan Azure Kubernetes Service (AKS) tidak didukung saat ini. Untuk dukungan tautan privat bersama ke Azure API Management, gunakan jenis sumber daya Microsoft.ApiManagement/service.

⁵ Lihat Membuat tautan privat bersama untuk SQL Managed Instance untuk petunjuk.

⁶ Jenis Microsoft.CognitiveServices/accounts sumber daya ini digunakan untuk koneksi pemvektor dan pengindeksan ke model penyematan Azure OpenAI saat menerapkan vektorisasi terintegrasi. Ada dukungan untuk tautan privat yang dibagikan untuk mendukung embedding multimodal Azure Vision melalui sumber daya Microsoft Foundry.

⁷ Tautan privat bersama untuk Azure OpenAI hanya didukung di cloud publik dan Microsoft Azure Government. Penawaran cloud lainnya tidak memiliki dukungan untuk tautan privat yang dibagikan bersama untuk openai_account ID Grup.

⁸ Tautan privat bersama didukung untuk koneksi ke sumber daya Foundry. Untuk keterampilan sumber daya Foundry yang digunakan dalam pengayaan AI, Pencarian Azure AI menghubungkan dengan sumber daya Foundry untuk tujuan penagihan. Koneksi ini dapat bersifat privat melalui tautan privat bersama, yang hanya didukung saat mengonfigurasi identitas terkelola (konfigurasi tanpa kunci) dalam definisi set keterampilan.

⁹ Tautan privat bersama didukung untuk koneksi ke sumber daya Foundry. Untuk fitur model yang dihosting di Azure seperti fitur prompt GenAI, fitur penyematan Azure OpenAI, atau fitur Content Understanding, Pencarian Azure AI terhubung ke sumber daya Foundry untuk melakukan pemrosesan yang mendasar.

¹⁰ Tautan privat bersama didukung untuk koneksi ke ruang kerja OneLake. Untuk membuat sumber daya yang khusus untuk sebuah ruang kerja, daftarkan namespace ke langganan Anda dan rujuk langkah 2 seperti yang didokumentasikan dalam Membuat layanan tautan privat di Azure. Perhatikan bahwa saat menggunakan tautan privat bersama, konfigurasi sumber data OneLake harus didefinisikan dengan string koneksi tertentu seperti yang diuraikan dalam dokumentasi pengindeks OneLake.

¹¹ Jenis sumber daya Microsoft.ApiManagement/service memberikan konektivitas privat ke gateway Azure API Management yang berada di depan titik akhir model.

1 - Membuat tautan privat bersama

Gunakan portal Microsoft Azure, Management REST API, Azure CLI, atau Azure PowerShell untuk membuat tautan privat bersama.

Berikut adalah beberapa tips:

• Beri nama yang bermakna pada tautan privat. Di sumber daya Azure PaaS, Tautan Privat Bersama muncul bersama titik akhir privat lainnya. Nama seperti "shared-private-link-for-search" dapat mengingatkan Anda bagaimana cara penggunaannya.

Saat Anda menyelesaikan langkah-langkah di bagian ini, Anda memiliki tautan privat bersama yang disediakan dalam status tertunda. Dibutuhkan beberapa menit untuk membuat tautan. Setelah dibuat, pemilik sumber daya harus menyetujui permintaan sebelum beroperasi.

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

New-AzSearchSharedPrivateLinkResource -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -Name <spl-name> -PrivateLinkResourceId /subscriptions/<alphanumeric-subscription-ID>/resourceGroups/<storage-resource-group-name>/providers/Microsoft.Storage/storageAccounts/myBlobStorage -GroupId blob -RequestMessage "Please approve"

az search shared-private-link-resource list --service-name {{your-search-service-name}} --resource-group {{your-search-service-resource-group}}

az search shared-private-link-resource create --name {{your-shared-private-link-name}} --service-name {{your-search-service-name}} --resource-group {{your-search-service-resource-group}} --group-id Sql --resource-id "/subscriptions/{{your-subscription-ID}}/{{your-cosmos-db-resource-group}}/providers/Microsoft.DocumentDB/databaseAccounts/{{your-cosmos-db-account-name}}" 

Alur kerja pembuatan tautan privat bersama

Respons 202 Accepted dikembalikan jika berhasil. Proses pembuatan titik akhir privat keluar adalah operasi jangka panjang (asinkron). Ini melibatkan penyebaran sumber daya berikut:

• Titik akhir privat, dialokasikan dengan alamat IP privat dalam status "Pending" . Alamat IP privat diperoleh dari ruang alamat yang dialokasikan ke jaringan virtual lingkungan eksekusi untuk pengindeks privat khusus layanan pencarian. Setelah persetujuan titik akhir privat, komunikasi apa pun dari Pencarian Azure AI ke sumber daya Azure berasal dari alamat IP privat dan saluran tautan privat yang aman.

• Zona DNS privat untuk jenis sumber daya, berdasarkan ID grup. Dengan menyebarkan sumber daya ini, Anda memastikan bahwa setiap pencarian DNS ke sumber daya privat menggunakan alamat IP yang terkait dengan titik akhir privat.

2 - Menyetujui koneksi titik akhir privat

Persetujuan koneksi titik akhir privat diberikan di sisi Azure PaaS. Persetujuan eksplisit oleh pemilik sumber daya diperlukan. Langkah-langkah berikut mencakup persetujuan menggunakan portal Microsoft Azure, tetapi berikut adalah beberapa tautan untuk menyetujui koneksi secara terprogram dari sisi Azure PaaS:

• Di Azure Storage, gunakan Private Endpoint Connections - Put
• Di Azure Cosmos DB, gunakan Koneksi Titik Akhir Privat - Buat Atau Perbarui
• Di Azure OpenAI, gunakan Koneksi Titik Akhir Privat - Buat Atau Perbarui
• Di Microsoft Onelake, gunakan Titik Akhir Privat - Setujui melalui CLI atau Titik Akhir Privat - Setujui melalui Portal

Menggunakan portal Microsoft Azure, lakukan langkah-langkah berikut:

1. Buka halaman Jaringan sumber daya Azure PaaS. Teks

2. Temukan bagian yang mencantumkan koneksi titik akhir privat. Contoh berikut adalah untuk akun penyimpanan.

   

3. Pilih koneksi, lalu pilih Setujui. Diperlukan waktu beberapa menit agar status diperbarui di portal Microsoft Azure.

   

Setelah titik akhir privat disetujui, Pencarian Azure AI membuat pemetaan zona DNS yang diperlukan di zona DNS yang dibuat untuknya.

Meskipun tautan titik akhir privat di halaman Jaringan aktif, tautan tersebut tidak dapat diselesaikan.

Memilih tautan akan menghasilkan kesalahan. Pesan status "The access token is from the wrong issuer" dan must match the tenant associated with this subscription muncul karena sumber daya titik akhir privat backend disediakan oleh Microsoft di penyewa yang dikelola oleh Microsoft, sementara sumber daya tertaut (Pencarian Azure AI) berada di penyewa Anda. Secara desain Anda tidak dapat mengakses sumber daya titik akhir privat dengan memilih tautan koneksi titik akhir privat.

Ikuti instruksi di bagian berikutnya untuk memeriksa status tautan privat yang dibagikan.

3 - Periksa status tautan privat yang dibagikan

Di sisi Pencarian Azure AI, Anda dapat mengonfirmasi persetujuan permintaan dengan mengunjungi kembali halaman Akses Privat Bersama dari halaman Jaringan layanan pencarian. Status koneksi harus disetujui.

Atau, Anda juga dapat memperoleh status koneksi dengan menggunakan Sumber Daya Tautan Privat Bersama - Ambil.

az rest --method get --uri https://management.azure.com/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/contoso/providers/Microsoft.Search/searchServices/contoso-search/sharedPrivateLinkResources/blob-pe?api-version=2025-05-01

Ini akan mengembalikan JSON, di mana status koneksi muncul sebagai "status" di bawah bagian "properti". Berikut ini adalah contoh untuk akun penyimpanan.

{
      "name": "blob-pe",
      "properties": {
        "privateLinkResourceId": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/contoso/providers/Microsoft.Storage/storageAccounts/contoso-storage",
        "groupId": "blob",
        "requestMessage": "please approve",
        "status": "Approved",
        "resourceRegion": null,
        "provisioningState": "Succeeded"
      }
}

Jika status penyediaan (properties.provisioningState) sumber daya adalah "Berhasil" dan status koneksi (properties.status) adalah "Disetujui", itu berarti bahwa sumber daya tautan privat bersama berfungsi dan pengindeks dapat dikonfigurasi untuk berkomunikasi melalui titik akhir privat.

4 - Mengonfigurasi pengindeks untuk dijalankan di lingkungan privat

Pelaksanaan pengindeks terjadi di lingkungan privat yang khusus untuk layanan pencarian, atau lingkungan multipenyewa yang digunakan secara internal untuk mengurangi beban pemrosesan sekumpulan keterampilan yang mahal untuk beberapa pelanggan.

Lingkungan eksekusi transparan, tetapi setelah Anda mulai membangun aturan firewall atau membuat koneksi privat, Anda harus memperhitungkan eksekusi pengindeks. Untuk koneksi privat, konfigurasikan eksekusi pengindeks untuk selalu berjalan di lingkungan privat.

Langkah ini menunjukkan kepada Anda cara mengonfigurasi pengindeks untuk berjalan di lingkungan privat menggunakan REST API. Anda juga dapat mengatur lingkungan eksekusi menggunakan editor JSON di portal Microsoft Azure.

1. Buat definisi sumber data, indeks, dan set keterampilan (jika Anda menggunakannya) seperti biasa. Tidak ada properti dalam salah satu definisi ini yang berubah saat menggunakan endpoint privat bersama.

2. Buat pengindeks yang menunjuk ke sumber data, indeks, dan set keterampilan yang Anda buat di langkah sebelumnya. Selain itu, paksa pengindeks untuk berjalan di lingkungan eksekusi privat dengan mengatur properti konfigurasi pengindeks executionEnvironment ke private.

   {
       "name": "indexer",
       "dataSourceName": "blob-datasource",
       "targetIndexName": "index",
       "parameters": {
           "configuration": {
               "executionEnvironment": "private"
           }
       },
       "fieldMappings": []
   }
   

Setelah pengindeks berhasil dibuat, pengindeks harus terhubung ke sumber daya Azure melalui koneksi titik akhir privat. Anda dapat memantau status pengindeks dengan menggunakan API Status Pengindeks.

5 - Menguji tautan privat bersama

1. Jika Anda belum melakukannya, verifikasi bahwa sumber daya Azure PaaS Anda menolak koneksi dari internet publik. Jika koneksi diterima, tinjau pengaturan DNS di halaman Jaringan sumber daya Azure PaaS Anda.

2. Pilih alat yang dapat memanggil skenario permintaan keluar, seperti koneksi pengindeks ke titik akhir privat. Pilihan mudah adalah menggunakan wizard impor, tetapi Anda juga dapat mencoba klien REST dan REST API untuk presisi lebih. Dengan asumsi bahwa layanan pencarian Anda tidak juga dikonfigurasi untuk koneksi privat, koneksi klien REST untuk pencarian dapat melalui internet publik.

3. Atur string koneksi ke sumber daya Azure PaaS privat. Format string sambungan tidak berubah untuk tautan privat yang dibagi. Layanan pencarian memanggil tautan privat bersama secara internal.

   Untuk beban kerja pengindeks, string koneksi ada dalam definisi sumber data. Contoh sumber data mungkin terlihat seperti ini:

    {
      "name": "my-blob-ds",
      "type": "azureblob",
      "subtype": null,
      "credentials": {
        "connectionString": "DefaultEndpointsProtocol=https;AccountName=<YOUR-STORAGE-ACCOUNT>;AccountKey=..."
      }
   

4. Untuk beban kerja pengindeks, ingatlah untuk mengatur lingkungan eksekusi dalam definisi pengindeks. Contoh definisi pengindeks mungkin terlihat seperti ini:

   "name": "indexer",
   "dataSourceName": "my-blob-ds",
   "targetIndexName": "my-index",
   "parameters": {
      "configuration": {
          "executionEnvironment": "private"
          }
      },
   "fieldMappings": []
   }
   

5. Jalankan pengindeks. Jika eksekusi pengindeks berhasil dan indeks pencarian diisi, tautan privat bersama berfungsi.

Kapan menggunakan tautan privat bersama

Pencarian Azure AI melakukan panggilan keluar ke sumber daya Azure lainnya dalam skenario berikut:

• Koneksi basis pengetahuan ke Azure OpenAI untuk alur kerja pengambilan data secara agen
• Pengindeks atau koneksi kueri ke Azure OpenAI atau Azure Vision di Foundry Tools untuk vektorisasi
• Koneksi pengindeks ke sumber data yang didukung
• Koneksi pengindeks (skillset) ke Azure Storage untuk menyimpan cache hasil pengayaan atau menulis ke penyimpanan pengetahuan
• Koneksi Indexer (skillset) ke Foundry Tools untuk keperluan penagihan.
• Permintaan kunci enkripsi ke Azure Key Vault
• Permintaan keterampilan kustom ke Azure Functions atau sumber daya serupa

Tautan privat bersama hanya berfungsi untuk koneksi Azure-ke-Azure. Jika Anda tersambung ke OpenAI atau penyedia model eksternal lainnya, koneksi harus melalui internet publik.

Tautan privat yang dibagikan adalah untuk operasi dan data yang diakses melalui titik akhir privat untuk sumber daya atau klien Azure yang berjalan di dalam jaringan virtual Azure.

Tautan privat yang dibagikan adalah:

• Dibuat menggunakan alat, API, atau SDK Pencarian Azure AI
• Disetujui oleh pemilik sumber daya Azure
• Digunakan secara internal oleh Pencarian Azure AI pada koneksi privat ke sumber daya Azure tertentu

Hanya layanan pencarian Anda yang dapat menggunakan tautan privat yang dibuatnya, dan hanya ada satu tautan privat bersama yang dibuat pada layanan Anda untuk setiap kombinasi sumber daya dan sub sumber daya.

Setelah Anda menyiapkan tautan privat, tautan tersebut digunakan secara otomatis setiap kali layanan pencarian terhubung ke sumber daya tersebut. Anda tidak perlu mengubah string koneksi atau mengubah klien yang Anda gunakan untuk mengeluarkan permintaan, meskipun perangkat yang digunakan untuk koneksi harus tersambung menggunakan IP resmi di firewall sumber daya Azure.

Ada dua skenario untuk menggunakan Azure Private Link dan Pencarian Azure AI bersama-sama:

• Skenario satu: membuat tautan privat bersama saat koneksi keluar (pengindeks atau pangkalan pengetahuan) ke Azure memerlukan koneksi privat. Skenario ini dibahas dalam artikel ini.

• Skenario dua: mengonfigurasi pencarian koneksi masuk privat dari klien yang berjalan di jaringan virtual.

Meskipun kedua skenario memiliki dependensi pada Azure Private Link, keduanya independen. Anda dapat membuat tautan privat yang dapat dibagikan tanpa mengonfigurasi layanan pencarian Anda untuk titik akhir privat.

Keterbatasan

Saat mengevaluasi tautan pribadi yang dibagikan untuk skenario Anda, ingat batasan ini:

• Beberapa jenis sumber daya yang digunakan dalam tautan pribadi yang dibagikan sedang dalam pratinjau. Jika Anda menyambungkan ke sumber daya pratinjau (Azure Database for MySQL atau Azure SQL Managed Instance), gunakan versi pratinjau API REST Manajemen untuk membuat tautan privat bersama. Kami merekomendasikan versi API pratinjau terbaru.

• Eksekusi pengindeks harus menggunakan lingkungan eksekusi privat yang khusus untuk layanan pencarian Anda. Koneksi titik akhir privat tidak didukung dari lingkungan pemrosesan konten multipenyewa. Pengaturan konfigurasi untuk persyaratan ini tercakup dalam artikel ini.

• Batas sumber daya tautan privat yang dibagikan bervariasi menurut tingkat harga.

• Sesi debug tidak mendukung tautan privat bersama. Jika layanan pencarian Anda menggunakan konektivitas titik akhir privat, Anda tidak dapat menjalankan sesi debug terhadapnya. Untuk solusinya, lihat Sesi debug dan konektivitas privat.

• Saat Anda mengubah tingkat harga, sumber daya tautan privat yang dibagikan diukur berdasarkan batas tingkat target. Jika jumlah tautan rahasia yang Anda bagikan melebihi maksimum tingkatan sasaran, perubahan tingkatan diblokir. Jika perubahan tingkat berhasil, sumber daya tautan privat bersama yang ada tidak dibuat ulang dan tidak memerlukan persetujuan ulang. Konektivitas pengindeks privat terus berfungsi setelah layanan pencarian kembali ke status provisi "Berhasil" dan status "Berjalan", asalkan status penyediaan tautan privat bersama tetap "Berhasil" dan status koneksi tetap "Disetujui."

Pemecahan masalah

• Jika pembuatan pengindeks Anda gagal dengan "Kredensial sumber data tidak valid," periksa status persetujuan tautan privat bersama sebelum men-debug koneksi. Jika statusnya adalah Approved, periksa properties.provisioningState properti . Jika itu Incomplete, mungkin ada masalah dengan dependensi yang mendasar. Dalam hal ini, ulang terbitkan PUT permintaan untuk membuat ulang tautan pribadi bersama. Anda mungkin juga perlu mengulangi langkah persetujuan.

• Jika pengindeks gagal secara konsisten atau terputus-putus, periksa executionEnvironment properti pada pengindeks. Nilai harus diatur ke private. Jika Anda tidak mengatur properti ini, dan pengoperasian pengindeks berhasil di masa lalu, itu karena layanan pencarian menggunakan lingkungan privat secara otomatis. Layanan pencarian memindahkan pemrosesan keluar dari lingkungan multi-penyewa jika sistem mengalami beban kerja.

• Jika Anda mendapatkan kesalahan saat membuat tautan privat yang dibagikan, periksa batas layanan untuk memverifikasi bahwa Anda masih dalam kuota untuk tingkatan Anda.

Langkah berikutnya

Pelajari selengkapnya tentang titik akhir privat dan metode koneksi aman lainnya:

• Memecahkan masalah dengan sumber daya tautan privat bersama
• Apa itu titik akhir privat?
• Konfigurasi DNS diperlukan untuk titik akhir privat
• Akses pengindeks ke konten yang dilindungi oleh fitur keamanan jaringan Azure