Mengindeks blob dan file JSON di Azure AI Search

  • Artikel

Berlaku untuk: Pengindeks Blob, Pengindeks file

Untuk pengindeksan blob di Azure AI Search, artikel ini memperlihatkan kepada Anda cara mengatur properti untuk blob atau file yang terdiri dari dokumen JSON. File JSON di Azure Blob Storage atau Azure Files biasanya mengasumsikan salah satu formulir ini:

  • Satu dokumen JSON
  • Dokumen JSON yang berisi array elemen JSON yang terbentuk dengan baik
  • Dokumen JSON yang berisi banyak entitas, dipisahkan oleh baris baru

Pengindeks blob menyediakan parsingMode parameter untuk mengoptimalkan output dokumen pencarian berdasarkan struktur JSON. Mode penguraian terdiri dari opsi berikut:

parsingMode Sokumen JSON Deskripsi
json Satu per blob (default) Menguraikan blob JSON sebagai satu potongan teks. Setiap blob JSON menjadi satu dokumen penelusuran.
jsonArray Beberapa per blob Menguraikan array JSON dalam blob, di mana setiap elemen array menjadi dokumen penelusuran terpisah.
jsonLines Beberapa per blob Mengurai blob yang berisi beberapa entitas JSON (juga array), dengan elemen individual yang dipisahkan oleh baris baru. Pengindeks memulai dokumen penelusuran baru setelah setiap baris baru.

Untuk jsonArray dan jsonLines, Anda harus meninjau Mengindeks satu blob untuk menghasilkan banyak dokumen penelusuran guna memahami cara pengindeks blob menangani disambiguasi dokumen kunci untuk beberapa dokumen penelusuran yang dihasilkan dari blob yang sama.

Dalam definisi pengindeks, Anda dapat secara opsional mengatur pemetaan bidang untuk memilih properti mana dari dokumen JSON sumber yang digunakan untuk mengisi indeks penelusuran target Anda. Misalnya, saat menggunakan jsonArray mode penguraian, jika array ada sebagai properti tingkat bawah, Anda dapat mengatur properti "documentRoot" yang menunjukkan tempat array ditempatkan dalam blob.

Catatan

Saat mode penguraian JSON digunakan, Azure AI Search mengasumsikan bahwa semua blob menggunakan pengurai yang sama (baik untuk json, jsonArray atau jsonLines). Jika Anda memiliki campuran jenis file yang berbeda di sumber data yang sama, pertimbangkan untuk menggunakan filter ekstensi file untuk mengontrol file mana yang diimpor.

Bagian berikut menjelaskan setiap mode secara lebih rinci. Jika Anda tidak terbiasa dengan klien dan konsep pengindeks, lihat Membuat pengindeks pencarian. Anda juga harus memahami detail konfigurasi pengindeks blob dasar, yang tidak diulang di sini.

Mengindeks dokumen JSON tunggal (satu per blob)

Secara default, pengindeks blob mengurai blob JSON sebagai satu potongan teks, satu dokumen penelusuran untuk setiap blob dalam sebuah kontainer. Jika JSON terstruktur, dokumen penelusuran dapat mencerminkan struktur itu, dengan elemen individual direpresentasikan sebagai bidang individual. Misalnya, anggap saja Anda memiliki dokumen JSON berikut di Azure Blob Storage:

{
    "article" : {
        "text" : "A hopefully useful article explaining how to parse JSON blobs",
        "datePublished" : "2020-04-13",
        "tags" : [ "search", "storage", "howto" ]    
    }
}

Pengindeks blob mengurai dokumen JSON ke dalam satu dokumen penelusuran, memuat indeks dengan mencocokkan "teks", "datePublished", dan "tag" dari sumber dengan bidang indeks target yang dinamai dan diketik secara identik. Diberikan indeks dengan bidang "teks", "datePublished, dan "tag", pengindeks blob dapat menyimpulkan pemetaan yang benar tanpa pemetaan bidang yang ada dalam permintaan.

