Bagikan melalui

Data indeks dari Azure Table Storage

  • Artikel

Dalam artikel ini, pelajari cara mengonfigurasi pengindeks yang mengimpor konten dari Azure Table Storage dan membuatnya dapat dicari di Azure AI Search. Input ke pengindeks adalah entitas Anda, dalam satu tabel. Output adalah indeks pencarian dengan konten dan metadata yang dapat dicari yang disimpan di bidang individual.

Artikel ini melengkapi Buat pengindeks dengan informasi khusus untuk pengindeksan dari Azure Table Storage. Ini menggunakan API portal Azure dan REST untuk menunjukkan alur kerja tiga bagian yang umum untuk semua pengindeks: membuat sumber data, membuat indeks, membuat pengindeks. Ekstraksi data terjadi saat Anda mengirimkan permintaan Buat Pengindeks.

Prasyarat

  • Penyimpanan Tabel Azure

  • Tabel yang berisi teks. Jika Anda memiliki data biner, pertimbangkan pengayaan AI untuk analisis gambar.

  • Izin baca di Azure Storage. String koneksi "akses penuh" menyertakan kunci yang memberikan akses ke konten, tetapi jika Anda menggunakan peran Azure, pastikan identitas terkelola layanan pencarian memiliki izin Pembaca Data Tabel Penyimpanan.

Untuk mengerjakan contoh dalam artikel ini, Anda memerlukan portal Azure atau klien REST. Jika Anda menggunakan portal Azure, pastikan akses ke semua jaringan publik diaktifkan. Pendekatan lain untuk membuat pengindeks Azure Table termasuk Azure SDK.

Coba dengan data sampel

Gunakan instruksi ini untuk membuat tabel di Azure Storage untuk tujuan pengujian.

  1. Masuk ke portal Azure, buka akun penyimpanan Anda, dan buat tabel bernama hotel.

  2. Instal Azure Storage Explorer.

  3. Unduh HotelsData_toAzureSearch.csv dari GitHub. File ini adalah subset dari himpunan data sampel hotel bawaan. Ini menghilangkan koleksi kamar, deskripsi yang diterjemahkan, dan koordinat geografi.

  4. Di Azure Storage Explorer, masuk ke Azure, pilih langganan Anda, lalu pilih akun penyimpanan Anda.

  5. Buka Tabel dan pilih hotel.

  6. Pilih Impor pada bilah perintah, lalu pilih file HotelsData_toAzureSearch.csv .

  7. Terima default. Pilih Impor untuk memuat data.

Anda harus memiliki 50 rekaman hotel dalam tabel dengan partitionKey, rowKey, dan tanda waktu yang dibuat secara otomatis. Sekarang Anda dapat menggunakan konten ini untuk pengindeksan di portal Azure, klien REST, atau Azure SDK.

Bidang Deskripsi menyediakan konten paling verbose. Anda harus menargetkan bidang ini untuk pencarian teks lengkap dan kueri vektor opsional.

Menggunakan portal Azure

Anda bisa menggunakan wizard Impor data atau Wizard impor dan vektorisasi data untuk mengotomatiskan pengindeksan dari tabel atau tampilan database SQL. Konfigurasi sumber data mirip untuk kedua wizard.

  1. Mulai wizard.

  2. Pada Sambungkan ke data Anda, pilih atau verifikasi bahwa jenis sumber data adalah Azure Table Storage atau bidang pemilihan data meminta tabel.

    Nama sumber data mengacu pada objek koneksi sumber data di Azure AI Search. Jika Anda menggunakan wizard vektor, nama sumber data Anda dibuat secara otomatis menggunakan awalan kustom yang ditentukan di akhir alur kerja wizard.

  3. Tentukan akun penyimpanan dan nama tabel. Kueri bersifat opsional. Ini berguna jika Anda memiliki kolom tertentu yang ingin Anda impor.

  4. Tentukan metode autentikasi, baik identitas terkelola atau kunci API bawaan. Jika Anda tidak menentukan koneksi identitas terkelola, portal Azure menggunakan kunci.

    Jika Anda mengonfigurasi Azure AI Search untuk menggunakan identitas terkelola, dan Anda membuat penetapan peran di Azure Storage yang memberikan izin Pembaca dan Akses Data ke identitas, pengindeks Anda dapat tersambung ke penyimpanan tabel menggunakan ID dan peran Microsoft Entra.

  5. Untuk wizard Impor dan vektorisasi data, Anda bisa menentukan opsi untuk deteksi penghapusan,

    Deteksi penghapusan mengharuskan Anda memiliki bidang yang sudah ada sebelumnya dalam tabel yang dapat digunakan sebagai bendera penghapusan sementara. Ini harus berupa bidang Boolean (Anda bisa menamainya IsDeleted). Tentukan true sebagai nilai penghapusan sementara. Dalam indeks pencarian, tambahkan bidang pencarian terkait yang disebut IsDeleted diatur untuk diambil dan dapat difilter .

  6. Lanjutkan dengan langkah-langkah yang tersisa untuk menyelesaikan wizard:

Menggunakan REST API

Bagian ini menunjukkan panggilan REST API yang membuat sumber data, indeks, dan pengindeks.

Menentukan sumber data

Definisi sumber data menentukan data sumber untuk mengindeks, kredensial, dan kebijakan untuk deteksi perubahan. Sumber data adalah sumber daya independen yang dapat digunakan oleh beberapa pengindeks.

  1. Buat atau perbarui sumber data untuk mengatur definisinya:

     POST https://[service name].search.windows.net/datasources?api-version=2024-07-01 
 {
     "name": "my-table-storage-ds",
     "description": null,
     "type": "azuretable",
     "subtype": null,
     "credentials": {
        "connectionString": "DefaultEndpointsProtocol=https;AccountName=<account name>"
     },
     "container": {
        "name": "my-table-in-azure-storage",
        "query": ""
     },
     "dataChangeDetectionPolicy": null,
     "dataDeletionDetectionPolicy": null,
     "encryptionKey": null,
     "identity": null
 }

  2. Atur "jenis" ke "azuretable" (diperlukan).

  3. Atur "kredensial" ke string koneksi Azure Storage. Bagian berikutnya menjelaskan format yang didukung.

  4. Atur "kontainer" ke nama tabel.

  5. Secara opsional, atur "kueri" ke filter di PartitionKey. Mengatur properti ini adalah praktik terbaik yang meningkatkan performa. Jika "kueri" null, pengindeks menjalankan pemindaian tabel penuh, yang dapat mengakibatkan performa yang buruk jika tabel besar.

Definisi sumber data juga dapat menyertakan kebijakan penghapusan sementara, jika Anda ingin pengindeks menghapus dokumen pencarian saat dokumen sumber ditandai untuk dihapus.

Kredensial dan string koneksi yang didukung

Pengindeks dapat tersambung ke tabel menggunakan koneksi berikut.

Akun penyimpanan akses penuh string koneksi
{ "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<your storage account>;AccountKey=<your account key>;" }
Anda bisa mendapatkan string koneksi dari halaman Akun penyimpanan di portal Azure dengan memilih Tombol akses di panel navigasi kiri. Pastikan untuk memilih string koneksi lengkap dan bukan hanya kunci.
Identitas terkelola string koneksi
{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Storage/storageAccounts/<your storage account name>/;" }
String koneksi ini tidak memerlukan kunci akun, tetapi Sebelumnya Anda harus mengonfigurasi layanan pencarian untuk tersambung menggunakan identitas terkelola.
String koneksi tanda tangan akses bersama akun penyimpanan** (SAS)
{ "connectionString" : "BlobEndpoint=https://<your account>.blob.core.windows.net/;SharedAccessSignature=?sv=2016-05-31&sig=<the signature>&spr=https&se=<the validity end time>&srt=co&ss=b&sp=rl;" }
SAS harus memiliki daftar dan izin baca pada tabel dan entitas.
Tanda tangan akses bersama kontainer
{ "connectionString" : "ContainerSharedAccessUri=https://<your storage account>.blob.core.windows.net/<container name>?sv=2016-05-31&sr=c&sig=<the signature>&se=<the validity end time>&sp=rl;" }
SAS harus memiliki izin daftar dan baca pada kontainer. Untuk informasi selengkapnya, lihat Menggunakan Tanda Tangan Akses Bersama.

Catatan

Jika Anda menggunakan kredensial SAS, Anda harus memperbarui kredensial sumber data secara berkala dengan tanda tangan yang diperbarui untuk mencegah kedaluwarsanya. Ketika kredensial SAS kedaluwarsa, pengindeks akan gagal dengan pesan kesalahan yang mirip dengan "Kredensial yang disediakan dalam string koneksi tidak valid atau telah kedaluwarsa".

Partisi untuk peningkatan performa

Secara default, Azure AI Search menggunakan filter kueri internal berikut untuk melacak entitas sumber mana yang telah diperbarui sejak eksekusi terakhir: Timestamp >= HighWaterMarkValue. Karena tabel Azure tidak memiliki indeks sekunder di bidang Timestamp, jenis kueri ini memerlukan pemindaian tabel penuh dan karenanya lambat untuk tabel besar.

Untuk menghindari pemindaian penuh, Anda dapat menggunakan partisi tabel untuk mempersempit cakupan setiap pekerjaan pengindeks.

  • Jika data Anda secara alami dapat dipartisi ke dalam beberapa rentang partisi, buat sumber data dan pengindeks yang sesuai untuk setiap rentang partisi. Setiap pengindeks sekarang hanya harus memproses rentang partisi tertentu, menghasilkan performa kueri yang lebih baik. Jika data yang perlu diindeks memiliki sejumlah kecil partisi tetap, bahkan lebih baik: setiap pengindeks hanya melakukan pemindaian partisi.

    Misalnya, untuk membuat sumber data untuk memproses rentang partisi dengan kunci dari 000 ke 100, gunakan kueri seperti ini: "container" : { "name" : "my-table", "query" : "PartitionKey ge '000' and PartitionKey lt '100' " }

  • Jika data Anda dipartisi berdasarkan waktu (misalnya, jika Anda membuat partisi baru setiap hari atau minggu), pertimbangkan pendekatan berikut:

    • Dalam definisi sumber data, tentukan kueri yang mirip dengan contoh berikut: (PartitionKey ge <TimeStamp>) and (other filters).

    • Pantau kemajuan pengindeks dengan menggunakan Get Indexer Status API, dan perbarui kondisi <TimeStamp> kueri secara berkala berdasarkan nilai tanda air tinggi terbaru yang berhasil.

    • Dengan pendekatan ini, jika Anda perlu memicu reindeks penuh, reset kueri sumber data selain mengatur ulang pengindeks.

Menambahkan bidang pencarian ke indeks

Dalam indeks pencarian, tambahkan bidang untuk menerima konten dan metadata entitas tabel Anda.

  1. Buat atau perbarui indeks untuk menentukan bidang pencarian yang akan menyimpan konten dari entitas:

    POST https://[service name].search.windows.net/indexes?api-version=2024-07-01 
{
  "name" : "my-search-index",
  "fields": [
    { "name": "Key", "type": "Edm.String", "key": true, "searchable": false },
    { "name": "SomeColumnInMyTable", "type": "Edm.String", "searchable": true }
  ]
}

  2. Buat bidang kunci dokumen ("key": true), tetapi izinkan pengindeks mengisinya secara otomatis. Pengindeks tabel mengisi bidang kunci dengan kunci partisi dan baris yang digabungkan dari tabel. Misalnya, jika PartitionKey baris adalah 1 dan RowKey adalah 1_123, maka nilai kuncinya adalah 11_123. Jika kunci partisi null, hanya kunci baris yang digunakan.

    Jika Anda menggunakan wizard Impor data untuk membuat indeks, portal Azure menyimpulkan bidang "Kunci" untuk indeks pencarian dan menggunakan pemetaan bidang implisit untuk menyambungkan bidang sumber dan tujuan. Anda tidak perlu menambahkan bidang sendiri, dan Anda tidak perlu menyiapkan pemetaan bidang.

    Jika Anda menggunakan REST API dan ingin pemetaan bidang implisit, buat dan beri nama bidang kunci dokumen "Kunci" dalam definisi indeks pencarian seperti yang ditunjukkan pada langkah sebelumnya ({ "name": "Key", "type": "Edm.String", "key": true, "searchable": false }). Pengindeks mengisi bidang Kunci secara otomatis, tanpa pemetaan bidang yang diperlukan.

    Jika Anda tidak ingin bidang bernama "Kunci" di indeks pencarian Anda, tambahkan pemetaan bidang eksplisit dalam definisi pengindeks dengan nama bidang yang Anda inginkan, atur bidang sumber ke "Kunci":

     "fieldMappings" : [
   {
     "sourceFieldName" : "Key",
     "targetFieldName" : "MyDocumentKeyFieldName"
   }
]

  3. Sekarang tambahkan bidang entitas lain yang Anda inginkan dalam indeks Anda. Misalnya, jika entitas terlihat seperti contoh berikut, indeks pencarian Anda harus memiliki bidang untuk HotelName, Deskripsi, dan Kategori untuk menerima nilai tersebut.

    Cuplikan layar konten tabel di browser Penyimpanan.

    Menggunakan nama yang sama dan jenis data yang kompatibel meminimalkan kebutuhan akan pemetaan bidang. Ketika nama dan jenis sama, pengindeks dapat menentukan jalur data secara otomatis.

Mengonfigurasi dan menjalankan pengindeks tabel

Setelah Anda memiliki indeks dan sumber data, Anda siap untuk membuat pengindeks. Konfigurasi pengindeks menentukan input, parameter, dan properti yang mengontrol perilaku run time.

  1. Buat atau perbarui pengindeks dengan memberinya nama dan mereferensikan sumber data dan indeks target:

    POST https://[service name].search.windows.net/indexers?api-version=2024-07-01
{
    "name" : "my-table-indexer",
    "dataSourceName" : "my-table-storage-ds",
    "targetIndexName" : "my-search-index",
    "disabled": null,
    "schedule": null,
    "parameters" : {
        "batchSize" : null,
        "maxFailedItems" : null,
        "maxFailedItemsPerBatch" : null,
        "configuration" : { }
    },
    "fieldMappings" : [ ],
    "cache": null,
    "encryptionKey": null
}

  2. Tentukan pemetaan bidang jika ada perbedaan dalam nama atau jenis bidang, atau jika Anda memerlukan beberapa versi bidang sumber dalam indeks pencarian. Bidang Target adalah nama bidang dalam indeks pencarian.

     "fieldMappings" : [
   {
     "sourceFieldName" : "Description",
     "targetFieldName" : "HotelDescription"
   }
]

  3. Lihat Membuat pengindeks untuk informasi selengkapnya tentang properti lain.

Pengindeks berjalan secara otomatis saat dibuat. Anda dapat mencegahnya dengan mengatur "dinonaktifkan" ke true. Untuk mengontrol eksekusi pengindeks, jalankan pengindeks sesuai permintaan atau letakkan sesuai jadwal.

Periksa status pengindeks

Untuk memantau status pengindeks dan riwayat eksekusi, periksa riwayat eksekusi pengindeks di portal Azure, atau kirim Get Indexer Status REST APIrequest

  1. Pada halaman layanan pencarian, buka Pengindeks manajemen>pencarian.

  2. Pilih pengindeks untuk mengakses konfigurasi dan riwayat eksekusi.

  3. Pilih pekerjaan pengindeks tertentu untuk melihat detail, peringatan, dan kesalahan.

Riwayat eksekusi berisi hingga 50 eksekusi yang terakhir selesai, yang diurutkan dalam urutan kronologis terbalik sehingga eksekusi terbaru menjadi yang pertama.

Langkah berikutnya

Pelajari selengkapnya tentang cara menjalankan pengindeks, memantau status, atau menjadwalkan eksekusi pengindeks. Artikel berikut ini berlaku untuk pengindeks yang menarik konten dari Azure Storage: