Indeks data dari Azure Data Lake Storage Gen2

Artikel
09/01/2024

Dalam artikel ini, pelajari cara mengonfigurasi pengindeks yang mengimpor konten dari Azure Data Lake Storage (ADLS) Gen2 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 pengindeksan dari ADLS Gen2. 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.

Untuk sampel kode di C#, lihat Mengindeks Data Lake Gen2 menggunakan ID Microsoft Entra di GitHub.

Prasyarat

ADLS Gen2 dengan namespace hierarki diaktifkan. ADLS Gen2 tersedia melalui Azure Storage. Saat menyiapkan akun penyimpanan, Anda memiliki opsi untuk mengaktifkan namespace hierarkis, mengatur file ke dalam hierarki direktori dan subdirektori berlapis. Dengan mengaktifkan namespace hierarkis, Anda mengaktifkan ADLS Gen2.
Tingkat akses untuk ADLS Gen2 termasuk panas, dingin, dan arsip. Hanya panas dan dingin yang dapat diakses oleh pengindeks pencarian.
Blob yang berisi teks. Jika Anda memiliki data biner, Anda dapat menyertakan pengayaan AI untuk analisis gambar. Konten blob tidak boleh melebihi batas pengindeks untuk tingkat layanan pencarian Anda.
Izin baca di Azure Storage. "Akses penuh" string koneksi menyertakan kunci yang memberikan akses ke konten, tetapi jika Anda menggunakan peran Azure sebagai gantinya, pastikan identitas terkelola layanan pencarian memiliki izin Storage Blob Data Reader.
Gunakan klien REST untuk merumuskan panggilan REST yang mirip dengan yang diperlihatkan dalam artikel ini.

Catatan

ADLS Gen2 menerapkan model kontrol akses yang mendukung kontrol akses berbasis peran Azure (Azure RBAC) dan daftar kontrol akses (ACL) seperti POSIX di tingkat blob. Pencarian Azure AI tidak mendukung izin tingkat dokumen. Semua pengguna memiliki tingkat akses yang sama ke semua konten yang dapat dicari dan dapat diambil dalam indeks. Jika izin tingkat dokumen adalah persyaratan aplikasi, pertimbangkan pemangkasan keamanan sebagai solusi potensial.

Format dokumen yang didukung

Pengindeks ADLS Gen2 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 inklusi atau pengecualian, pengindeks akan 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.

Mengindeks metadata blob

Metadata blob juga dapat diindeks, dan itu berguna jika Anda berpikir salah satu properti metadata standar atau kustom akan 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 akan 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.

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:

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

Atur "jenis" ke "adlsgen2" (diperlukan).
Atur "credentials" ke string koneksi Azure Storage. Bagian berikutnya menjelaskan format yang didukung.
Atur "container" 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).

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.

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

{
    "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 }     
    ]
}

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. Pengindeks secara otomatis mengodekan properti metadata kunci, tanpa memerlukan konfigurasi atau pemetaan bidang.
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. Pengindeks dapat membaca properti metadata kustom, properti metadata standar, dan properti metadata khusus konten.

Mengonfigurasi dan menjalankan pengindeks ADLS Gen2

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.

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

{
  "name" : "my-adlsgen2-indexer",
  "dataSourceName" : "my-adlsgen2-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" : [ ]
}

Atur "batchSize" jika default (10 dokumen) sedang menggunakan atau membangi sumber daya yang tersedia. Ukuran batch default berukuran spesifik sumber data. Pengindeksan blob menetapkan ukuran batch pada 10 dokumen sebagai pengenalan ukuran dokumen rata-rata yang lebih besar.
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.
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.
Di bagian "konfigurasi", atur "parsingMode" jika blob harus dipetakan ke beberapa dokumen pencarian, atau jika terdiri dari teks biasa, dokumen JSON, atau file CSV.
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.
Lihat Membuat pengindeks untuk informasi selengkapnya tentang properti lain. Untuk daftar lengkap deskripsi parameter, lihat Membuat Pengindeks (REST) 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=2024-07-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":"2024-02-21T00:23:24.957Z",
            "endTime":"2024-02-21T00:36:47.752Z",
            "errors":[],
            "itemsProcessed":1599501,
            "itemsFailed":0,
            "initialTrackingState":null,
            "finalTrackingState":null
        },
        "executionHistory":
        [
            {
                "status":"success",
                "errorMessage":null,
                "startTime":"2024-02-21T00:23:24.957Z",
                "endTime":"2024-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 pengindeksan dilanjutkan meskipun terjadi kesalahan, lalu 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=2024-07-01
{
  "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.

Batasan

Tidak seperti pengindeks blob, pengindeks ADLS Gen2 tidak dapat menggunakan token SAS tingkat kontainer untuk menghitung dan mengindeks konten dari akun penyimpanan. Ini karena pengindeks melakukan pemeriksaan untuk menentukan apakah akun penyimpanan memiliki namespace hierarkis yang diaktifkan dengan memanggil FILESystem - Dapatkan properti API. Untuk akun penyimpanan di mana namespace hierarki tidak diaktifkan, pelanggan disarankan untuk menggunakan pengindeks blob untuk memastikan enumerasi blob yang berkinerja.
Jika properti metadata_storage_path dipetakan menjadi bidang kunci indeks, blob tidak dijamin akan diindeks ulang setelah nama direktori diganti. Jika Anda ingin mengindeks ulang blob yang merupakan bagian dari direktori yang diganti namanya, perbarui LastModified tanda waktu untuk semuanya.

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:

Bagikan melalui