Azure Yapay Zeka Arama dizin oluşturucuları kullanan alan eşlemeleri ve dönüştürmeleri

Bu makalede, desteklenen bir veri kaynağındaki kaynak alanlar ile arama dizinindeki hedef alanlar arasında veri yolunu oluşturan açık alan eşlemelerinin nasıl ayarlanacağı açıklanmaktadır.

Alan eşlemesi ne zaman ayarlanır?

Azure Yapay Zeka Arama dizin oluşturucu bir arama dizini yüklediğinde, kaynak-hedef alan eşlemelerini kullanarak veri yolunu belirler. Örtük alan eşlemeleri dahilidir ve alan adları ve veri türleri kaynak ve hedef arasında uyumlu olduğunda gerçekleşir. Girişler ve çıkışlar eşleşmiyorsa, bu makalede açıklandığı gibi veri yolunu ayarlamak için açık alan eşlemeleri tanımlayabilirsiniz.

Alan eşlemeleri, eşleme işlevleri aracılığıyla kodlama veya kod çözme gibi basit veri dönüştürmeleri için de kullanılabilir. Daha fazla işlem gerekiyorsa, boşluğu kapatmak için Azure Data Factory göz önünde bulundurun.

Alan eşlemeleri şu şekilde uygulanır:

• Veri yolunun her iki tarafındaki fiziksel veri yapıları. Beceriler tarafından oluşturulan mantıksal veri yapıları yalnızca bellekte bulunur. Bellek içi düğümleri arama dizinindeki çıkış alanlarıyla eşlemek için outputFieldMappings kullanın.

• Yalnızca ana yapay zeka arama dizinleri. "Alt" belgeler veya "öbekler" içeren "ikincil" dizinler için gelişmiş alan eşleme senaryolarına bakın.

• Yalnızca en üst düzey arama alanları; burada targetFieldName basit bir alan veya koleksiyondur. Hedef alan karmaşık bir tür olamaz.

Desteklenen senaryolar

Dizin oluşturucu ile dizin oluşturma için desteklenen bir veri kaynağı kullandığınızdan emin olun.

Karmaşık alanlar alan eşlemesinde desteklenmez. Varsayılan eşlemelerin çalışması için kaynak yapınızın (iç içe veya hiyerarşik yapılar) dizindeki karmaşık türle tam olarak eşleşmesi gerekir. Daha fazla bilgi için Örnek: İç içe JSON bloblarını dizin Eğitimi konusuna bakın. gibi "Field mapping specifies target field 'Address/city' that doesn't exist in the index"bir hata alırsanız, bunun nedeni hedef alan eşlemelerinin karmaşık bir tür olamaz olmasıdır.

İsteğe bağlı olarak, karmaşık yapıda yalnızca birkaç düğüm olmasını isteyebilirsiniz. Tek tek düğümleri almak için, gelen verileri bir dize koleksiyonuna düzleştirebilirsiniz (bu geçici çözüm için outputFieldMappings bölümüne bakın).

Bir alan eşlemesi tanımlayın

Bu bölümde alan eşlemelerini ayarlama adımları açıklanmaktadır.

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);

Eşleme işlevleri ve örnekleri

Alan eşleme işlevi, bir alanın içeriğini dizinde depolanmadan önce dönüştürür. Şu anda aşağıdaki eşleme işlevleri desteklenmektedir:

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

Bu işlevlerin şu anda yalnızca üst dizinler için desteklendiğini unutmayın. Bunlar öbeklenmiş dizin eşlemesi ile uyumlu değildir, bu nedenle bu işlevler dizin projeksiyonları için kullanılamaz.

base64Encode işlevi

Giriş dizesinin URL güvenli Base64 kodlamasını gerçekleştirir. Girişin UTF-8 kodlanmış olduğunu varsayar.

Örnek: Belge anahtarını temel kodlama

Azure Yapay Zeka Arama belge anahtarında yalnızca URL güvenli karakterler görüntülenebilir (böylece belgeyi Lookup API) kullanarak ele alabilirsiniz). Anahtarınızın kaynak alanında - ve \ gibi URL için güvenli olmayan karakterler varsa, dizin oluşturma zamanında dönüştürmek için base64Encode işlevini kullanın.

Aşağıdaki örnek desteklenmeyen karakterleri işlemek için base64Encode metadata_storage_name işlevini belirtir.

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

Belge anahtarı (dönüştürmeden önce ve sonra) 1.024 karakterden uzun olamaz. Arama yaparken kodlanmış anahtarı aldığınızda, orijinal anahtar değerini almak için base64Decode işlevini kullanın ve bu değeri kaynak belgeyi almak için kullanın.

Örnek: Temel kodlanmış bir alanı "aranabilir" hale getirme

Bir alanın anahtar olarak metadata_storage_path kodlanmış bir sürümünü kullanmanız gereken ancak tam metin araması için kodlanmamış bir sürüme de ihtiyacınız olduğu zamanlar vardır. Her iki senaryoyu da desteklemek için metadata_storage_path iki alana eşleyebilirsiniz: biri anahtar için (kodlanmış) ve diğeri dizin şemasında searchable olarak atfedilen bir yol alanı için.

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

Örnek - özgün değerleri koruma

Blob depolama dizin oluşturucu, hiçbir alan eşlemesi metadata_storage_pathbelirtilmezse, blobun URI'sinden dizin anahtarı alanına otomatik olarak bir alan eşlemesi ekler. Bu değer Base64 kodlanmış olduğundan, Azure Yapay Zeka Arama belge anahtarı olarak kullanmak güvenlidir. Aşağıdaki örnek, URL güvenli Base64 kodlanmış sürümünü metadata_storage_path aynı anda bir alanla eşlemeyi ve alandaki index_key özgün değeri metadata_storage_path korumayı gösterir:

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

Eşleme işleviniz için bir parameters özelliği eklemezseniz, varsayılan değer {"useHttpServerUtilityUrlTokenEncode" : true} olur.

Azure Yapay Zeka Arama iki farklı Base64 kodlamasını destekler. Aynı alanı kodlarken ve kodunu çözerken aynı parametreleri kullanmanız gerekir. Daha fazla bilgi için hangi parametrelerin kullanılacağına karar vermek için base64 kodlama seçenekleri bölümüne bakın.

base64Decode işlevi

Giriş dizesinin Base64 kodunu çözme işlemini gerçekleştirir. Girişin URL güvenli base64 ile kodlanmış bir dize olduğu varsayılır.

Örnek - blob meta verilerinin veya URL'lerinin kodunu çözme

Kaynak verileriniz, düz metin olarak aranabilir hale getirmek istediğiniz blob meta veri dizeleri veya web URL'leri gibi Base64 ile kodlanmış dizeler içerebilir. arama dizininizi doldurarak kodlanmış verileri normal dizelere geri döndürmek için işlevini kullanabilirsiniz base64Decode .

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

Parametre özelliği eklemezseniz, varsayılan olarak değerine {"useHttpServerUtilityUrlTokenEncode" : true}sahip olur.

Azure Yapay Zeka Arama iki farklı Base64 kodlamasını destekler. Aynı alanı kodlarken ve kodunu çözerken aynı parametreleri kullanmanız gerekir. Daha fazla bilgi için hangi parametrelerin kullanılacağına karar vermek için base64 kodlama seçenekleri bölümüne bakın.

base64 kodlama seçenekleri

Azure Yapay Zeka Arama, URL güvenli base64 kodlamasını ve normal base64 kodlamasını destekler. Dizin oluşturma sırasında base64 kodlanmış bir dizenin kodu daha sonra aynı kodlama seçenekleriyle çözülmelidir, aksi halde sonuç özgün ile eşleşmez.

Eğer useHttpServerUtilityUrlTokenEncode ve useHttpServerUtilityUrlTokenDecode parametreleri sırasıyla kodlama ve kod çözme için true olarak ayarlanırsa, o zaman base64Encode HttpServerUtility.UrlTokenEncode gibi davranır ve HttpServerUtility.UrlTokenDecode gibi base64Decode davranır.

Azure Yapay Zeka Arama'deki .NET kitaplıkları, yerleşik kodlama sağlayan tam .NET Framework'ün olduğunu varsayar. useHttpServerUtilityUrlTokenEncode ve useHttpServerUtilityUrlTokenDecode seçenekleri bu yerleşik işlevselliği uygular. .NET Core veya başka bir çerçeve kullanıyorsanız, bu seçenekleri false olarak ayarlamanızı ve çerçevenizin kodlama ve kod çözme işlevlerini doğrudan çağırmanızı öneririz.

Aşağıdaki tablo, dizesinin 00>00?00farklı base64 kodlamalarını karşılaştırır. base64 işlevleriniz için gerekli işlemeyi (varsa) belirlemek için dizeye 00>00?00 kitaplık kodlama işlevinizi uygulayın ve çıktıyı beklenen çıkışla MDA-MDA_MDAkarşılaştırın.

extractTokenAtPosition işlevi

Belirtilen sınırlayıcıyı kullanarak bir dize alanını böler ve sonuçta elde edilen bölmede belirteci belirtilen konumda seçer.

Bu işlev aşağıdaki parametreleri kullanır:

• delimiter: giriş dizesini bölerken ayırıcı olarak kullanılacak bir dize.
• position: Giriş dizesi bölündükten sonra seçilebilecek belirtecin sıfır tabanlı tamsayı konumu.

Örneğin, giriş Jane Doe ise, delimiter" " (boşluk) ve position 0 olduğunda, sonuç Jane olur; position 1 olduğunda, sonuç Doe olur. Konum varolmayan bir belirteçe başvuruyorsa bir hata döndürülür.

Örnek - ad çıkarma

Veri kaynağınız bir PersonName alan içeriyor ve bunu iki ayrı FirstName ve LastName alan olarak dizine almak istiyorsunuz. Sınırlayıcı olarak boşluk karakterini kullanarak girişi bölmek için bu işlevi kullanabilirsiniz.

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

jsonArrayToStringCollection işlevi

Dizelerin JSON dizisi olarak biçimlendirilmiş bir dizeyi, dizindeki bir alanı doldurmak için kullanılabilecek bir Collection(Edm.String) dize dizisine dönüştürür.

Örneğin, giriş dizesi ["red", "white", "blue"] ise, türündeki Collection(Edm.String) hedef alan, red, white, ve blue olmak üzere üç değerle doldurulur. JSON dize dizileri olarak ayrıştırılamayan giriş değerleri için bir hata döndürülür.

Örnek - ilişkisel verilerden koleksiyonu doldurma

Azure SQL Veritabanı, Azure Yapay Zeka Arama'daki Collection(Edm.String) alanlarıyla doğal olarak eşlenen yerleşik bir veri türüne sahip değildir. Dize koleksiyonu alanlarını doldurmak için, kaynak verilerinizi JSON dize dizisi olarak önceden işleyebilir ve ardından eşleme işlevini kullanabilirsiniz jsonArrayToStringCollection .

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

urlEncode işlevi

Bu işlev bir dizeyi "URL güvenli" olacak şekilde kodlamak için kullanılabilir. URL'de izin verilmeyen karakterler içeren bir dizeyle kullanıldığında, bu işlev bu "güvenli olmayan" karakterleri karakter-varlık eşdeğerlerine dönüştürür. Bu işlev UTF-8 kodlama biçimini kullanır.

Örnek - belge anahtarı arama

urlEncode işlevi, base64Encode işlevine alternatif olarak kullanılabilir; yalnızca URL güvenli olmayan karakterler dönüştürülecekse diğer karakterler olduğu gibi tutulur.

Örneğin, giriş dizesi şöyledir <hello> ; ardından türdeki (Edm.String) hedef alan değerle doldurulur %3chello%3e

Kodlanmış anahtarı arama zamanında aldığınızda, özgün anahtar değerini almak için urlDecode işlevini kullanabilir ve ardından bu anahtar değerle kaynak belgeyi alabilirsiniz.

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

urlDecode işlevi

Bu işlev, UTF-8 kodlama biçimini kullanarak URL ile kodlanmış bir dizeyi kodu çözülen bir dizeye dönüştürür.

Örnek - blob meta verilerinin kodunu çözme

Bazı Azure depolama istemcileri, ASCII olmayan karakterler içeriyorsa blob meta verilerini otomatik olarak URL kodlar. Ancak, bu tür meta verileri aranabilir (düz metin olarak) yapmak istiyorsanız, arama dizininizi doldurarak kodlanmış verileri normal dizelere geri döndürmek için işlevini kullanabilirsiniz urlDecode .

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

fixedLengthEncode işlevi

Bu işlev, herhangi bir uzunluktaki bir dizeyi sabit uzunlukta bir dizeye dönüştürür.

Örnek - çok uzun olan belge anahtarlarını eşleme

Belge anahtarı uzunluğunun 1024 karakteri aşması ile ilgili hatalar oluştuğunda, belge anahtarının uzunluğunu azaltmak için bu işlev uygulanabilir.

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

toJson işlevi

Bu işlev bir dizeyi biçimlendirilmiş bir JSON nesnesine dönüştürür. Bu, Azure SQL gibi veri kaynağının bileşik veya hiyerarşik veri türlerini yerel olarak desteklemediği ve ardından karmaşık alanlarla eşlemediği senaryolar için kullanılabilir.

Örnek - metin içeriğini karmaşık bir alana eşleme

Dizindeki (buna karşılık olarak tanımlanmış) karmaşık bir alana eşlenmesi gereken bir JSON dizesine sahip bir SQL satırı olduğunu varsayalım; toJson işlev bunu başarmak için kullanılabilir. Örneğin, dizindeki karmaşık bir alanın aşağıdaki verilerle doldurulması gerekiyorsa:

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

Şuna benzer bir SQL satırındaki JSON dize sütununda toJson eşleme işlevi kullanılarak elde edilebilir: {"id": 5, "info": {"name": "Jane", "surname": "Smith", "skills": ["SQL", "C#", "Azure"]}, "dob": "2005-11-04T12:00:00"}.

Alan eşlemesinin aşağıda gösterildiği gibi belirtilmesi gerekir.

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

Gelişmiş alan eşleme senaryoları

Veri öbekleme veya veri bölme gibi "bire çok" belge ilişkilerine sahip olduğunuz senaryolarda, alanları üst belgelerden "alt" belgelere (parçalar) eşlemek için bu yönergeleri izleyin:

1. Üst belge dizin oluşturma atlanıyor

Üst belgelerin dizinlemesini atlıyorsanız (beceri kümesindeki projectionMode öğesini skipIndexingParentDocuments olarak ayarlayarak indexProjections), alanları üst belgelerden alt belgelere eşlemek için dizin projeksiyonlarını kullanın.

2. Hem ana hem de "alt" belgelerin dizinlemesi

Hem üst belgelerin hem de "alt" belgelerin dizinini oluştururken:

• Alanları üst belgelerle eşlemek için alan eşlemelerini kullanın.
• Alanları "alt" belgelerle eşlemek için dizin projeksiyonlarını kullanın.

3. İşlevle dönüştürülmüş değerleri üst ve/veya "alt" belgelere eşleme

Üst belgedeki bir alan dönüştürme gerektiriyorsa (kodlama gibi eşleme işlevlerini kullanarak) ve üst ve/veya "alt" belgelere eşlenmesi gerekiyorsa:

• Dizin oluşturucuda alan eşlemelerinin işlevlerini kullanarak dönüştürmeyi uygulayın.
• Dönüştürülen alanı "alt" belgelerle eşlemek için beceri kümesindeki dizin projeksiyonlarını kullanın.

Ayrıca bkz.

• Azure Yapay Zeka Arama'te desteklenen veri türleri
• SQL veri türü eşlemesi