Data indeks dari Azure Blob Storage

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

Pengindeks blob sering digunakan untuk pengayaan AI dan pemrosesan berbasis teks. Artikel ini berfokus pada pengindeks untuk pengindeksan berbasis teks, di mana hanya konten tekstual dan metadata yang diserap untuk skenario pencarian teks lengkap.

Prasyarat

  • Azure Blob Storage, Performa Standar (tujuan umum v2).

  • Tingkat akses untuk Blob Storage termasuk Hot, Cool, dan Archive. Hanya Panas dan Dingin yang dapat diakses oleh pengindeks pencarian.

  • Blob yang menyediakan konten teks dan metadata. Jika blob berisi konten biner atau teks yang tidak terstruktur, pertimbangkan untuk menambahkan pengayaan AI untuk pemrosesan gambar dan bahasa alami. Konten blob tidak boleh melebihi batas pengindeks untuk tingkat layanan pencarian Anda.

  • Konfigurasi jaringan dan akses data yang didukung. Minimal, Anda memerlukan izin baca di Azure Storage. String koneksi penyimpanan yang menyertakan kunci akses memberi Anda akses baca ke konten penyimpanan. Jika Anda menggunakan login dan peran Microsoft Entra, pastikan identitas terkelola layanan pencarian memiliki izin Pembaca Data Blob Penyimpanan.

    Secara default, pencarian dan penyimpanan menerima permintaan dari alamat IP publik. Jika keamanan jaringan bukan masalah langsung, Anda dapat mengindeks data blob hanya menggunakan izin string koneksi dan baca. Saat Anda siap untuk menambahkan perlindungan jaringan, lihat Akses pengindeks ke konten yang dilindungi oleh fitur keamanan jaringan Azure untuk panduan tentang akses data.

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

Format dokumen yang didukung

Pengindeks blob 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

Menentukan blob mana yang akan diindeks

Sebelum Anda menyiapkan pengindeksan, tinjau data sumber Anda untuk menentukan apakah ada perubahan yang harus dibuat di muka. Pengindeks dapat mengindeks konten dari satu kontainer pada satu waktu. Secara default, semua blob dalam kontainer diproses. Anda memiliki beberapa opsi untuk pemrosesan yang lebih selektif:

  • Tempatkan blob di folder virtual. Definisi sumber data pengindeks menyertakan parameter "kueri" yang dapat mengambil folder virtual. Jika Anda menentukan folder virtual, hanya blob di folder yang diindeks.

  • Sertakan atau kecualikan blob berdasarkan jenis file. Daftar format dokumen yang didukung dapat membantu Anda menentukan blob mana yang akan dikecualikan. Misalnya, Anda mungkin ingin mengecualikan file gambar atau audio yang tidak menyediakan teks yang dapat dicari. Kemampuan ini dikontrol melalui pengaturan konfigurasi di pengindeks.

  • Sertakan atau kecualikan blob arbitrer. Jika Anda ingin melewati blob tertentu karena alasan apa pun, Anda dapat menambahkan properti metadata dan nilai berikut ke blob di Blob Storage. Ketika pengindeks menemukan properti ini, pengindeks melompati blob atau kontennya dalam pengindeksan yang dijalankan.

    Nama properti Nilai properti Penjelasan
    "AzureSearch_Skip" "true" Menginstruksikan pengindeks blob untuk melewati blob sepenuhnya. Metadata maupun ekstraksi konten tidak dicoba. Ini berguna saat blob tertentu gagal berulang kali dan mengganggu proses pengindeksan.
    "AzureSearch_SkipContent" "true" Melompati konten dan mengekstrak hanya metadata. ini setara dengan pengaturan yang "dataToExtract" : "allMetadata" dijelaskan dalam pengaturan konfigurasi, hanya dilingkupkan ke blob tertentu.

