Azure AI Search dizin oluşturucularını kullanarak alan eşlemeleri ve dönüştürmeleri

  • Makale

Indexer Stages

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 akışının her iki tarafındaki fiziksel veri yapıları (desteklenen bir veri kaynağındaki alanlar ve arama dizinindeki alanlar arasında). Bellekte bulunan beceri açısından zenginleştirilmiş içeriği içeri aktarıyorsanız, bellek içi düğümleri arama dizinindeki çıkış alanlarıyla eşlemek için outputFieldMappings kullanın.

  • Yalnızca dizinleri arayın. Bilgi deposu dolduruyorsanız veri yolu yapılandırması için projeksiyonları kullanın.

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

Not

Karmaşık verilerle (iç içe veya hiyerarşik yapılar) çalışıyorsanız ve bu veri yapısını arama dizininizde yansıtmak istiyorsanız, varsayılan eşlemelerin çalışması için arama dizininizin kaynak yapıyla tam olarak eşleşmesi gerekir (aynı alan adları, düzeyler ve türler). İ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).

Desteklenen senaryolar

Kullanım amacı Açıklama
Ad tutarsızlığı Veri kaynağınızın adlı _citybir alanı olduğunu varsayalım. Azure AI Search'in alt çizgiyle başlayan alan adlarına izin vermediği göz önünde bulundurulduğunda, alan eşlemesi "_city" ile "şehir" arasında etkili bir şekilde eşlemenizi sağlar.

Dizin oluşturma gereksinimleriniz, alan adlarının kaynaklar arasında farklılık gösterdiği birden çok veri kaynağından içerik almayı kapsıyorsa, yolu netleştirmek için bir alan eşlemesi kullanabilirsiniz.
Tür uyuşmazlığı Bir kaynak tamsayı alanının arama dizininde aranabilmesi için türünde Edm.String olmasını istediğiniz sanılır. Türler farklı olduğundan, veri yolunun başarılı olması için bir alan eşlemesi tanımlamanız gerekir. Azure AI Search'ün birçok veri kaynağından daha küçük bir desteklenen veri türü kümesine sahip olduğunu unutmayın. SQL verilerini içeri aktarıyorsanız alan eşlemesi, arama dizininde istediğiniz SQL veri türünü eşlemenizi sağlar.
Bire çok veri yolları Dizindeki birden çok alanı aynı kaynak alandaki içerikle doldurabilirsiniz. Örneğin, istemci uygulamanızdaki farklı kullanım örneklerini desteklemek için her alana farklı çözümleyiciler uygulamak isteyebilirsiniz.
Kodlama ve kod çözme Dizin oluşturma sırasında Verilerin Base64 kodlamasını veya kodunu çözmeyi desteklemek için eşleme işlevleri uygulayabilirsiniz.
Dizeleri bölme veya dizileri koleksiyonlara yeniden yansıtma Sınırlayıcı içeren bir dizeyi bölmek veya türünde Collection(Edm.String)bir arama alanına JSON dizisi göndermek için eşleme işlevleri uygulayabilirsiniz.

Alan eşlemesi tanımlama

Alan eşlemeleri, dizin oluşturucu tanımının dizisine fieldMappings eklenir. Alan eşlemesi üç bölümden oluşur.

"fieldMappings": [
  {
    "sourceFieldName": "_city",
    "targetFieldName": "city",
    "mappingFunction": null
  }
]
Özellik Açıklama
sourceFieldName Gerekli. Veri kaynağınızdaki bir alanı temsil eder.
targetFieldName isteğe bağlı. Arama dizininizdeki bir alanı temsil eder. Atlanırsa değeri sourceFieldName hedef için varsayılır. Hedef alanlar üst düzey basit alanlar veya koleksiyonlar olmalıdır. Karmaşık bir tür veya koleksiyon olamaz. Bir veri türü sorunuyla ilgileniyorsanız, dizin tanımında bir alanın veri türü belirtilir. Alan eşlemesinin yalnızca alanın adına sahip olması gerekir.
mappingFunction isteğe bağlı. Verileri dönüştüren önceden tanımlanmış işlevlerden oluşur.

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. Geçici çözüm, alan adları ve veri türleri için ham içerikle aynı olan bir dizin şeması oluşturmaktır. Örnek için bkz . Öğretici: İç içe JSON bloblarını dizine alma.

Azure AI Search, alan eşlemelerindeki alan ve işlev adlarını çözümlemek için büyük/küçük harfe duyarsız karşılaştırma kullanır. Bu kullanışlı bir işlemdir (büyük/küçük harfle ilgili tüm bilgileri almanız gerekmez), ancak veri kaynağınızın veya dizininizin yalnızca büyük/küçük harfe göre farklı alanlara sahip olmadığı anlamına gelir.

Not

Hiçbir alan eşlemesi yoksa, dizin oluşturucular veri kaynağı alanlarının aynı ada sahip dizin alanlarına eşlenmesi gerektiğini varsayar. Alan eşlemesi eklemek, kaynak ve hedef alan için varsayılan alan eşlemelerini geçersiz kılar. Blob depolama dizin oluşturucu gibi bazı dizin oluşturucular, dizin anahtarı alanı için varsayılan alan eşlemeleri ekler.

Alan eşlemelerini tanımlamak için REST API veya Azure SDK'sını kullanabilirsiniz.

Herhangi bir API sürümü olan Dizin Oluşturucu Oluştur (REST) veya Güncelleştirme Dizin Oluşturucu (REST) kullanın.

Bu örnek, alan adı tutarsızlığını işler.

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

Bu örnek, tek bir kaynak alanı birden çok hedef alanla ("bire çok" eşlemeleri) eşler. Bir alanı "çatallayabilir" ve aynı kaynak alan içeriğini dizinde farklı şekilde analiz edilecek veya özniteliklendirilecek iki farklı dizin alanına kopyalayabilirsiniz.


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

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 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=2020-06-30
{
  "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=2020-06-30
{
    "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 base64Encodetrue, HttpServerUtility.UrlTokenEncode gibi davranır ve base64Decode HttpServerUtility.UrlTokenDecode gibi davranır.

Uyarı

Anahtar değerleri üretmek için kullanılıyorsa base64Encode true useHttpServerUtilityUrlTokenEncode olarak ayarlanmalıdır. Anahtar değerleri için yalnızca URL güvenli base64 kodlaması kullanılabilir. Anahtar değerlerdeki karakterlerle ilgili tüm kısıtlamalar için bkz . Adlandırma kuralları .

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.

Kodlama Base64 kodlama çıkışı Kitaplık kodlamadan sonra ek işleme Kitaplık kodunu çözmeden önce ek işleme
Doldurmalı Base64 MDA+MDA/MDA= URL güvenli karakterler kullanma ve doldurmayı kaldırma Standart base64 karakterlerini kullanma ve doldurma ekleme
Doldurma olmadan Base64 MDA+MDA/MDA URL güvenli karakterler kullanma Standart base64 karakter kullanma
Doldurma ile URL güvenli base64 MDA-MDA_MDA= Doldurmayı kaldırma Doldurma ekleme
Doldurma olmadan URL güvenli base64 MDA-MDA_MDA Hiçbiri Hiçbiri

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

Ayrıca bkz.