Membuat Sumber Data (Azure AI Search REST API)

Artikel
03/05/2024

Di Pencarian Azure AI, sumber data digunakan dengan pengindeks, menyediakan informasi koneksi sesuai permintaan atau refresh data terjadwal dari indeks target, menarik data dari sumber data Azure yang didukung.

Anda dapat menggunakan POST atau PUT pada permintaan. Untuk salah satu, dokumen JSON dalam isi permintaan menyediakan definisi objek.

POST https://[service name].search.windows.net/datasources?api-version=[api-version]  
    Content-Type: application/json  
    api-key: [admin key]

Atau, Anda dapat menggunakan PUT dan menentukan nama pada URI.

PUT https://[service name].search.windows.net/datasources/[data source name]?api-version=[api-version]
    Content-Type: application/json  
    api-key: [admin key]

HTTPS diperlukan untuk semua permintaan layanan. Jika objek tidak ada, objek akan dibuat. Jika sudah ada, itu diperbarui ke definisi baru.

Catatan

Jumlah maksimum indeks yang dapat Anda buat bervariasi menurut tingkat harga. Untuk informasi selengkapnya, lihat Batas layanan.

Parameter URI

Parameter	Deskripsi
nama layanan	Wajib diisi. Atur ini ke nama unik yang ditentukan pengguna dari layanan pencarian Anda.
nama sumber data	Diperlukan pada URI jika menggunakan PUT. Nama harus huruf kecil, dimulai dengan huruf atau angka, tidak memiliki garis miring atau titik, dan kurang dari 128 karakter. Nama harus dimulai dengan huruf atau angka, tetapi nama lainnya dapat menyertakan huruf, angka, dan tanda hubung apa pun, selama tanda hubung tidak berturut-turut.
versi-api	Wajib diisi. Lihat versi API untuk daftar versi yang didukung.

Judul Permintaan

Tabel berikut ini menjelaskan header permintaan yang diperlukan dan opsional.

Bidang	Deskripsi
Jenis-Konten	Wajib diisi. Atur titik akhir ini ke `application/json`
api-key	Opsional jika Anda menggunakan peran Azure dan token pembawa disediakan berdasarkan permintaan, jika tidak, kunci diperlukan. Membuat permintaan harus menyertakan header yang `api-key` diatur ke kunci admin Anda (dibandingkan dengan kunci kueri). Lihat Menyambungkan ke Pencarian Azure AI menggunakan autentikasi kunci untuk detailnya.

Isi Permintaan

Isi permintaan berisi definisi sumber data, yang mencakup jenis sumber data, kredensial untuk membaca data, serta deteksi perubahan data opsional dan kebijakan deteksi penghapusan data yang digunakan untuk mengidentifikasi data yang diubah atau dihapus secara efisien di sumber data saat digunakan dengan pengindeks terjadwal secara berkala.

JSON berikut adalah representasi tingkat tinggi dari bagian utama definisi.

{   
    "name" : (optional on PUT; required on POST) "Name of the data source",  
    "description" : (optional) "Anything you want, or nothing at all",  
    "type" : (required) "Must be a supported data source",
    "credentials" : (required) { "connectionString" : "Connection string for your data source" },
    "container": {
        "name": "Name of the table, view, collection, or blob container you wish to index",
        "query": (optional) 
    },
    "dataChangeDetectionPolicy" : (optional) {See below for details },
    "dataDeletionDetectionPolicy" : (optional) {See below for details },
    "encryptionKey":(optional) { }
}

Permintaan berisi properti berikut:

