Mengindeks data dari Azure Files (pratinjau)

Pengindeks Azure Files (pratinjau) mengimpor konten dari berbagi file ke dalam indeks Pencarian Azure AI. Input ke pengindeks adalah file Anda dalam satu folder bersama. Output adalah indeks pencarian dengan konten dan metadata yang dapat dicari yang disimpan di bidang individual.

Untuk mengonfigurasi dan menjalankan pengindeks, Anda dapat menggunakan:

• REST API pratinjau Layanan Pencarian, versi pratinjau apa pun.
• Paket Azure SDK, versi apa pun.
• Panduan impor data di portal Azure.

Prasyarat

• Azure Files, Tingkat Optimalisasi Transaksi.

• Berbagi file SMB yang menyediakan konten sumber. Bagian NFS tidak didukung.

• File yang berisi teks. Jika Anda memiliki data biner, Anda dapat menyertakan pengayaan AI untuk analisis gambar.

• File sumber yang diproses oleh pengindeks Azure Files menggunakan batas ukuran file sumber bersama dan batas karakter hasil ekstraksi untuk pengindeks mirip blob.

• Izin membaca untuk Azure Storage. Connection string dengan "akses penuh" menyertakan kunci yang memungkinkan akses ke konten.

• Gunakan klien REST untuk merumuskan panggilan REST yang mirip dengan yang diperlihatkan dalam artikel ini.

Tugas yang didukung

Anda dapat menggunakan pengindeks ini untuk tugas-tugas berikut:

• Pengindeksan data dan pengindeksan inkremental: Pengindeks dapat mengindeks file dan metadata terkait dari tabel. Ini mendeteksi file dan metadata baru dan diperbarui melalui deteksi perubahan bawaan. Anda dapat mengonfigurasi refresh data sesuai jadwal atau sesuai permintaan.
• Deteksi penghapusan: Pengindeks dapat mendeteksi penghapusan melalui metadata kustom.
• AI Terapan melalui keterampilan:Keterampilan didukung sepenuhnya oleh mesin pengindeksan. Ini termasuk fitur utama seperti vektorisasi terintegrasi yang menambahkan langkah-langkah pemotongan dan penyematan data.
• Mode penguraian: Pengindeks mendukung mode penguraian JSON jika Anda ingin mengurai array atau baris JSON ke dalam dokumen pencarian individual. Ini juga mendukung mode penguraian Markdown.
• Kompatibilitas dengan fitur lain: Pengindeks dirancang untuk bekerja dengan mulus dengan fitur pengindeks lainnya, seperti sesi debug, cache pengindeks untuk pengayaan bertahap, dan penyimpanan pengetahuan.

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 bagian Mengindeks blob JSON)
• KML (XML untuk representasi geografis)
• Markdown
• 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

Bagaimana 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 yang disematkan yang berisi lampiran, atau . File MSG dengan lampiran) juga diindeks sebagai satu dokumen. Misalnya, semua gambar yang diekstrak dari lampiran . File MSG akan dikembalikan di bidang 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.

Anda dapat menggunakan 2020-06-30-preview atau versi yang lebih baru untuk "type": "azurefile". Kami merekomendasikan API pratinjau terbaru.

1. Buat sumber data untuk mengatur definisinya, menggunakan API pratinjau untuk "jenis": "azurefile".

   POST /datasources?api-version=2026-08-01-preview
   {
       "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>" }
   }
   

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

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

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

Menambahkan bidang pencarian ke indeks

Dalam indeks search, tambahkan bidang untuk menerima konten dan metadata file Azure Anda.

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

   POST /indexes?api-version=2026-04-01
   {
     "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 }        
     ]
   }
   

2. 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. Pengindeks secara otomatis mengodekan properti metadata kunci, 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 pengunggahan blob Anda menambahkan properti metadata tersebut ke semua blob. Karena kunci adalah properti yang diperlukan, blob apa pun yang kehilangan nilai 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.

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

4. 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 bergaris hubung menjadi nama properti dengan garis bawah. 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) - tipe konten seperti yang ditentukan oleh kode yang Anda gunakan untuk mengunggah file. Misalnya, application/octet-stream.
   • metadata_storage_last_modified (Edm.DateTimeOffset) - tanda waktu terakhir yang dimodifikasi untuk file. Pencarian Azure AI 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 kustom 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.

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

   POST /indexers?api-version=2026-04-01
   {
     "name" : "my-file-indexer",
     "dataSourceName" : "my-file-datasource",
     "targetIndexName" : "my-search-index",
     "parameters": {
        "batchSize": null,
        "maxFailedItems": null,
        "maxFailedItemsPerBatch": null,
        "configuration": {
           "indexedFileNameExtensions" : ".pdf,.docx",
           "excludedFileNameExtensions" : ".png,.jpeg" 
       }
     },
     "schedule" : { },
     "fieldMappings" : [ ]
   }
   

2. Di bagian "konfigurasi" opsional, berikan kriteria penyertaan atau pengecualian apa pun. Jika tidak ditentukan, semua file dalam layanan berbagi file akan diakses.

   Jika parameter indexedFileNameExtensions dan excludedFileNameExtensions ada, Pencarian Azure AI pertama-tama melihat indexedFileNameExtensions, kemudian pada excludedFileNameExtensions. Jika ekstensi file yang sama ada di kedua daftar, ekstensi tersebut akan dikecualikan dari pengindeksan.

3. 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 tidak menggunakan pemetaan bidang karena pengindeks memiliki dukungan terintegrasi untuk memetakan properti "konten" dan metadata ke bidang yang memiliki nama dan tipe yang serupa dalam indeks. Untuk properti metadata, pengindeks akan secara otomatis mengganti tanda hubung - dengan garis bawah dalam indeks pencarian.

4. 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=2026-04-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":"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 berlaku untuk pengindeks yang menarik konten dari Azure Storage:

• Deteksi perubahan dan deteksi penghapusan
• Mengindeks himpunan data besar