Data indeks dari Azure Files

Artikel
12/13/2023

Penting

Pengindeks Azure Files saat ini dalam pratinjau publik di bawah Ketentuan Penggunaan Tambahan. Gunakan PRATINJAU REST API (pratinjau 2020-06-30 atau yang lebih baru) untuk membuat sumber data pengindeks.

Dalam artikel ini, pelajari cara mengonfigurasi pengindeks yang mengimpor konten dari Azure Files dan membuatnya dapat dicari di Azure AI Search. Input ke pengindeks adalah file Anda dalam satu berbagi. 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 mengindeks file di Azure 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

Azure Files, tingkat Transaksi yang Dioptimalkan.
Berbagi file SMB yang menyediakan konten sumber. Berbagi NFS tidak didukung.
File yang berisi teks. Jika Anda memiliki data biner, Anda dapat menyertakan pengayaan AI untuk analisis gambar.
Izin baca di Azure Storage. String koneksi "akses penuh" menyertakan kunci yang memberikan akses ke konten.
Gunakan klien REST untuk merumuskan panggilan REST yang mirip dengan yang diperlihatkan dalam artikel ini.

Format dokumen yang didukung

Pengindeks Azure Files dapat mengekstrak teks dari format dokumen berikut:

CSV (lihat Mengindeks blob CSV)
EML
EPUB
GZ
HTML
JSON (lihat Mengindeks blob JSON)
KML (XML untuk representasi geografis)
Format Microsoft Office: DOCX/DOC/DOCM, XLSX/XLS/XLSM, PPTX/PPT/PPTM, MSG (email Outlook), XML (XML WORD 2003 dan 2006)
Format Dokumen Terbuka: ODT, ODS, ODP
PDF
File teks biasa (lihat juga Mengindeks teks biasa)
RTF
XML
ZIP

Cara Azure Files diindeks

Secara default, sebagian besar file diindeks sebagai dokumen pencarian tunggal dalam indeks, termasuk file dengan konten terstruktur, seperti JSON atau CSV, yang diindeks sebagai satu gugus teks.

Dokumen gabungan atau tersemat (seperti arsip ZIP, dokumen Word dengan email Outlook tersemat yang berisi lampiran, atau . File MSG dengan lampiran) juga diindeks sebagai satu dokumen. Misalnya, semua gambar yang diekstrak dari lampiran file an .MSG akan dikembalikan di kolom normalized_images. Jika Anda memiliki gambar, pertimbangkan untuk menambahkan pengayaan AI untuk mendapatkan lebih banyak utilitas pencarian dari konten tersebut.

Konten tekstual dokumen diekstrak ke dalam bidang string bernama "konten". Anda juga dapat mengekstrak metadata standar dan yang ditentukan pengguna.

Menentukan sumber data

Definisi sumber data menentukan data untuk mengindeks, kredensial, dan kebijakan untuk mengidentifikasi perubahan dalam data. Sumber data didefinisikan sebagai sumber daya independen sehingga dapat digunakan oleh beberapa pengindeks.

Buat atau perbarui sumber data untuk mengatur definisinya, menggunakan API pratinjau versi 2020-06-30-Preview atau yang lebih baru untuk "type": "azurefile".

{
    "name" : "my-file-datasource",
    "type" : "azurefile",
    "credentials" : { "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<account name>;AccountKey=<account key>;" },
    "container" : { "name" : "my-file-share", "query" : "<optional-directory-name>" }
}

Atur "jenis" ke "azurefile" (diperlukan).
Atur "kredensial" ke string koneksi Azure Storage. Bagian berikutnya menjelaskan format yang didukung.
Atur "kontainer" ke berbagi file akar, dan gunakan "kueri" untuk menentukan subfolder apa pun.

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 berbagi file 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.

Menambahkan bidang pencarian ke indeks

Di indeks pencarian, tambahkan bidang untuk menerima konten dan metadata file Azure Anda.

Buat atau perbarui indeks untuk menentukan bidang pencarian yang akan menyimpan konten file dan metadata:

POST /indexes?api-version=2020-06-30
{
  "name" : "my-search-index",
  "fields": [
      { "name": "ID", "type": "Edm.String", "key": true, "searchable": false },
      { "name": "content", "type": "Edm.String", "searchable": true, "filterable": false },
      { "name": "metadata_storage_name", "type": "Edm.String", "searchable": false, "filterable": true, "sortable": true  },
      { "name": "metadata_storage_path", "type": "Edm.String", "searchable": false, "filterable": true, "sortable": true },
      { "name": "metadata_storage_size", "type": "Edm.Int64", "searchable": false, "filterable": true, "sortable": true  },
      { "name": "metadata_storage_content_type", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true }        
  ]
}

