Data indeks dari Azure Table Storage

Artikel
02/22/2024

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 REST API 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 Data dan Pembaca.
Gunakan klien REST untuk merumuskan panggilan REST yang mirip dengan yang diperlihatkan dalam artikel ini.

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.

Buat atau perbarui sumber data untuk mengatur definisinya:

 POST https://[service name].search.windows.net/datasources?api-version=2023-11-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
 }

Atur "jenis" ke "azuretable" (diperlukan).
Atur "kredensial" ke string koneksi Azure Storage. Bagian berikutnya menjelaskan format yang didukung.
Atur "kontainer" ke nama tabel.
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.

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

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

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 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"
   }
]
```
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.

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.

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

POST https://[service name].search.windows.net/indexers?api-version=2023-11-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,
        "base64EncodeKeys" : null,
        "configuration" : { }
    },
    "fieldMappings" : [ ],
    "cache": null,
    "encryptionKey": null
}

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"
   }
]
```
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, kirim permintaan Dapatkan Status Pengindeks:

GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2023-11-01
  Content-Type: application/json  
  api-key: [admin key]

Respons mencakup status dan jumlah item yang diproses. Ini akan terlihat mirip dengan contoh berikut:

    {
        "status":"running",
        "lastResult": {
            "status":"success",
            "errorMessage":null,
            "startTime":"2023-02-21T00:23:24.957Z",
            "endTime":"2023-02-21T00:36:47.752Z",
            "errors":[],
            "itemsProcessed":1599501,
            "itemsFailed":0,
            "initialTrackingState":null,
            "finalTrackingState":null
        },
        "executionHistory":
        [
            {
                "status":"success",
                "errorMessage":null,
                "startTime":"2023-02-21T00:23:24.957Z",
                "endTime":"2023-02-21T00:36:47.752Z",
                "errors":[],
                "itemsProcessed":1599501,
                "itemsFailed":0,
                "initialTrackingState":null,
                "finalTrackingState":null
            },
            ... earlier history items
        ]
    }

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: