Pemetaan dan transformasi bidang menggunakan pengindeks Pencarian Azure AI

Artikel ini menjelaskan cara mengatur pemetaan bidang eksplisit yang menetapkan jalur data antara bidang sumber dalam sumber data yang didukung dan bidang target dalam indeks pencarian.

Kapan mengatur pemetaan bidang

Saat pengindeks Pencarian Azure AI memuat indeks pencarian, pengindeks menentukan jalur data menggunakan pemetaan bidang sumber ke tujuan. Pemetaan bidang implisit bersifat internal dan terjadi saat nama bidang dan jenis data kompatibel antara sumber dan tujuan. Jika input dan output tidak cocok, Anda dapat menentukan pemetaan bidang eksplisit untuk menyiapkan jalur data, seperti yang dijelaskan dalam artikel ini.

Pemetaan bidang juga dapat digunakan untuk konversi data ringan, seperti pengodean atau dekode, melalui fungsi pemetaan. Jika diperlukan lebih banyak pemrosesan, pertimbangkan Azure Data Factory untuk menjegal kesenjangan.

Pemetaan bidang berlaku untuk:

• Struktur data fisik di kedua sisi jalur data. Struktur data logis yang dibuat oleh keterampilan hanya berada dalam memori. Gunakan outputFieldMappings untuk memetakan simpul dalam memori ke bidang output dalam indeks pencarian.

• Indeks Pencarian AI induk saja. Untuk indeks "sekunder" dengan dokumen "turunan" atau "gugus", lihat skenario pemetaan bidang tingkat lanjut.

• Bidang pencarian tingkat atas saja, di mana targetFieldName adalah bidang sederhana atau koleksi. Bidang target tidak boleh berupa jenis kompleks.

Skenario yang didukung

Pastikan Anda menggunakan sumber data yang didukung untuk pengindeksan yang digerakkan oleh pengindeks.

Bidang kompleks tidak didukung dalam pemetaan bidang. Struktur sumber Anda (struktur berlapis atau hierarkis) harus sama persis dengan jenis kompleks dalam indeks sehingga pemetaan default berfungsi. Untuk informasi selengkapnya, lihat Tutorial: Mengindeks blob JSON berlapis misalnya. Jika Anda mendapatkan kesalahan yang mirip dengan "Field mapping specifies target field 'Address/city' that doesn't exist in the index", itu karena pemetaan bidang target tidak dapat berupa tipe kompleks.

Secara opsional, Anda mungkin hanya ingin beberapa simpul dalam struktur kompleks. Untuk mendapatkan simpul individual, Anda dapat meratakan data masuk ke dalam koleksi string (lihat outputFieldMappings untuk solusi ini).

Menentukan pemetaan bidang

Bagian ini menjelaskan langkah-langkah untuk menyiapkan pemetaan bidang.

PUT https://[service name].search.windows.net/indexers/myindexer?api-version=[api-version]
Content-Type: application/json
api-key: [admin key]
{
    "dataSourceName" : "mydatasource",
    "targetIndexName" : "myindex",
    "fieldMappings" : [ { "sourceFieldName" : "_city", "targetFieldName" : "city" } ]
}

"fieldMappings" : [
    { "sourceFieldName" : "text", "targetFieldName" : "textStandardEnglishAnalyzer" },
    { "sourceFieldName" : "text", "targetFieldName" : "textSoundexAnalyzer" }
]

var indexer = new SearchIndexer("hotels-sql-idxr", dataSource.Name, searchIndex.Name)
{
    Description = "SQL data indexer",
    Schedule = schedule,
    Parameters = parameters,
    FieldMappings =
    {
        new FieldMapping("_hotelId") {TargetFieldName = "HotelId", FieldMappingFunction.Base64Encode()},
        new FieldMapping("Amenities") {TargetFieldName = "Tags"}
    }
};

await indexerClient.CreateOrUpdateIndexerAsync(indexer);

Fungsi dan contoh pemetaan

Fungsi pemetaan bidang mengubah konten bidang sebelum disimpan dalam indeks. Fungsi pemetaan berikut saat ini didukung:

• base64Encode
• base64Decode
• extractTokenAtPosition
• fixedLengthEncode
• jsonArrayToStringCollection
• toJson
• urlEncode
• urlDecode

Perhatikan bahwa fungsi-fungsi ini didukung secara eksklusif untuk indeks induk saat ini. Mereka tidak kompatibel dengan pemetaan indeks yang dipotong, oleh karena itu, fungsi-fungsi ini tidak dapat digunakan untuk proyeksi indeks.

fungsi base64Encode

Melakukan pengodean Base64 yang aman untuk URL dari string input. Mengasumsikan bahwa input dikodekan UTF-8.

Contoh: Pengodean dasar kunci dokumen

Hanya karakter aman URL yang dapat muncul di kunci dokumen Pencarian Azure AI (sehingga Anda dapat mengakses dokumen menggunakan Lookup API). Jika bidang sumber untuk kunci Anda berisi karakter URL-tidak aman, seperti - dan \, gunakan base64Encode fungsi untuk mengonversinya pada waktu pengindeksan.

Contoh berikut ini menentukan fungsi base64Encode pada metadata_storage_name untuk menangani karakter yang tidak didukung.

PUT /indexers?api-version=2026-04-01
{
  "dataSourceName" : "my-blob-datasource ",
  "targetIndexName" : "my-search-index",
  "fieldMappings" : [
    { 
        "sourceFieldName" : "metadata_storage_name", 
        "targetFieldName" : "key", 
        "mappingFunction" : { 
            "name" : "base64Encode",
            "parameters" : { "useHttpServerUtilityUrlTokenEncode" : false }
        } 
    }
  ]
}

Kunci dokumen (sebelum dan sesudah konversi) tidak boleh lebih dari 1.024 karakter. Saat Anda mengambil kunci yang dikodekan pada waktu pencarian, gunakan base64Decode fungsi untuk mendapatkan nilai kunci asli, dan gunakan itu untuk mengambil dokumen sumber.

Contoh: Membuat bidang yang dikodekan dasar "dapat dicari"

Ada kalanya Anda perlu menggunakan versi yang dikodekan dari bidang seperti metadata_storage_path sebagai kunci, namun juga membutuhkan versi yang tidak dikodekan untuk pencarian teks lengkap. Untuk mendukung kedua skenario, Anda dapat memetakan metadata_storage_path ke dua bidang: satu untuk kunci (dikodekan), dan yang kedua untuk bidang jalur yang dapat kita asumsikan dikaitkan seperti searchable dalam skema indeks.

PUT /indexers/blob-indexer?api-version=2026-04-01
{
    "dataSourceName" : " blob-datasource ",
    "targetIndexName" : "my-target-index",
    "schedule" : { "interval" : "PT2H" },
    "fieldMappings" : [
        { "sourceFieldName" : "metadata_storage_path", "targetFieldName" : "key", "mappingFunction" : { "name" : "base64Encode" } },
        { "sourceFieldName" : "metadata_storage_path", "targetFieldName" : "path" }
      ]
}

Contoh - mempertahankan nilai asli

Pengindeks penyimpanan blob secara otomatis menambahkan pemetaan bidang dari metadata_storage_path, URI blob, ke bidang kunci indeks jika tidak ada pemetaan bidang yang ditentukan. Nilai ini dikodekan Base64 sehingga aman digunakan sebagai kunci dokumen Pencarian Azure AI. Contoh berikut menunjukkan cara memetakan versi Base64 yang dikodekan URL-safe secara bersamaan ke bidang metadata_storage_path dan mempertahankan nilai asli dalam bidang index_key.

"fieldMappings": [
  {
    "sourceFieldName": "metadata_storage_path",
    "targetFieldName": "metadata_storage_path"
  },
  {
    "sourceFieldName": "metadata_storage_path",
    "targetFieldName": "index_key",
    "mappingFunction": {
       "name": "base64Encode"
    }
  }
]

Jika Anda tidak menyertakan properti parameter untuk fungsi pemetaan Anda, itu default ke nilai {"useHttpServerUtilityUrlTokenEncode" : true}.

Pencarian Azure AI mendukung dua pengodean Base64 yang berbeda. Anda harus menggunakan parameter yang sama saat mengodekan dan mendekode bidang yang sama. Untuk informasi selengkapnya, lihat opsi pengodean base64 untuk memutuskan parameter mana yang akan digunakan.

fungsi base64Decode

Melakukan decoding Base64 dari string masukan. Input diasumsikan sebagai string yang dikodekan Base64 url-safe .

Contoh - dekode metadata blob atau URL

Data sumber Anda mungkin berisi string yang dikodekan Base64, seperti string metadata blob atau URL web, yang ingin Anda cari sebagai teks biasa. Anda dapat menggunakan base64Decode fungsi untuk mengubah data yang dikodekan kembali menjadi string reguler saat mengisi indeks pencarian Anda.

"fieldMappings" : [
  {
    "sourceFieldName" : "Base64EncodedMetadata",
    "targetFieldName" : "SearchableMetadata",
    "mappingFunction" : { 
      "name" : "base64Decode", 
      "parameters" : { "useHttpServerUtilityUrlTokenDecode" : false }
    }
  }
]

Jika Anda tidak menyertakan properti parameter, properti tersebut default ke nilai {"useHttpServerUtilityUrlTokenEncode" : true}.

Pencarian Azure AI mendukung dua pengodean Base64 yang berbeda. Anda harus menggunakan parameter yang sama saat mengodekan dan mendekode bidang yang sama. Untuk informasi selengkapnya, lihat opsi pengodean base64 untuk memutuskan parameter mana yang akan digunakan.

opsi pengkodean base64

Pencarian Azure AI mendukung pengodean base64 yang aman URL dan pengodean base64 normal. String yang dikodekan base64 selama pengindeksan harus didekode nanti dengan opsi pengodean yang sama, atau jika tidak, hasilnya tidak akan cocok dengan yang asli.

useHttpServerUtilityUrlTokenEncode Jika parameter atau useHttpServerUtilityUrlTokenDecode untuk pengodean dan dekode masing-masing diatur ke true, maka base64Encode berperilaku seperti HttpServerUtility.UrlTokenEncode dan base64Decode berperilaku seperti HttpServerUtility.UrlTokenDecode.

Pustaka .NET di Pencarian Azure AI mengasumsikan kerangka kerja .NET lengkap, yang menyediakan pengodean bawaan. Opsi useHttpServerUtilityUrlTokenEncode dan useHttpServerUtilityUrlTokenDecode menerapkan fungsionalitas bawaan ini. Jika Anda menggunakan .NET Core atau kerangka kerja lain, sebaiknya atur opsi tersebut ke false dan memanggil fungsi pengodean dan dekode kerangka kerja Anda secara langsung.

Tabel berikut membandingkan pengodean base64 yang berbeda dari string 00>00?00. Untuk menentukan pemrosesan yang diperlukan (jika ada) untuk fungsi base64 Anda, terapkan fungsi enkode pustaka Anda pada string 00>00?00 dan bandingkan output dengan output MDA-MDA_MDAyang diharapkan .

fungsi extractTokenAtPosition

Memisahkan bidang string menggunakan pemisah yang ditentukan, dan memilih token pada posisi yang ditentukan dalam pemisahan yang dihasilkan.

Fungsi ini menggunakan parameter berikut:

• delimiter: string untuk digunakan sebagai pemisah saat memisahkan string input.
• position: posisi berbasis nol dari token bilangan bulat untuk dipilih setelah string input dipecah.