Jika Anda tidak menyiapkan kriteria penyertaan atau pengecualian, pengindeks melaporkan blob yang tidak memenuhi syarat sebagai kesalahan dan melanjutkan. Jika terjadi kesalahan yang cukup, pemrosesan mungkin berhenti. Anda dapat menentukan toleransi kesalahan dalam pengaturan konfigurasi pengindeks.

Pengindeks biasanya membuat satu dokumen pencarian per blob, di mana konten teks dan metadata diambil sebagai bidang yang dapat dicari dalam indeks. Jika blob adalah seluruh file, Anda berpotensi dapat mengurainya ke dalam beberapa dokumen pencarian. Misalnya, Anda dapat mengurai baris dalam file CSV untuk membuat satu dokumen pencarian per baris.

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.

Mengindeks metadata blob

Metadata blob juga dapat diindeks, dan itu berguna jika Anda merasa salah satu properti metadata standar atau kustom berguna dalam filter dan kueri.

Properti metadata yang ditentukan pengguna diekstrak verbatim. Untuk menerima nilai, Anda harus menentukan bidang dalam indeks pencarian jenis Edm.String, dengan nama yang sama dengan kunci metadata blob. Misalnya, jika blob memiliki kunci metadataSensitivity dengan nilai High, Anda harus menentukan bidang bernama Sensitivity dalam indeks pencarian Anda dan itu akan diisi dengan nilai High.

Properti metadata blob standar dapat diekstrak ke dalam bidang bernama dan ditik yang sama, seperti yang tercantum di bawah ini. Pengindeks blob secara otomatis membuat pemetaan bidang internal untuk properti metadata blob ini, mengonversi nama hiphenated asli ("metadata-storage-name") menjadi nama yang setara dengan garis bawah ("metadata_storage_name").

Anda masih harus menambahkan bidang garis bawah ke definisi indeks, tetapi Anda dapat menghilangkan pemetaan bidang karena pengindeks membuat asosiasi secara otomatis.

  • metadata_storage_name (Edm.String) - nama file blob. Misalnya, jika Anda memiliki blob /my-container/my-folder/subfolder/resume.pdf, nilai bidang ini adalah resume.pdf.

  • metadata_storage_path (Edm.String) - URI penuh blob, termasuk akun penyimpanan. Misalnya: https://myaccount.blob.core.windows.net/my-container/my-folder/subfolder/resume.pdf

  • metadata_storage_content_type (Edm.String) - jenis konten seperti yang ditentukan oleh kode yang Anda gunakan untuk mengunggah blob. Contohnya,application/octet-stream.

  • metadata_storage_last_modified (Edm.DateTimeOffset) - tanda waktu terakhir yang dimodifikasi untuk blob. Azure AI Search menggunakan tanda waktu ini untuk mengidentifikasi blob yang diubah, untuk menghindari pengindeksan ulang semuanya setelah pengindeksan awal.

  • metadata_storage_size (Edm.Int64) - ukuran blob dalam byte.

  • metadata_storage_content_md5 ( Edm.String) - MD5 hash dari konten blob, jika tersedia.

  • metadata_storage_sas_token (Edm.String) - Token SAS sementara yang dapat digunakan oleh keterampilan khusus untuk mendapatkan akses ke blob. Token ini tidak boleh disimpan untuk digunakan nanti karena mungkin kedaluwarsa.

Terakhir, properti metadata apa pun khusus untuk format dokumen blob yang Anda indeks juga dapat diwakili dalam skema indeks. Untuk informasi selengkapnya tentang metadata khusus konten, lihat Properti metadata konten.

Penting untuk menunjukkan bahwa Anda tidak perlu menentukan bidang untuk semua properti di atas dalam indeks pencarian Anda - cukup tangkap properti yang Anda butuhkan untuk aplikasi Anda.

