Data indeks dari Azure Blob Storage

Nota

Pencarian Azure AI tersedia melalui portal Azure, REST API, dan Azure SDK. Ini juga mendukung Foundry IQ, lapisan pengetahuan terkelola yang mengubah konten perusahaan menjadi pangkalan pengetahuan yang dapat digunakan kembali dan sadar izin untuk agen di portal Microsoft Foundry.

Important

Fitur dan fungsionalitas ini mendukung koneksi ke layanan layanan Microsoft dan pihak ketiga lainnya. Penggunaan layanan ini tunduk pada persyaratan masing-masing dan dapat mengakibatkan pemrosesan data atau penyimpanan di luar batas kepatuhan Azure, serta data yang mengalir ke batas kepatuhan Azure.

Anda bertanggung jawab untuk mengelola apakah data Anda akan mengalir di luar batas kepatuhan dan geografis organisasi Anda dan implikasi terkait, dan bahwa izin, batas, dan persetujuan yang sesuai disediakan.

Anda bertanggung jawab untuk meninjau dan menguji aplikasi yang Anda buat dengan cermat dalam konteks kasus penggunaan spesifik Anda dan membuat semua keputusan dan penyesuaian yang sesuai. Ini termasuk menerapkan mitigasi AI Anda sendiri yang bertanggung jawab, seperti metaprompts, filter konten, atau sistem keamanan lainnya, dan memastikan aplikasi Anda memenuhi standar kualitas, keandalan, keamanan, dan kepercayaan yang sesuai. Untuk informasi selengkapnya, lihat Catatan Transparansi Pencarian Azure AI.

Pengindeks blob mengimpor konten dari Azure Blob Storage dan membuatnya dapat dicari di Pencarian Azure AI. Pengindeks menerima blob dalam satu kontainer sebagai input. Output adalah indeks pencarian yang menyimpan konten dan metadata yang dapat dicari di bidang individual.

Artikel ini menggunakan REST API Layanan Pencarian untuk menunjukkan cara mengonfigurasi dan menjalankan pengindeks. Namun, Anda juga dapat menggunakan:

Nota

Pencarian Azure AI dapat menyerap cakupan kontrol akses berbasis peran (RBAC) selama pengindeksan dan mentransfer izin tersebut ke konten terindeks dalam indeks pencarian. Untuk informasi selengkapnya, lihat Menggunakan pengindeks blob atau sumber pengetahuan untuk memasukkan metadata cakupan RBAC (pratinjau).

Prasyarat

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

  • Tingkat akses termasuk panas, sejuk, dingin, dan arsip. Pengindeks dapat mengambil blob pada tingkat akses panas, sejuk, dan dingin.

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

    Batas pengindeks blob mencakup ukuran blob maksimum dan jumlah karakter yang Pencarian Azure AI ekstrak dari blob. Jika Anda menggunakan set keterampilan, setiap input keterampilan atau batas layanan berlaku secara terpisah setelah pemecahan dokumen.

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

Tugas yang didukung

Anda dapat menggunakan pengindeks ini untuk tugas-tugas berikut:

Format dokumen yang didukung

Pengindeks blob dapat mengekstrak teks dari format dokumen berikut:

  • CSV (lihat Mengindeks blob CSV)
  • EML
  • EPUB
  • GZ
  • HTML
  • JSON (lihat Pengindeksan 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

Menentukan blob mana yang akan diindeks

Sebelum menyiapkan pengindeksan, tinjau data sumber Anda untuk menentukan apakah Anda perlu membuat perubahan apa pun. Pengindeks dapat mengindeks konten dari satu kontainer pada satu waktu. Secara default, pengindeks memproses semua blob dalam kontainer. Anda memiliki beberapa opsi untuk pemrosesan yang lebih selektif:

  • Tempatkan blob di folder virtual. Definisi sumber data untuk pengindeksan menyertakan parameter query yang dapat menerima folder virtual. Jika Anda menentukan folder virtual, pengindeks hanya mengindeks blob tersebut di folder .

  • 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. Anda mengontrol kemampuan ini melalui pengaturan konfigurasi di pengindeks.

  • Sertakan atau kecualikan blob arbitrer. Untuk melewati blob tertentu, tambahkan properti metadata dan nilai berikut ke blob di Azure Blob Storage. Ketika pengindeks menemukan properti ini, pengindeks akan melewati blob atau kontennya dalam proses pengindeksan.

    Nama properti Nilai properti Explanation
    AzureSearch_Skip true Menginstruksikan pengindeks blob untuk mengabaikan blob sepenuhnya. Pengindeks tidak mencoba mengekstrak metadata atau konten. Properti ini berguna ketika blob tertentu gagal berulang kali dan mengganggu proses pengindeksan.
    AzureSearch_SkipContent true Pengindeks melompati konten dan hanya mengekstrak metadata. Properti ini setara dengan pengaturan yang "dataToExtract": "allMetadata" dijelaskan dalam pengaturan konfigurasi, tetapi 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 sekumpulan data berupa seluruh file, Anda 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 .MSG dikembalikan di normalized_images field. Jika Anda memiliki gambar, pertimbangkan untuk menambahkan pengayaan AI untuk mendapatkan lebih banyak utilitas pencarian dari konten tersebut.

Pengindeks mengekstrak konten tekstual dokumen ke dalam bidang string bernama content. Anda juga dapat mengekstrak metadata standar dan yang ditentukan pengguna.

Mengindeks metadata blob

Anda dapat mengindeks metadata blob bersama konten. Pengindeks mengekstrak properti metadata dan menyimpannya di bidang indeks, yang berguna untuk membuat filter dan kueri.

Tentukan bidang dalam indeks pencarian Anda untuk properti metadata yang ingin Anda ambil. Anda tidak perlu menentukan setiap properti metadata standar atau kustom yang tersedia. Cukup tangkap properti yang Anda butuhkan untuk aplikasi Anda.

Saat ini, pengindeks ini tidak mendukung pengindeksan tag indeks blob.

Important

Pengindeks hanya mengisi bidang metadata yang sudah ditentukan dalam indeks pencarian Anda. Persyaratan ini berlaku untuk metadata blob standar dan metadata kustom. Jika bidang tidak ditentukan, nilai metadata diekstrak selama pengindeksan tetapi diam-diam dibuang, sehingga tidak muncul di hasil pencarian. Ini adalah sumber bidang metadata null yang paling umum dalam hasil pencarian. Untuk informasi selengkapnya, lihat Bidang metadata null dalam hasil pencarian.

Properti metadata blob standar

Untuk metadata blob standar, tentukan bidang dalam indeks Anda menggunakan nama bergaris bawah yang sama. Untuk contoh definisi bidang langkah demi langkah, lihat Menambahkan bidang pencarian ke indeks.

Untuk konfigurasi pengindeks, termasuk dataToExtract pengaturan yang mengontrol metadata mana yang akan diekstrak, lihat Mengonfigurasi dan menjalankan pengindeks blob.

Pengindeks mengenali dan dapat memetakan properti metadata standar ini jika Anda menentukan bidang yang sesuai dalam indeks Anda:

  • metadata_storage_name (Edm.String) adalah 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) adalah URI lengkap blob, termasuk akun penyimpanan. Contohnya, https://myaccount.blob.core.windows.net/my-container/my-folder/subfolder/resume.pdf. Gunakan properti ini untuk menyertakan URL blob dalam hasil pencarian untuk navigasi atau atribusi sumber.

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

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

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

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

  • metadata_storage_sas_token (Edm.String) adalah token SAS sementara yang dapat digunakan keterampilan kustom untuk mendapatkan akses ke blob. Jangan simpan token ini untuk digunakan nanti, karena mungkin kedaluwarsa.

Metadata kustom dan khusus konten

Untuk metadata blob kustom atau yang ditentukan pengguna, tentukan bidang dengan nama yang sama persis dengan kunci metadata blob. Misalnya, jika blob Anda memiliki kunci Sensitivity metadata dengan nilai High, tentukan bidang bernama Sensitivity jenis Edm.String dalam indeks Anda.

Anda juga dapat mewakili properti metadata khusus untuk format dokumen blob yang Anda indeks. Untuk informasi selengkapnya, lihat Properti metadata konten.

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 type ke azureblob (diperlukan).

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

  4. Atur container ke kontainer blob, dan gunakan query untuk menentukan subfolder apa pun.

Anda juga dapat menyertakan kebijakan penghapusan sementara dalam definisi sumber data 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 dengan menggunakan koneksi berikut.

String koneksi akun penyimpanan dengan akses penuh
{ "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<your storage account>;AccountKey=<your account key>;" }
Anda bisa mendapatkan string koneksi dari halaman Akun penyimpanan di portal Microsoft Azure dengan memilih Kunci akses di panel kiri. Pastikan untuk memilih string koneksi lengkap dan bukan hanya kunci.
String koneksi identitas terkelola
{ "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 (SAS) akun penyimpanan
{ "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 hak akses untuk daftar dan membaca 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 Berikan akses terbatas ke sumber daya Azure Storage menggunakan tanda tangan akses bersama (SAS).

Nota

Jika Anda menggunakan kredensial SAS, Anda perlu memperbarui kredensial sumber data secara berkala dengan tanda tangan yang diperbarui untuk mencegah kedaluwarsanya. Jika kredensial SAS kedaluwarsa, pengindeks 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 menyimpan konten blob dan metadata:

    POST https://[service name].search.windows.net/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_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) adalah jalur lengkap ke objek atau file. Bidang kunci (ID dalam contoh ini) diisi dengan nilai dari metadata_storage_path karena merupakan 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 kunci adalah properti yang diperlukan, blob apa pun yang kehilangan nilai gagal diindeks. Jika Anda menggunakan properti metadata kustom sebagai kunci, hindari membuat perubahan pada properti tersebut. Pengindeks menambahkan dokumen duplikat untuk blob yang sama jika properti kunci berubah.

    Properti metadata sering menyertakan karakter, seperti / dan -, yang tidak valid untuk kunci dokumen. Namun, pengindeks secara otomatis mengodekan properti metadata kunci, tanpa konfigurasi atau pemetaan bidang yang diperlukan.

  3. Tambahkan bidang content untuk menyimpan teks yang diekstraksi dari setiap file melalui properti content blob. Anda tidak diharuskan menggunakan nama ini, tetapi dengan menggunakannya, Anda dapat 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 Anda membuat indeks dan sumber data, buat pengindeks. Konfigurasi pengindeks menentukan input, parameter, dan properti yang mengontrol perilaku runtime. 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=2026-04-01
    {
      "name" : "my-blob-indexer",
      "dataSourceName" : "my-blob-datasource",
      "targetIndexName" : "my-search-index",
      "parameters": {
          "batchSize": null,
          "maxFailedItems": null,
          "maxFailedItemsPerBatch": null,
          "configuration": {
              "indexedFileNameExtensions" : ".pdf,.docx",
              "excludedFileNameExtensions" : ".png,.jpeg",
              "dataToExtract": "contentAndMetadata",
              "parsingMode": "default"
          }
      },
      "schedule" : { },
      "fieldMappings" : [ ]
    }
    
  2. Atur batchSize jika default (10 dokumen) kurang digunakan atau membuat sumber daya yang tersedia kewalahan. Ukuran batch default bersifat spesifik terhadap sumber data. Pengindeksan Blob menetapkan ukuran batch menjadi 10 dokumen dengan mempertimbangkan ukuran dokumen rata-rata yang lebih besar.

  3. Pada bagian configuration, kendalikan blob mana yang diindeks berdasarkan jenis file, atau sisipkan pengaturan tidak ditentukan untuk mengambil semua blob.

    Untuk indexedFileNameExtensions, berikan daftar ekstensi file yang dipisahkan koma (dengan titik terdepan). Lakukan hal yang sama untuk excludedFileNameExtensions untuk menandakan ekstensi mana yang harus dilewati oleh pengindeks. Jika ekstensi yang sama ada di kedua daftar, pengindeks mengecualikannya dari pengindeksan.

  4. Di bawah configuration, atur dataToExtract untuk mengontrol bagian mana dari blob yang diindeks:

  5. Di bawah configuration, 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 content properti metadata ke bidang yang namanya sama dan bertipe sama dalam indeks. Untuk properti metadata, pengindeks 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 REST API.

Pengindeks berjalan secara otomatis saat dibuat. Anda dapat mencegah tindakan ini dengan mengatur disabled ke true. Untuk mengontrol eksekusi pengindeks, jalankan pengindeks sesuai permintaan atau letakkan sesuai jadwal.

Mengindeks data dari beberapa kontainer Azure Blob ke satu indeks

Ingat bahwa pengindeks hanya dapat mengindeks data dari satu kontainer. Jika Anda perlu mengindeks data dari beberapa kontainer dan mengonsolidasikannya ke dalam satu indeks Pencarian AI, konfigurasikan beberapa pengindeks yang semuanya menunjuk ke indeks yang sama. Ketahui jumlah maksimum pengindeks yang tersedia per SKU.

Misalnya, Anda dapat menggunakan dua pengindeks untuk menarik data dari dua sumber data berbeda bernama my-blob-datasource1 dan my-blob-datasource2. Setiap sumber data menunjuk ke kontainer Azure Blob terpisah, tetapi keduanya mengarahkan ke indeks yang sama bernama my-search-index.

Contoh definisi pengindeks pertama:

POST https://[service name].search.windows.net/indexers?api-version=2026-04-01
{
  "name" : "my-blob-indexer1",
  "dataSourceName" : "my-blob-datasource1",
  "targetIndexName" : "my-search-index",
  "parameters": {
      "batchSize": null,
      "maxFailedItems": null,
      "maxFailedItemsPerBatch": null,
      "configuration": {
          "indexedFileNameExtensions" : ".pdf,.docx",
          "excludedFileNameExtensions" : ".png,.jpeg",
          "dataToExtract": "contentAndMetadata",
          "parsingMode": "default"
      }
  },
  "schedule" : { },
  "fieldMappings" : [ ]
}

Definisi pengindeks kedua yang berjalan secara paralel, contoh:

POST https://[service name].search.windows.net/indexers?api-version=2026-04-01
{
  "name" : "my-blob-indexer2",
  "dataSourceName" : "my-blob-datasource2",
  "targetIndexName" : "my-search-index",
  "parameters": {
      "batchSize": null,
      "maxFailedItems": null,
      "maxFailedItemsPerBatch": null,
      "configuration": {
          "indexedFileNameExtensions" : ".pdf,.docx",
          "excludedFileNameExtensions" : ".png,.jpeg",
          "dataToExtract": "contentAndMetadata",
          "parsingMode": "default"
      }
  },
  "schedule" : { },
  "fieldMappings" : [ ]
}

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. Entri diurutkan dalam urutan kronologis terbalik, sehingga eksekusi terbaru menjadi yang pertama.

Troubleshooting

Gunakan bagian ini untuk mendiagnosis nilai metadata yang hilang dan kegagalan pengindeksan blob umum.

Bidang metadata null dalam hasil pencarian

Jika Anda melihat nilai null atau kosong untuk bidang metadata di hasil pencarian Anda, gunakan daftar periksa ini:

  1. Verifikasi bidang ada di skema indeks Anda: Periksa apakah Anda menentukan bidang untuk setiap properti metadata yang ingin Anda ambil. Jalankan permintaan GET pada indeks Anda untuk mengonfirmasi bidang ada.

  2. Gunakan nama bidang yang benar: Untuk properti blob standar, gunakan nama bergaris bawah, seperti metadata_storage_path alih-alih metadata-storage-path. Untuk metadata kustom, nama bidang harus sama persis dengan kunci metadata blob.

  3. Konfirmasikan pengindeks telah dataToExtract diatur dengan benar:

    • contentAndMetadata (default) mengekstrak konten dan metadata standar/kustom.
    • storageMetadata hanya mengekstrak properti blob standar dan metadata kustom.
    • allMetadata mengekstrak properti standar ditambah metadata khusus jenis konten.

    Periksa konfigurasi pengindeks Anda untuk memastikan pengaturan cocok dengan niat Anda.

  4. Jalankan kembali pengindeks setelah pembaruan skema: Jika Anda menambahkan bidang baru ke indeks Anda, jalankan pengindeks lagi sehingga dokumen diproses terhadap skema yang diperbarui. Dokumen yang ada mungkin perlu diolah ulang sebelum bidang baru diisi.

  5. Periksa riwayat eksekusi pengindeks: Buka pengindeks Anda di portal Azure atau gunakan Dapatkan Status Pengindeks (REST API) untuk melihat detail eksekusi dan pesan kesalahan apa pun.

Kegagalan pengindeks dan tipe konten yang tidak didukung

Secara default, pengindeks blob berhenti segera setelah menemukan blob dengan jenis konten yang tidak didukung, seperti file audio. Anda dapat menggunakan excludedFileNameExtensions parameter untuk melewati jenis konten tertentu.

Jika Anda ingin pengindeksan dilanjutkan saat beberapa dokumen gagal, sesuaikan parameter berikut lalu selidiki dokumen individual nanti. Untuk informasi selengkapnya, lihat Panduan pemecahan masalah pengindeks dan Kesalahan dan peringatan Pengindeks.

Ketika kesalahan terjadi, lima parameter pengindeks mengontrol respons pengindeks:

PUT /indexers/[indexer name]?api-version=2026-04-01
{
  "parameters" : { 
    "maxFailedItems" : 10, 
    "maxFailedItemsPerBatch" : 10,
    "configuration" : { 
        "failOnUnsupportedContentType" : false, 
        "failOnUnprocessableDocument" : false,
        "indexStorageMetadataOnlyForOversizedDocuments": false
      }
    }
}
Pengaturan Nilai yang valid Description
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 jenis 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 pekerjaan atau membiarkannya gagal.
indexStorageMetadataOnlyForOversizedDocuments benar atau salah Blob yang terlalu besar diperlakukan sebagai kesalahan secara default. Jika Anda mengatur parameter ini ke true, pengindeks mencoba mengindeks metadatanya meskipun konten tidak dapat diindeks. Untuk batas ukuran blob, lihat Batas layanan.