Membuat atau Memperbarui Sumber Data (Pratinjau REST API)

  • Artikel

Berlaku untuk: 2023-07-01-Preview, 2021-04-30-Preview, 2020-06-30-Preview

Penting

Pratinjau 01-07-2023 (tidak ada perubahan).

Pratinjau 30-04-2021 menambahkan dukungan identitas terkelola untuk koneksi pengindeks ke sumber daya Azure lainnya:

  • "kredensial" menerima ID sumber daya Azure sebagai nilai, asalkan layanan pencarian berjalan di bawah identitas terkelola dan penetapan peran Azure memberikan akses baca ke data.
  • "identitas" menerima identitas terkelola yang ditetapkan pengguna. Properti ini adalah tingkat pertama untuk koneksi data. Ini juga berada di bawah "encryptionKey" untuk mengambil kunci yang dikelola pelanggan di Azure Key Vault.
  • Azure Files sedang dalam pratinjau. Gunakan API pratinjau untuk mengindeks dari sumber data ini.

Pratinjau 30-06-2020 menambahkan:

  • "dataDeletionDetectionPolicy" menerima "NativeBlobSoftDeleteDeletionDetectionPolicy" untuk pengindeks blob.
  • dukungan Azure Database for MySQL sedang dalam pratinjau. Gunakan API pratinjau untuk mengindeks dari sumber data ini.
  • Dukungan Cosmos DB MongoDB API dan Gremlin API sedang dalam pratinjau. Gunakan API pratinjau untuk mengindeks dari sumber data ini.

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

Anda dapat menggunakan POST atau PUT pada permintaan buat. Untuk salah satu dari keduanya, 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]

Untuk permintaan pembaruan, gunakan PUT dan tentukan nama pengindeks 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 ditimpa menggunakan definisi baru.

Catatan

Setelah sumber data ada, Anda tidak dapat mengubah properti jenis pada permintaan pembaruan. Sebagai gantinya, Anda harus membuat sumber data baru menggunakan jenis yang Anda inginkan.

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 Anda 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 pratinjau saat ini adalah 2023-07-01-Preview. 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 Opsional jika Anda menggunakan peran Azure dan token pembawa disediakan berdasarkan permintaan, jika tidak, kunci diperlukan. Kunci api adalah string unik yang dihasilkan sistem yang mengautentikasi permintaan ke layanan pencarian Anda. Membuat permintaan harus menyertakan header yang api-key diatur ke kunci admin Anda (dibandingkan dengan kunci kueri). Lihat Menyambungkan ke Azure AI Search 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" : (required) { "name" : "Name of the table, collection, or blob container you wish to index" },  
    "dataChangeDetectionPolicy" : (optional) {See below for details },
    "dataDeletionDetectionPolicy" : (optional) {See below for details },
    "identity": (optional) {Sets the Resource ID of a managed identity. See below for details },
    "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.",
      "identity": "(Resource ID of a user-assigned managed identity, used for connecting to key vault)",
      "accessCredentials": (Credentials for connecting to key vault. Omit if using a managed identity) {
        "applicationId": "Azure AD Application ID that has access permissions to the key vault",
        "applicationSecret": "Authentication key of the specified Azure AD application)"}
      }
}

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 boleh 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:

adlsgen2 untuk Azure Data Lake Storage Gen2
azureblobuntuk Azure Blob Storage
azurefiles untuk Azure File Storage
azuresql for Azure SQL Database
azuretable for Azure Table Storage
cosmosdb untuk Azure Cosmos DB SQL API, MongoDB API, Gremlin API
mysql untuk Azure Database for MySQL
kredensial Wajib diisi. connectionString Berisi properti yang menentukan cara menyambungkan.
kontainer Wajib diisi. Menentukan kontainer, koleksi, tabel, atau tampilan yang berisi data yang akan diindeks.
dataChangeDetectionPolicy Pilihan. Menentukan mekanisme yang disediakan oleh platform data untuk mengidentifikasi item data yang diubah.
dataDeletionDetectionPolicy Opsional. Mengidentifikasi bagaimana platform data menghapus data.
encryptionKey Pilihan. Digunakan untuk enkripsi tambahan kredensial sumber data, melalui kunci enkripsi yang dikelola pelanggan (CMK) di Azure Key Vault. Tersedia untuk layanan pencarian yang dapat ditagih yang dibuat pada atau setelah 2019-01-01.
dinonaktifkan Pilihan. Nilai Boolean menunjukkan apakah pengindeks dibuat dalam status dinonaktifkan, yang mencegahnya segera berjalan. Salah secara default.
identitas Opsional. Ini berisi userAssignedIdentity jenis #Microsoft.Azure.Search.DataUserAssignedIdentity dan menentukan identitas terkelola yang ditetapkan pengguna dari sumber daya eksternal. Properti ini bergantung pada credentials memiliki string koneksi dalam format yang tepat (ID Sumber Daya) untuk koneksi identitas terkelola untuk setiap jenis sumber data.

identity Jika properti null, koneksi ke ID sumber daya dibuat menggunakan properti yang dikelola sistem.

Jika properti ini ditetapkan ke jenis #Microsoft.Azure.Search.DataNoneIdentity, identitas eksplisit apa pun yang sebelumnya ditentukan akan dihapus.

Respons

Untuk permintaan yang berhasil: 201 Dibuat jika sumber data baru dibuat, dan 204 Tidak Ada Konten jika sumber data yang ada diperbarui.

Contoh

Contoh: Peran Azure dan identitas terkelola yang ditetapkan sistem

Jika layanan pencarian Anda memiliki identitas terkelola yang ditetapkan sistem dan penetapan peran, koneksi sumber data dapat menjadi ID sumber daya unik akun penyimpanan Anda.

{
    "name": "azure-blob-ds",
    "description": "a description of the blob data",
    "type": "azureblob",
    "subtype": null,
    "credentials": {
      "connectionString": "ResourceId=/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.Storage/storageAccounts/[storage account name]/;"
    },
    "container": {
      "name": "mycontainer"
    },
    "dataChangeDetectionPolicy": null,
    "dataDeletionDetectionPolicy": null,
  }

Contoh: Peran Azure dan identitas terkelola yang ditetapkan pengguna (pratinjau)

Contoh ini menunjukkan koneksi terautentikasi Azure AD untuk layanan pencarian yang memiliki identitas terkelola yang ditetapkan pengguna.

{
    "name": "azure-blob-ds",
    "description": "a description of the blob data",
    "type": "azureblob",
    "subtype": null,
    "credentials": {
      "connectionString": "ResourceId=/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.Storage/storageAccounts/[storage account name]/;"
    },
    "container": {
      "name": "mycontainer"
    },
    "dataChangeDetectionPolicy": null,
    "dataDeletionDetectionPolicy": null,
    "identity": {
      "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
      "userAssignedIdentity": "/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[user identity name]"
    }
  }

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: Menggunakan opsi kredensial yang tidak berubah atau diredaksi

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

Contoh: Koneksi brankas kunci enkripsi oleh layanan pencarian yang memiliki identitas terkelola yang ditetapkan pengguna

Contoh ini menghilangkan accessCredentials. Untuk sumber daya yang memiliki identitas terkelola yang ditetapkan pengguna yang ditetapkan untuknya, Anda dapat menentukan identitas di encryptionKey dan mengambil kunci menggunakan identitas tersebut dan penetapan peran Azure.

{
    "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",
      "identity": {
        "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
        "userAssignedIdentity": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/contoso-rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/contoso-identity"
        }
    }
}

Definisi

Tautan Deskripsi
kontainer Menentukan kontainer, koleksi, tabel, atau tampilan yang berisi data yang akan diindeks.
kredensial connectionString Berisi properti yang menentukan cara pengindeks tersambung ke sumber daya Azure.
dataChangeDetectionPolicy Menentukan mekanisme yang disediakan oleh platform data untuk mengidentifikasi data yang diubah.
dataDeletionDetectionPolicy Menentukan mekanisme untuk mendeteksi data yang dihapus.
encryptionKey Mengonfigurasi koneksi ke Azure Key Vault untuk enkripsi yang dikelola pelanggan.

kontainer

Menentukan kontainer, koleksi, tabel, atau tampilan yang berisi data yang akan diindeks.

Atribut Deskripsi
nama Wajib diisi. Untuk Azure Cosmos DB, menentukan koleksi SQL API. Untuk Azure Blob Storage, menentukan kontainer penyimpanan. Untuk Azure SQL, menentukan tabel atau tampilan. Anda dapat menggunakan nama yang memenuhi syarat skema, seperti [dbo].[mytable]. Untuk Azure Table Storage, menentukan nama tabel.
query Pilihan. 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.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).

informasi masuk

Berisi properti "connectionString" yang menentukan bagaimana pengindeks tersambung ke sumber daya Azure.

Atribut Deskripsi
connectionString Wajib diisi. Menentukan koneksi ke sumber data pengindeks. Jika Anda memperbarui definisi sumber data, string koneksi tidak diperlukan. <unchanged> Nilai atau <redacted> dapat digunakan sebagai pengganti string koneksi aktual.

Untuk koneksi yang diautentikasi menggunakan kunci atau kredensial masuk, nilai-nilai tersebut terlihat dalam string koneksi. 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.

Jika Anda menggunakan identitas terkelola untuk mengautentikasi, Anda dapat menghilangkan kredensial pada koneksi.

Untuk koneksi yang diautentikasi menggunakan identitas terkelola, string koneksi menentukan ID sumber daya Azure (lihat tautan ini untuk format string koneksi: Azure Storage, Cosmos DB,SQL Database).

Penetapan peran yang dilingkup ke sumber data eksternal menentukan apakah pengindeks dapat tersambung, dan layanan pencarian harus dikonfigurasi untuk dijalankan sebagai layanan tepercaya di Azure Active Directory.

Jika properti "identitas" juga ditentukan, koneksi dibuat menggunakan identitas terkelola yang ditetapkan pengguna layanan pencarian yang disediakan oleh properti "identitas". Jika tidak, jika "identitas" tidak ditentukan atau null, koneksi melalui identitas yang dikelola sistem.

dataChangeDetectionPolicy

Menentukan mekanisme yang disediakan oleh platform data untuk mengidentifikasi data yang diubah. Kebijakan yang didukung bervariasi berdasarkan jenis sumber data.

Atribut Deskripsi
dataChangeDetectionPolicy Pilihan. Kebijakan yang valid meliputi HighWatermarkChangeDetectionPolicy atau SqlIntegratedChangeDetectionPolicy.

HighWatermarkChangeDetectionPolicy 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.

SqlIntegratedChangeDetectionPolicydigunakan 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.
highWaterMarkColumnName Diperlukan untuk HighWatermarkChangeDetectionPolicy. Untuk Cosmos DB, kolom harus berupa _ts properti . Untuk Azure SQL, kolom terindeks rowversion disarankan. Untuk Azure Storage, deteksi perubahan bawaan menggunakan nilai lastModified, menghilangkan kebutuhan apa pun untuk mengatur dataChangeDetectionPolicy.

dataDeletionDetectionPolicy

Menentukan mekanisme yang disediakan oleh platform data untuk mengidentifikasi data yang dihapus. Kebijakan yang didukung bervariasi berdasarkan jenis sumber data.

Atribut Deskripsi
dataDeletionDetectionPolicy Pilihan. Nilai yang valid adalah SoftDeleteColumnDeletionDetectionPolicy atau NativeBlobSoftDeleteDeletionDetectionPolicy (lihat Penghapusan sementara blob asli (pratinjau)).

Saat ini, satu-satunya kebijakan yang tersedia secara umum adalahSoftDeleteColumnDeletionDetectionPolicy, yang mengidentifikasi item yang dihapus berdasarkan nilai kolom atau properti 'penghapusan sementara' di sumber data.

softDeleteColumnName" Wajib diisi. Nama kolom di sumber data Anda yang menyediakan nilai yang menentukan status penghapusan baris. Misalnya, Anda dapat membuat kolom bernama "IsDeleted". Hanya kolom dengan nilai string, bilangan bulat, atau boolean yang didukung.
softDeleteMarkerValue Wajib diisi. Nilai kolom penghapusan sementara. 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. Jika pengindeks membaca nilai ini dari kolom penghapusan sementara, pengindeks akan menghapus dokumen pencarian yang sesuai dari indeks pencarian.

encryptionKey

Mengonfigurasi koneksi ke Azure Key Vault untuk kunci enkripsi (CMK) yang dikelola pelanggan tambahan. Enkripsi dengan kunci yang dikelola pelanggan tidak tersedia untuk layanan gratis. Untuk layanan yang dapat ditagih, layanan ini hanya tersedia untuk layanan pencarian yang dibuat pada atau setelah 2019-01-01.

Koneksi ke brankas kunci harus diautentikasi. Anda dapat menggunakan "accessCredentials" atau identitas terkelola untuk tujuan ini.

Identitas terkelola dapat berupa sistem atau ditetapkan pengguna (pratinjau). Jika layanan pencarian memiliki identitas terkelola yang ditetapkan sistem dan penetapan peran yang memberikan akses baca ke brankas kunci, Anda dapat menghilangkan "identitas" dan "accessCredentials", dan permintaan akan mengautentikasi menggunakan identitas terkelola. Jika layanan pencarian memiliki identitas dan penetapan peran yang ditetapkan pengguna, atur properti "identitas" ke ID sumber daya identitas tersebut.

Atribut Deskripsi
keyVaultKeyName Wajib diisi. Nama kunci Azure Key Vault yang digunakan untuk enkripsi.
keyVaultKeyVersion Wajib diisi. Versi kunci Key Vault Azure.
keyVaultUri Wajib diisi. URI Azure Key Vault (juga disebut sebagai nama DNS) yang menyediakan kunci. Contoh URI adalah https://my-keyvault-name.vault.azure.net.
accessCredentials Hilangkan jika Anda menggunakan identitas terkelola. Jika tidak, properti accessCredentials sertakan applicationId (ID Aplikasi Azure Active Directory yang memiliki izin akses ke azure Key Vault yang ditentukan), dan applicationSecret (kunci autentikasi aplikasi Azure AD yang ditentukan).
identity Opsional kecuali Anda menggunakan identitas terkelola yang ditetapkan pengguna untuk koneksi layanan pencarian ke Azure Key Vault. Formatnya adalah "/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[managed identity name]".

Lihat juga