Meskipun perilaku default adalah satu dokumen pencarian per blob JSON, mengatur mode penguraian json mengubah pemetaan bidang internal untuk konten, mempromosikan bidang di dalam content ke bidang aktual dalam indeks pencarian. Contoh definisi pengindeks untuk mode penguraian json mungkin terlihat seperti ini:

POST https://[service name].search.windows.net/indexers?api-version=2020-06-30
Content-Type: application/json
api-key: [admin key]

{
    "name" : "my-json-indexer",
    "dataSourceName" : "my-blob-datasource",
    "targetIndexName" : "my-target-index",
    "parameters" : { "configuration" : { "parsingMode" : "json" } }
}

Catatan

Seperti halnya semua pengindeks, jika bidang tidak terlalu cocok, Anda harus menentukan pemetaan bidang individual secara eksplisit kecuali Anda menggunakan pemetaan bidang implisit yang tersedia untuk konten blob dan metadata, seperti yang dijelaskan dalam konfigurasi pengindeks blob dasar.

contoh json (file JSON hotel tunggal)

Himpunan data dokumen hotel JSON di GitHub berguna untuk menguji penguraian JSON, saat setiap gumpalan mewakili file JSON terstruktur. Anda dapat mengunggah file data ke Blob Storage dan menggunakan wizard Impor data untuk mengevaluasi dengan cepat bagaimana konten ini diurai ke dalam dokumen pencarian individual.

Himpunan data terdiri dari lima blob, masing-masing berisi dokumen hotel dengan kumpulan alamat dan kumpulan kamar. Pengindeks blob mendeteksi kedua koleksi dan mencerminkan struktur dokumen input dalam skema indeks.

Mengurai array JSON

Atau, Anda dapat menggunakan opsi array JSON. Opsi ini berguna ketika blob berisi array objek JSON yang terbentuk dengan baik, dan Anda ingin setiap elemen menjadi dokumen penelusuran yang terpisah. Menggunakan jsonArrays, blob JSON berikut menghasilkan tiga dokumen terpisah, masing-masing dengan bidang "id" dan "text".

[
    { "id" : "1", "text" : "example 1" },
    { "id" : "2", "text" : "example 2" },
    { "id" : "3", "text" : "example 3" }
]

Properti parameters pada pengindeks berisi nilai mode penguraian. Untuk array JSON, definisi pengindeks akan terlihat mirip dengan contoh berikut.

POST https://[service name].search.windows.net/indexers?api-version=2020-06-30
Content-Type: application/json
api-key: [admin key]

{
    "name" : "my-json-indexer",
    "dataSourceName" : "my-blob-datasource",
    "targetIndexName" : "my-target-index",
    "parameters" : { "configuration" : { "parsingMode" : "jsonArray" } }
}

contoh jsonArrays

Himpunan data JSON New York Philharmonic di GitHub sangat membantu untuk menguji penguraian array JSON. Anda dapat mengunggah file data ke penyimpanan Blob dan menggunakan wizard Impor data untuk mengevaluasi dengan cepat bagaimana konten ini diurai ke dalam dokumen pencarian individual.

Himpunan data terdiri dari delapan blob, masing-masing berisi array JSON dari entitas, dengan total 100 entitas. Entitas bervariasi untuk bidang mana yang diisi, tetapi hasil akhirnya adalah satu dokumen penelusuran per entitas, dari semua array, di semua blob.

Mengurai array JSON bertumpuk

Untuk array JSON yang memiliki elemen bertumpuk, Anda dapat menentukan documentRoot untuk menampilkan struktur multi-level. Misalnya, jika blob Anda terlihat seperti ini:

{
    "level1" : {
        "level2" : [
            { "id" : "1", "text" : "Use the documentRoot property" },
            { "id" : "2", "text" : "to pluck the array you want to index" },
            { "id" : "3", "text" : "even if it's nested inside the document" }  
        ]
    }
}