Misalnya, jika input adalah Jane Doe, delimiter adalah " "(spasi) dan position adalah 0, hasilnya adalah Jane; jika position adalah 1, hasilnya adalah Doe. Jika posisi mengacu pada token yang tidak ada, kesalahan akan ditampilkan.

Contoh - mengekstrak nama

Sumber data Anda berisi PersonName bidang, dan Anda ingin mengindeksnya sebagai dua bidang terpisah FirstName dan LastName. Anda dapat menggunakan fungsi ini untuk membagi input menggunakan karakter spasi sebagai pemisah.

"fieldMappings" : [
  {
    "sourceFieldName" : "PersonName",
    "targetFieldName" : "FirstName",
    "mappingFunction" : { "name" : "extractTokenAtPosition", "parameters" : { "delimiter" : " ", "position" : 0 } }
  },
  {
    "sourceFieldName" : "PersonName",
    "targetFieldName" : "LastName",
    "mappingFunction" : { "name" : "extractTokenAtPosition", "parameters" : { "delimiter" : " ", "position" : 1 } }
  }]

fungsi jsonArrayToStringCollection

Mengubah string yang diformat sebagai array string JSON menjadi array string yang dapat digunakan untuk mengisi Collection(Edm.String) bidang dalam indeks.

Misalnya, jika string input adalah ["red", "white", "blue"], maka bidang target jenis Collection(Edm.String) akan diisi dengan tiga nilai red, , whitedan blue. Untuk nilai input yang tidak dapat diurai sebagai array string JSON, kesalahan dikembalikan.

Contoh - mengisi koleksi dari data relasional

Azure SQL Database tidak memiliki tipe data bawaan yang secara alami memetakan ke bidang Collection(Edm.String) di Pencarian Azure AI. Untuk mengisi bidang kumpulan string, Anda dapat melakukan praproses data sumber Anda sebagai array string JSON lalu menggunakan jsonArrayToStringCollection fungsi pemetaan.

"fieldMappings" : [
  {
    "sourceFieldName" : "tags", 
    "mappingFunction" : { "name" : "jsonArrayToStringCollection" }
  }]

fungsi urlEncode

Fungsi ini dapat digunakan untuk mengodekan string sehingga "URL aman". Saat digunakan dengan string yang berisi karakter yang tidak diizinkan dalam URL, fungsi ini akan mengonversi karakter "tidak aman" tersebut menjadi karakter-entitas yang setara. Fungsi ini menggunakan format pengodean UTF-8.

Contoh - pencarian kunci dokumen

urlEncode fungsi dapat digunakan sebagai alternatif untuk base64Encode fungsi, jika hanya karakter URL yang tidak aman yang akan dikonversi, sambil menyimpan karakter lain as-is.

Katakanlah, string input adalah <hello> - maka bidang target jenis (Edm.String) akan diisi dengan nilai %3chello%3e

Saat Anda mengambil kunci yang dikodekan pada waktu pencarian, Anda kemudian dapat menggunakan urlDecode fungsi untuk mendapatkan nilai kunci asli, dan menggunakannya untuk mengambil dokumen sumber.

"fieldMappings" : [
  {
    "sourceFieldName" : "SourceKey",
    "targetFieldName" : "IndexKey",
    "mappingFunction" : {
      "name" : "urlEncode"
    }
  }
]

fungsi urlDecode

Fungsi ini mengonversi string yang dikodekan URL menjadi string yang didekodekan menggunakan format pengodean UTF-8.

Contoh - memecahkan kode metadata blob

Beberapa klien penyimpanan Azure secara otomatis mengodekan URL metadata blob jika berisi karakter non-ASCII. Namun, jika Anda ingin membuat metadata tersebut dapat dicari (sebagai teks biasa), Anda dapat menggunakan urlDecode fungsi untuk mengubah data yang dikodekan kembali menjadi string reguler saat mengisi indeks pencarian Anda.

"fieldMappings" : [
  {
    "sourceFieldName" : "UrlEncodedMetadata",
    "targetFieldName" : "SearchableMetadata",
    "mappingFunction" : {
      "name" : "urlDecode"
    }
  }
]

fungsi fixedLengthEncode

Fungsi ini mengonversi string dengan panjang apa pun menjadi string panjang tetap.

Contoh - memetakan kunci dokumen yang terlalu panjang

Ketika terjadi kesalahan yang terkait dengan panjang kunci dokumen yang melebihi 1024 karakter, fungsi ini dapat diterapkan untuk mengurangi panjang kunci dokumen.

"fieldMappings" : [
 {
   "sourceFieldName" : "metadata_storage_path",
   "targetFieldName" : "your key field",
   "mappingFunction" : {
     "name" : "fixedLengthEncode"
   }
 }
]

fungsi toJson

Fungsi ini mengonversi string menjadi objek JSON yang diformat. Ini dapat digunakan untuk skenario di mana sumber data, seperti Azure SQL, tidak secara asli mendukung jenis data senyawa atau hierarkis, lalu memetakannya ke bidang kompleks.

Contoh - memetakan konten teks ke bidang kompleks

Asumsikan ada baris SQL dengan string JSON yang perlu dipetakan ke bidang kompleks (yang ditentukan secara sesuai) dalam indeks, toJson fungsi dapat digunakan untuk mencapai ini. Misalnya, jika bidang kompleks dalam indeks perlu diisi dengan data berikut:

{
    "id": "5",
    "info": {
        "name": "Jane",
        "surname": "Smith",
        "skills": [
            "SQL",
            "C#",
            "Azure"
        ],
        "dob": "2005-11-04T12:00:00"
    }
}

Ini dapat dicapai dengan menggunakan fungsi pemetaan toJson pada kolom string JSON di baris SQL yang terlihat seperti ini: {"id": 5, "info": {"name": "Jane", "surname": "Smith", "skills": ["SQL", "C#", "Azure"]}, "dob": "2005-11-04T12:00:00"}.

Pemetaan bidang perlu ditentukan seperti yang ditunjukkan di bawah ini.

"fieldMappings" : [
  {
    "sourceFieldName" : "content",
    "targetFieldName" : "complexField",
    "mappingFunction" : {
      "name" : "toJson"
    }
  }
]

Skenario pemetaan bidang tingkat lanjut

Dalam skenario di mana Anda memiliki hubungan dokumen "satu-ke-banyak", seperti pemotongan (chunking) atau pemisahan (splitting) data, ikuti panduan ini untuk memetakan bidang dari dokumen induk ke dokumen "anak" (potongan):

1. Melewatkan pengindeksan dokumen induk

Jika Anda melewatkan pengindeksan dokumen induk (dengan mengatur projectionMode ke skipIndexingParentDocuments dalam kumpulan keterampilan indexProjections), gunakan proyeksi indeks untuk memetakan bidang dari dokumen induk ke dokumen "turunan".

2. Mengindeks dokumen induk dan "anak"

Jika Anda mengindeks dokumen induk dan dokumen "turunan":

• Gunakan pemetaan bidang untuk memetakan bidang ke dokumen induk.
• Gunakan proyeksi indeks untuk memetakan field ke dokumen turunan.

3. Memetakan nilai yang telah diubah melalui fungsi ke dokumen induk dan/atau dokumen "anak"

Jika bidang dalam dokumen induk memerlukan transformasi (menggunakan fungsi pemetaan seperti pengodean) dan perlu dipetakan ke dokumen induk dan/atau dokumen turunan:

• Terapkan transformasi menggunakan fungsi pemetaan bidang di pengindeks.
• Gunakan proyeksi indeks dalam skillset untuk memetakan bidang yang telah diubah ke dokumen "anak".

Lihat juga

• Jenis data yang didukung di Pencarian Azure AI
• Peta jenis data SQL