Saat ini, pengindeksan tag indeks blob tidak didukung oleh pengindeks ini.

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.

  1. Buat atau perbarui sumber data untuk mengatur definisinya:

    {
        "name" : "my-blob-datasource",
        "type" : "azureblob",
        "credentials" : { "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<account name>;AccountKey=<account key>;" },
        "container" : { "name" : "my-container", "query" : "<optional-virtual-directory-name>" }
    }
    
  2. Atur "jenis" ke "azureblob" (diperlukan).

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

  4. Atur "kontainer" ke kontainer blob, 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 kontainer blob 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 izin daftar dan baca pada kontainer dan objek (blob dalam kasus ini).
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 kedaluwarsa. Jika kredensial SAS kedaluwarsa, pengindeks akan gagal dengan pesan kesalahan yang mirip dengan "Kredensial yang disediakan dalam string koneksi tidak valid atau telah kedaluwarsa".

Menambahkan bidang pencarian ke indeks

Dalam indeks pencarian, tambahkan bidang untuk menerima konten dan metadata blob Azure Anda.

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

    POST https://[service name].search.windows.net/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_size", "type": "Edm.Int64", "searchable": false, "filterable": true, "sortable": true  },
            { "name": "metadata_storage_content_type", "type": "Edm.String", "searchable": false, "filterable": true, "sortable": true },        
        ]
    }
    
  2. Buat bidang kunci dokumen ("key": true). Untuk konten blob, kandidat terbaik adalah properti metadata.

    • metadata_storage_path (default) jalur lengkap ke objek atau file. Bidang kunci ("ID" dalam contoh ini) akan diisi dengan nilai dari metadata_storage_path karena ini adalah default.

    • metadata_storage_name, hanya dapat digunakan jika nama unik. Jika Anda ingin bidang ini sebagai kunci, pindahkan "key": true ke definisi bidang ini.

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

    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.

  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. Pengindeks dapat membaca properti metadata kustom, properti metadata standar, dan properti metadata khusus konten.

Mengonfigurasi dan menjalankan pengindeks blob

Setelah indeks dan sumber data dibuat, Anda siap untuk membuat pengindeks. Konfigurasi pengindeks menentukan input, parameter, dan properti yang mengontrol perilaku run time. Anda juga dapat menentukan bagian mana dari blob yang akan diindeks.

  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=2020-06-30
    {
      "name" : "my-blob-indexer",
      "dataSourceName" : "my-blob-datasource",
      "targetIndexName" : "my-search-index",
      "parameters": {
          "batchSize": null,
          "maxFailedItems": null,
          "maxFailedItemsPerBatch": null,
          "base64EncodeKeys": null,
          "configuration": {
              "indexedFileNameExtensions" : ".pdf,.docx",
              "excludedFileNameExtensions" : ".png,.jpeg",
              "dataToExtract": "contentAndMetadata",
              "parsingMode": "default"
          }
      },
      "schedule" : { },
      "fieldMappings" : [ ]
    }
    
  2. Atur batchSize jika default (10 dokumen) kurang digunakan atau sumber daya yang tersedia luar biasa. Ukuran batch default berukuran spesifik sumber data. Pengindeksan blob menetapkan ukuran batch pada 10 dokumen sebagai pengenalan ukuran dokumen rata-rata yang lebih besar.

  3. Di bagian "konfigurasi", kontrol blob mana yang diindeks berdasarkan jenis file, atau biarkan tidak ditentukan untuk mengambil semua blob.

    Untuk "indexedFileNameExtensions", berikan daftar ekstensi file yang dipisahkan koma (dengan titik terdepan). Lakukan hal yang sama untuk "excludedFileNameExtensions" menunjukkan ekstensi mana yang harus dilewati. Jika ekstensi yang sama ada di kedua daftar, ekstensi tersebut akan dikecualikan dari pengindeksan.

  4. Di bagian "konfigurasi", atur "dataToExtract" untuk mengontrol bagian blob mana yang diindeks:

    • "contentAndMetadata" menentukan bahwa semua metadata dan konten tekstual yang diekstrak dari blob diindeks. Ini adalah nilai default.

    • "storageMetadata" menentukan bahwa hanya properti blob standar dan metadata yang ditentukan pengguna yang diindeks.

    • "allMetadata" menentukan bahwa properti blob standar dan metadata apa pun untuk jenis konten yang ditemukan diekstrak dari konten blob dan diindeks.

  5. Di bagian "konfigurasi", atur "parsingMode". Mode penguraian default adalah satu dokumen pencarian per blob. Jika blob adalah teks biasa, Anda bisa mendapatkan performa yang lebih baik dengan beralih ke penguraian teks biasa. Jika Anda memerlukan penguraian yang lebih terperinci yang memetakan blob ke beberapa dokumen pencarian, tentukan mode yang berbeda. Penguraian satu ke banyak didukung untuk blob yang terdiri dari:

  6. Tentukan pemetaan bidang jika ada perbedaan dalam nama atau jenis bidang, atau jika Anda memerlukan beberapa versi bidang sumber dalam indeks pencarian.

    Dalam pengindeksan blob, 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.

  7. Lihat Membuat pengindeks untuk informasi selengkapnya tentang properti lain. Untuk daftar lengkap deskripsi parameter, lihat Parameter konfigurasi blob di REST API.

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.