Gunakan konfigurasi ini untuk mengindeks array yang terdapat dalam properti level2:

{
    "name" : "my-json-array-indexer",
    ... other indexer properties
    "parameters" : { "configuration" : { "parsingMode" : "jsonArray", "documentRoot" : "/level1/level2" } }
}

Mengurai entitas JSON yang dipisahkan oleh baris baru

Jika blob Anda berisi beberapa entitas JSON yang dipisahkan oleh baris baru, dan Anda ingin setiap elemen menjadi dokumen penelusuran terpisah, gunakan jsonLines.

{ "id" : "1", "text" : "example 1" }
{ "id" : "2", "text" : "example 2" }
{ "id" : "3", "text" : "example 3" }

Untuk baris JSON, definisi pengindeks akan terlihat mirip dengan contoh berikut.

POST https://[service name].search.windows.net/indexers?api-version=2020-06-30
Content-Type: application/json
api-key: [admin key]

{
    "name" : "my-json-indexer",
    "dataSourceName" : "my-blob-datasource",
    "targetIndexName" : "my-target-index",
    "parameters" : { "configuration" : { "parsingMode" : "jsonLines" } }
}

Petakan bidang JSON ke bidang penelusuran

Pemetaan bidang mengaitkan bidang sumber dengan bidang tujuan dalam situasi di mana nama dan jenis bidang tidak identik. Tetapi pemetaan bidang juga dapat digunakan untuk mencocokkan bagian-bagian dari dokumen JSON dan "mengangkatnya" ke bidang tingkat atas dari dokumen penelusuran.

Contoh berikut mengilustrasikan skenario ini. Untuk informasi selengkapnya tentang pemetaan bidang secara umum, lihat pemetaan bidang.

{
    "article" : {
        "text" : "A hopefully useful article explaining how to parse JSON blobs",
        "datePublished" : "2016-04-13"
        "tags" : [ "search", "storage", "howto" ]    
    }
}

Asumsikan indeks penelusuran dengan bidang berikut: text dari jenis Edm.String, date dari jenis Edm.DateTimeOffset, dan tags dari jenis Collection(Edm.String). Perhatikan perbedaan antara "datePublished" di sumber dan bidang date di indeks. Untuk memetakan JSON Anda ke dalam bentuk yang diinginkan, gunakan pemetaan bidang berikut:

"fieldMappings" : [
    { "sourceFieldName" : "/article/text", "targetFieldName" : "text" },
    { "sourceFieldName" : "/article/datePublished", "targetFieldName" : "date" },
    { "sourceFieldName" : "/article/tags", "targetFieldName" : "tags" }
    ]

Bidang sumber ditentukan menggunakan notasi JSON Pointer. Anda mulai dengan garis miring untuk merujuk ke akar dokumen JSON Anda, lalu pilih properti yang diinginkan (pada tingkat bertumpuk yang berubah-ubah) dengan menggunakan jalur yang dipisahkan garis miring.

Anda juga dapat merujuk ke elemen array individual dengan menggunakan indeks berbasis nol. Misalnya, untuk memilih elemen pertama array "tags" dari contoh di atas, gunakan pemetaan bidang seperti ini:

{ "sourceFieldName" : "/article/tags/0", "targetFieldName" : "firstTag" }

Catatan

Jika "sourceFieldName" mengacu pada properti yang tidak ada di blob JSON, pemetaan tersebut dilewati tanpa kesalahan. Perilaku ini memungkinkan pengindeksan untuk melanjutkan blob JSON yang memiliki skema berbeda (yang merupakan kasus penggunaan umum). Karena tidak ada pemeriksaan validasi, periksa pemetaan dengan hati-hati untuk kesalahan ketik sehingga Anda tidak kehilangan dokumen karena alasan yang salah.

Langkah berikutnya