Buat Sumber Data (Azure Cognitive Search REST API)

Di Azure Cognitive Search, sumber data digunakan dengan pengindeks, menyediakan informasi koneksi untuk ad hoc 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. Setelah memulai nama dengan huruf atau angka, sisa nama dapat menyertakan huruf, angka, dan tanda hubung apa pun, selama tanda hubung tidak berturut-turut.
versi-api Wajib diisi. Versi stabil saat ini adalah api-version=2020-06-30. Lihat versi API untuk versi lainnya.

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 Wajib diisi. api-key digunakan untuk mengautentikasi permintaan ke layanan Pencarian Anda. Ini adalah nilai string, unik untuk layanan Anda. Membuat permintaan harus menyertakan header yang api-key diatur ke kunci admin Anda (dibandingkan dengan kunci kueri). Anda dapat menemukan kunci API di dasbor layanan pencarian di portal Azure.

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
cosmosdb api SQL
azureblob Azure Cosmos DB untuk Azure Blob Storage
adlsgen2 untuk Azure Data Lake Storage Gen2
azuretable untuk Azure Storage tabel
informasi masuk Wajib diisi. Ini berisi connectionString properti yang menentukan string koneksi untuk sumber data. Format string koneksi tergantung pada jenis sumber data:

Untuk Azure SQL Database, ini adalah SQL Server string koneksi 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 Cognitive 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 API SQL.
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 Azure Cognitive Search.
Untuk Azure Blob Storage, memungkinkan Anda menentukan folder virtual dalam kontainer blob. Misalnya, untuk jalur mycontainer/documents/blob.pdfblob , 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 Opsional. 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 untuk mengatur dataChangeDetectionPolicy untuk penyimpanan blob atau tabel.

SQL Kebijakan Deteksi Perubahan Terintegrasi 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 Koneksi ke dan mengindeks konten Azure SQL.
dataDeletionDetectionPolicy Opsional. 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 Opsional. 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 yang accessCredentials disertakan applicationId (Azure Active Directory ID Aplikasi yang diberikan izin akses ke Key Vault Azure tertentu), dan applicationSecret (kunci autentikasi aplikasi Azure AD yang ditentukan). 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 (SQL Kebijakan Pelacakan Perubahan Terintegrasi)

{   
    "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 berniat 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": "Azure Active Directory Application ID that was granted access permissions to your specified Azure Key Vault",
        "applicationSecret": "Authentication key of the specified Azure AD application)"}
      }
}

Lihat juga