Azure AI Search dizin oluşturucularını kullanarak 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 AI Search dizin oluşturucu bir arama dizinini 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'yi 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 üst 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 bkz . Öğretici: Dizin iç içe JSON blobları örneği. 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).

Alan eşlemesi tanımlama

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
• jsonArrayToStringCollection
• 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 AI Search belge anahtarında yalnızca URL güvenli karakterler görüntülenebilir (böylece arama API'sini kullanarak belgeyi ele alabilirsiniz). Anahtarınızın kaynak alanında ve \gibi - URL'nin güvenli olmayan karakterleri varsa, dizin oluşturma zamanında dönüştürmek için işlevini kullanınbase64Encode.

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

PUT /indexers?api-version=2024-07-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. Kodlanmış anahtarı arama zamanında aldığınızda, base64Decode özgün anahtar değerini almak için işlevini kullanın ve kaynak belgeyi almak için bunu kullanın.

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

Bir alanın anahtar gibi metadata_storage_path kodlanmış bir sürümünü kullanmanız 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 iki alana eşleyebilirsiniz metadata_storage_path : biri anahtar için (kodlanmış) ve diğeri de dizin şemasında olduğu gibi searchable özniteliklendirildiğini varsaydığımız bir yol alanı için.

PUT /indexers/blob-indexer?api-version=2024-07-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 AI Search 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 olarak değerine sahip {"useHttpServerUtilityUrlTokenEncode" : true}olur.

Azure AI Search 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 AI Search 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 AI Search, 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.

useHttpServerUtilityUrlTokenEncode Sırasıyla kodlama ve kod çözme için veya useHttpServerUtilityUrlTokenDecode parametreleri olarak ayarlanırsa base64Encode true, HttpServerUtility.UrlTokenEncode gibi davranır ve base64Decode HttpServerUtility.UrlTokenDecode gibi davranır.

Azure AI Search'teki .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ş ise Jane Doe, " "delimiter (boşluk) ve position 0 ise, sonuç olurJane; 1 ise position sonuç olurDoe. Konum varolmayan bir belirteçe başvuruyorsa bir hata döndürülür.

Örnek - ad ayıklama

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 ise["red", "white", "blue"], türündeki Collection(Edm.String) hedef alan , whiteve blueolmak üzere üç değerle reddoldurulur. JSON dize dizileri olarak ayrıştırılabilen giriş değerleri için bir hata döndürülür.

Örnek - ilişkisel verilerden toplamayı doldurma

Azure SQL Veritabanı, Azure AI Search'teki alanlarla Collection(Edm.String) 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, yalnızca URL güvenli olmayan karakterlerin dönüştürülmesi ve diğer karakterlerin base64Encode olduğu gibi tutulması durumunda işleve alternatif olarak kullanılabilir.

Ö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 işlevini ve urlDecode kaynak belgeyi almak için bunu kullanabilirsiniz.

"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 ile 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şlediğ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 eşleme işlevi kullanılarak toJson 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 bölme gibi "bire çok" belge ilişkilerine sahip olduğunuz senaryolarda, alanları üst belgelerden "alt" belgelere (öbekler) eşlemek için bu yönergeleri izleyin:

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

Üst belgelerin dizinini atlarsanız (beceri kümesinde olarak ayarlayarak projectionMode skipIndexingParentDocuments), alanları üst belgelerden "alt" belgelere eşlemek için dizin projeksiyonlarını kullanın.indexProjections

2. Hem üst hem de "alt" belgelerin dizinini oluşturma

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. İşlev dönüştürülen değerleri üst ve/veya "alt" belgelerle 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 AI Search'te desteklenen veri türleri
• SQL veri türü eşlemesi