Properti	Deskripsi
nama	Wajib diisi. Nama sumber data. Nama sumber data hanya boleh berisi huruf kecil, digit, atau tanda hubung, tidak dapat dimulai atau diakhir dengan tanda hubung dan dibatasi hingga 128 karakter.
deskripsi	Deskripsi opsional.
jenis	Wajib diisi. Harus menjadi salah satu jenis sumber data yang didukung: `azuresql` untuk Azure SQL Database, Azure SQL Managed Instance, atau instans SQL Server yang berjalan di Azure VM `cosmosdb` untuk Azure Cosmos DB for NoSQL, Azure Cosmos DB for MongoDB (pratinjau) atau Azure Cosmos DB for Apache Gremlin (pratinjau) `azureblob` untuk Azure Blob Storage `adlsgen2`untuk Azure Data Lake Storage Gen2 `azuretable`azure Table Storage `azurefile` for Azure Files (pratinjau) `mysql` untuk Azure Database for MySQL ( pratinjau) `sharepoint` untuk SharePoint di Microsoft 365(pratinjau)
informasi masuk	Wajib diisi. Ini berisi `connectionString` properti yang menentukan string koneksi untuk sumber data. Format string koneksi tergantung pada jenis sumber data: Untuk database Azure SQL, ini adalah SQL Server string koneksi yang biasa. Jika Anda menggunakan portal Azure untuk mengambil string koneksi, pilih `ADO.NET connection string` opsi . Untuk Azure Cosmos DB, string koneksi harus dalam format berikut: `"AccountEndpoint=https://[your account name].documents.azure.com;AccountKey=[your account key];Database=[your database id]"`. Semua nilai diperlukan. Anda dapat menemukannya di portal Azure. Untuk Azure Blob Storage, format string koneksi ditentukan di bagian Kredensial dari Cara mengonfigurasi pengindeksan blob di Azure AI Search. Azure Storage, Azure SQL Database, dan Azure Cosmos DB juga mendukung string koneksi identitas terkelola yang tidak menyertakan kunci akun dalam string koneksi. Untuk menggunakan format string koneksi identitas terkelola, ikuti instruksi untuk Menyiapkan koneksi pengindeks ke sumber data menggunakan identitas terkelola. Jika Anda memperbarui sumber data, string koneksi tidak diperlukan. `<unchanged>` Nilai atau `<redacted>` dapat digunakan sebagai pengganti string koneksi aktual.
kontainer	Wajib diisi. Menentukan data yang akan diindeks menggunakan `name` properti (wajib) dan `query` (opsional):`name` : Untuk Azure SQL, menentukan tabel atau tampilan. Anda dapat menggunakan nama yang memenuhi syarat skema, seperti `[dbo].[mytable]`. Untuk Azure Cosmos DB, menentukan koleksi SQL API. Untuk Azure Blob Storage, menentukan kontainer penyimpanan. Untuk Azure Table Storage, menentukan nama tabel. `query`: Untuk Azure Cosmos DB, memungkinkan Anda menentukan kueri yang meratakan tata letak dokumen JSON arbitrer ke dalam skema datar yang dapat diindeks oleh Azure AI Search. Untuk Azure Blob Storage, memungkinkan Anda menentukan folder virtual dalam kontainer blob. Misalnya, untuk jalur `mycontainer/documents/blob.pdf`blob , `documents` dapat digunakan sebagai folder virtual. Untuk Azure Table Storage, memungkinkan Anda menentukan kueri yang memfilter kumpulan baris yang akan diimpor. Untuk Azure SQL, kueri tidak didukung. Gunakan tampilan sebagai gantinya.
dataChangeDetectionPolicy	Pilihan. Digunakan untuk mengidentifikasi item data yang diubah. Kebijakan yang didukung bervariasi berdasarkan jenis sumber data. Kebijakan yang valid adalah Kebijakan Deteksi Perubahan Marka Air Tinggi dan Kebijakan Deteksi Perubahan Terintegrasi SQL. Kebijakan Deteksi Perubahan Marka Air Tinggi bergantung pada kolom atau properti yang ada yang diperbarui bersama dengan pembaruan lain (semua sisipan menghasilkan pembaruan pada kolom marka air), dan perubahan nilainya lebih tinggi. Untuk sumber data Cosmos DB, Anda harus menggunakan `_ts` properti . Untuk Azure SQL, kolom terindeks `rowversion` adalah kandidat ideal untuk digunakan dengan kebijakan tanda air tinggi. Untuk Azure Storage, deteksi perubahan bawaan menggunakan nilai lastModified, menghilangkan kebutuhan apa pun untuk mengatur dataChangeDetectionPolicy untuk penyimpanan blob atau tabel. Kebijakan Deteksi Perubahan Terintegrasi SQL digunakan untuk mereferensikan fitur deteksi perubahan asli di SQL Server. Kebijakan ini hanya dapat digunakan dengan tabel; tidak dapat digunakan dengan tampilan. Anda perlu mengaktifkan pelacakan perubahan untuk tabel yang Anda gunakan sebelum dapat menggunakan kebijakan ini. Lihat Mengaktifkan dan menonaktifkan pelacakan perubahan untuk instruksi. Untuk informasi selengkapnya tentang dukungan deteksi perubahan di pengindeks, lihat Menyambungkan ke dan mengindeks konten Azure SQL.
dataDeletionDetectionPolicy	Pilihan. Digunakan untuk mengidentifikasi item data yang dihapus. Saat ini, satu-satunya kebijakan yang didukung adalah Kebijakan Penghapusan Sementara, yang mengidentifikasi item yang dihapus berdasarkan nilai kolom atau properti 'penghapusan sementara' di sumber data. Hanya kolom dengan nilai string, bilangan bulat, atau boolean yang didukung. Nilai yang digunakan sebagai `softDeleteMarkerValue` harus berupa string, meskipun kolom yang sesuai menyimpan bilangan bulat atau boolean. Misalnya, jika nilai yang muncul di sumber data Anda adalah 1, gunakan "1" sebagai `softDeleteMarkerValue`.
encryptionKey	Pilihan. Digunakan untuk mengenkripsi sumber data tidak aktif dengan kunci Anda sendiri, yang dikelola di Key Vault Azure Anda. Tersedia untuk layanan pencarian yang dapat ditagih yang dibuat pada atau setelah 2019-01-01. Bagian `encryptionKey` berisi yang ditentukan `keyVaultKeyName` pengguna (diperlukan), yang dihasilkan `keyVaultKeyVersion` sistem (diperlukan), dan `keyVaultUri` menyediakan kunci (diperlukan, juga disebut sebagai nama DNS). Contoh URI mungkin "https://my-keyvault-name.vault.azure.net". Secara opsional, Anda dapat menentukan `accessCredentials` apakah Anda tidak menggunakan identitas sistem terkelola. Properti termasuk `accessCredentialsapplicationId` (Microsoft Entra ID ID aplikasi yang diberikan izin akses ke Key Vault Azure yang Anda tentukan), dan `applicationSecret` (kunci autentikasi aplikasi terdaftar). Contoh di bagian berikutnya mengilustrasikan sintaks.

Respons

Untuk permintaan yang berhasil: 201 Dibuat.

Contoh

Contoh: Azure SQL dengan deteksi perubahan (Kebijakan Deteksi Perubahan Marka Air Tinggi)

{   
    "name" : "asqldatasource",  
    "description" : "a description",  
    "type" : "azuresql",  
    "credentials" : { "connectionString" : "Server=tcp:....database.windows.net,1433;Database=...;User ID=...;Password=...;Trusted_Connection=False;Encrypt=True;Connection Timeout=30;" },  
    "container" : { "name" : "sometable" },  
    "dataChangeDetectionPolicy" : { "@odata.type" : "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy", "highWaterMarkColumnName" : "RowVersion" }
}

Contoh: Azure SQL dengan deteksi perubahan (Kebijakan Pelacakan Perubahan Terintegrasi SQL)

{   
    "name" : "asqldatasource",  
    "description" : "a description",  
    "type" : "azuresql",  
    "credentials" : { "connectionString" : "Server=tcp:....database.windows.net,1433;Database=...;User ID=...;Password=...;Trusted_Connection=False;Encrypt=True;Connection Timeout=30;" },  
    "container" : { "name" : "sometable" },  
    "dataChangeDetectionPolicy" : { "@odata.type" : "#Microsoft.Azure.Search.SqlIntegratedChangeTrackingPolicy" }
}

Contoh: Azure SQL dengan deteksi perubahan dengan deteksi penghapusan

Ingat bahwa properti untuk deteksi penghapusan adalah softDeleteColumnName dan softDeleteMarkerValue.

{   
    "name" : "asqldatasource",  
    "description" : "a description",  
    "type" : "azuresql",  
    "credentials" : { "connectionString" : "Server=tcp:....database.windows.net,1433;Database=...;User ID=...;Password=...;Trusted_Connection=False;Encrypt=True;Connection Timeout=30;" },  
    "container" : { "name" : "sometable" },   
    "dataDeletionDetectionPolicy" : { "@odata.type" : "#Microsoft.Azure.Search.SoftDeleteColumnDeletionDetectionPolicy", "softDeleteColumnName" : "IsDeleted", "softDeleteMarkerValue" : "true" }  
}

Contoh: Sumber data dengan properti yang diperlukan saja

Properti opsional yang terkait dengan deteksi perubahan dan penghapusan dapat dihilangkan jika Anda hanya berniat menggunakan sumber data untuk salinan data satu kali:

{   
    "name" : "asqldatasource",  
    "description" : "anything you want, or nothing at all",  
    "type" : "azuresql",  
    "credentials" : { "connectionString" : "Server=tcp:....database.windows.net,1433;Database=...;User ID=...;Password=...;Trusted_Connection=False;Encrypt=True;Connection Timeout=30;" },  
    "container" : { "name" : "sometable" }  
}

Contoh: Menghilangkan kredensial

Jika Anda ingin memperbarui sumber data, kredensial tidak diperlukan. <unchanged> Nilai atau <redacted> dapat digunakan sebagai pengganti string koneksi.

{
    "name" : "adatasource",
    "description": "a description",
    "type": "azuresql",
    "credentials": { "connectionString": "<unchanged>" },
    "container" : { "name": "sometable" }
}

Contoh: Kunci enkripsi

Kunci enkripsi adalah kunci yang dikelola pelanggan yang digunakan untuk enkripsi tambahan. Untuk informasi selengkapnya, lihat Enkripsi menggunakan kunci yang dikelola pelanggan di Azure Key Vault.

{
    "name" : "adatasource",
    "description": "a description",
    "type": "azuresql",
    "credentials": { "connectionString": "<unchanged>" },
    "container" : { "name": "sometable" }
    "encryptionKey": (optional) { 
      "keyVaultKeyName": "Name of the Azure Key Vault key used for encryption",
      "keyVaultKeyVersion": "Version of the Azure Key Vault key",
      "keyVaultUri": "URI of Azure Key Vault, also referred to as DNS name, that provides the key. An example URI might be https://my-keyvault-name.vault.azure.net",
      "accessCredentials": (optional, only if not using managed system identity) {
        "applicationId": "Microsoft Entra ID application ID that was granted access permissions to your specified Azure Key Vault",
        "applicationSecret": "Authentication key of the registered application)"}
      }
}