Menangani kesalahan

Kesalahan yang umumnya terjadi selama pengindeksan termasuk jenis konten yang tidak didukung, konten yang hilang, atau blob yang terlalu besar.

Secara default, pengindeks blob berhenti segera setelah menemukan blob dengan jenis konten yang tidak didukung (misalnya, file audio). Anda dapat menggunakan parameter "excludedFileNameExtensions" untuk melewati jenis konten tertentu. Namun, Anda mungkin ingin mengindeks untuk melanjutkan meskipun terjadi kesalahan, lalu men-debug dokumen individual nanti. Untuk informasi selengkapnya tentang kesalahan pengindeks, lihat Panduan pemecahan masalah pengindeks dan Kesalahan dan peringatan pengindeks.

Ada lima properti pengindeks yang mengontrol respons pengindeks saat kesalahan terjadi.

PUT /indexers/[indexer name]?api-version=2020-06-30
{
  "parameters" : { 
    "maxFailedItems" : 10, 
    "maxFailedItemsPerBatch" : 10,
    "configuration" : { 
        "failOnUnsupportedContentType" : false, 
        "failOnUnprocessableDocument" : false,
        "indexStorageMetadataOnlyForOversizedDocuments": false
      }
    }
}
Parameter Nilai yang valid Deskripsi
"maxFailedItems" -1, null atau 0, bilangan bulat positif Lanjutkan pengindeksan jika terjadi kesalahan pada titik pemrosesan apa pun, baik saat mengurai blob atau saat menambahkan dokumen ke indeks. Atur properti ini ke jumlah kegagalan yang dapat diterima. Nilai -1 memungkinkan pemrosesan tidak peduli berapa banyak kesalahan yang terjadi. Jika tidak, nilainya adalah bilangan bulat positif.
"maxFailedItemsPerBatch" -1, null atau 0, bilangan bulat positif Sama seperti di atas, tetapi digunakan untuk pengindeksan batch.
"failOnUnsupportedContentType" BENAR atau SALAH Jika pengindeks tidak dapat menentukan tipe konten, tentukan apakah akan melanjutkan atau gagal pekerjaan.
"failOnUnprocessableDocument" BENAR atau SALAH Jika pengindeks tidak dapat memproses dokumen dari jenis konten yang didukung, tentukan apakah akan melanjutkan atau gagal pekerjaan.
"indexStorageMetadataOnlyForOversizedDocuments" BENAR atau SALAH Blob yang terlalu besar diperlakukan sebagai kesalahan secara default. Jika Anda mengatur parameter ini ke true, pengindeks akan mencoba mengindeks metadatanya meskipun konten tidak dapat diindeks. Untuk batasan ukuran blob, lihat Batas layanan.

Lihat juga