Buat bidang kunci dokumen ("key": true). Untuk konten blob, kandidat terbaik adalah properti metadata. Properti metadata sering menyertakan karakter, seperti / dan -, yang tidak valid untuk kunci dokumen. Karena pengindeks memiliki properti "base64EncodeKeys" (true secara default), pengindeks secara otomatis mengodekan properti metadata, tanpa memerlukan konfigurasi atau pemetaan bidang.
- metadata_storage_path (default) jalur lengkap ke objek atau file
- metadata_storage_name hanya dapat digunakan jika nama unik
- Properti metadata kustom yang Anda tambahkan ke blob. Opsi ini mengharuskan proses upload blob Anda menambahkan properti metadata ke semua blob. Karena kuncinya adalah properti yang diperlukan, blob apa pun yang hilang nilainya akan gagal diindeks. Jika Anda menggunakan properti metadata kustom sebagai kunci, hindari membuat perubahan pada properti tersebut. Pengindeks akan menambahkan dokumen duplikat untuk blob yang sama jika properti kunci berubah.
Tambahkan bidang "konten" untuk menyimpan teks yang diekstrak dari setiap file melalui properti "konten" blob. Anda tidak diharuskan menggunakan nama ini, tetapi melakukannya memungkinkan Anda memanfaatkan pemetaan bidang implisit.
Tambahkan bidang untuk properti metadata standar. Dalam pengindeksan file, properti metadata standar sama dengan properti metadata blob. Pengindeks Azure Files secara otomatis membuat pemetaan bidang internal untuk properti ini yang mengonversi nama properti terpencil menjadi nama properti yang digaris bawahi. Anda masih harus menambahkan bidang yang ingin Anda gunakan definisi indeksnya, tetapi Anda bisa menghilangkan pembuatan pemetaan bidang di sumber data.
- metadata_storage_name (Edm.String) - nama file. Misalnya, jika Anda memiliki file /my-share/my-folder/subfolder/resume.pdf, nilai bidang ini adalah resume.pdf.
- metadata_storage_path (Edm.String) - URI lengkap file, termasuk akun penyimpanan. Misalnya: https://myaccount.file.core.windows.net/my-share/my-folder/subfolder/resume.pdf
- metadata_storage_content_type (Edm.String) - jenis konten seperti yang ditentukan oleh kode yang Anda gunakan untuk mengunggah file. Contohnya,application/octet-stream.
- metadata_storage_last_modified (Edm.DateTimeOffset) - tanda waktu terakhir yang dimodifikasi untuk file. Azure AI Search menggunakan tanda waktu ini untuk mengidentifikasi file yang diubah, untuk menghindari pengindeksan ulang semuanya setelah pengindeksan awal.
- metadata_storage_size (Edm.Int64) - ukuran file dalam byte.
- metadata_storage_content_md5 ( Edm.String) - hash MD5 dari konten file, jika tersedia.
- metadata_storage_sas_token (Edm.String) - Token SAS sementara yang dapat digunakan oleh keterampilan khusus untuk mendapatkan akses ke file. Token ini tidak boleh disimpan untuk digunakan nanti karena mungkin kedaluwarsa.

Mengonfigurasi dan menjalankan pengindeks Azure Files

Setelah indeks dan sumber data dibuat, 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=2020-06-30
{
  "name" : "my-file-indexer",
  "dataSourceName" : "my-file-datasource",
  "targetIndexName" : "my-search-index",
  "parameters": {
     "batchSize": null,
     "maxFailedItems": null,
     "maxFailedItemsPerBatch": null,
     "base64EncodeKeys": null,
     "configuration": {
        "indexedFileNameExtensions" : ".pdf,.docx",
        "excludedFileNameExtensions" : ".png,.jpeg" 
    }
  },
  "schedule" : { },
  "fieldMappings" : [ ]
}

Di bagian "konfigurasi" opsional, berikan kriteria penyertaan atau pengecualian apa pun. Jika dibiarkan, semua file dalam berbagi file akan diambil.

Jika parameter indexedFileNameExtensions dan excludedFileNameExtensions ada, Azure AI Search terlebih dahulu melihat indexedFileNameExtensions, lalu di excludedFileNameExtensions. Jika ekstensi file yang sama ada di kedua daftar, ekstensi tersebut akan dikecualikan dari pengindeksan.
Tentukan pemetaan bidang jika ada perbedaan dalam nama atau jenis bidang, atau jika Anda memerlukan beberapa versi bidang sumber dalam indeks pencarian.

Dalam pengindeksan file, Anda sering dapat menghilangkan pemetaan bidang karena pengindeks memiliki dukungan bawaan untuk memetakan properti "konten" dan metadata ke bidang bernama dan ditik yang sama dalam indeks. Untuk properti metadata, pengindeks akan secara otomatis mengganti tanda hubung - dengan garis bawah dalam indeks pencarian.
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=2020-06-30
  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":"2022-02-21T00:23:24.957Z",
            "endTime":"2022-02-21T00:36:47.752Z",
            "errors":[],
            "itemsProcessed":1599501,
            "itemsFailed":0,
            "initialTrackingState":null,
            "finalTrackingState":null
        },
        "executionHistory":
        [
            {
                "status":"success",
                "errorMessage":null,
                "startTime":"2022-02-21T00:23:24.957Z",
                "endTime":"2022-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

Anda sekarang dapat menjalankan pengindeks, status pemantauan, atau menjadwalkan eksekusi pengindeks. Artikel berikut ini berlaku untuk pengindeks yang menarik konten dari Azure Storage: