Mapowania pól i przekształcenia przy użyciu indeksatorów usługi Azure AI Search
Gdy indeksator usługi Azure AI Search ładuje indeks wyszukiwania, określa ścieżkę danych przy użyciu mapowań pól źródła do miejsca docelowego. Niejawne mapowania pól są wewnętrzne i występują, gdy nazwy pól i typy danych są zgodne między źródłem i miejscem docelowym. Jeśli dane wejściowe i wyjściowe nie są zgodne, możesz zdefiniować jawne mapowania pól w celu skonfigurowania ścieżki danych zgodnie z opisem w tym artykule.
Mapowania pól mogą być również używane do konwersji danych o lekkiej wadze, takich jak kodowanie lub dekodowanie, za pomocą funkcji mapowania. Jeśli wymagane jest więcej przetwarzania, rozważ usługę Azure Data Factory , aby wypełnić lukę.
Mapowania pól mają zastosowanie do:
Fizyczne struktury danych po obu stronach strumienia danych (między polami w obsługiwanym źródle danych i polach w indeksie wyszukiwania). Jeśli importujesz wzbogaconą umiejętności zawartość, która znajduje się w pamięci, użyj parametrów outputFieldMappings do mapowania węzłów w pamięci na pola wyjściowe w indeksie wyszukiwania.
Wyszukaj tylko indeksy. Jeśli wypełniasz magazyn wiedzy, użyj projekcji do konfiguracji ścieżki danych.
Tylko pola wyszukiwania najwyższego poziomu, w których
targetFieldName
pole jest prostym polem lub kolekcją. Pole docelowe nie może być typem złożonym.
Uwaga
Jeśli pracujesz z złożonymi danymi (zagnieżdżonym lub hierarchicznymi strukturami), a chcesz dublować tę strukturę danych w indeksie wyszukiwania, indeks wyszukiwania musi dokładnie odpowiadać strukturze źródłowej (takie same nazwy pól, poziomy i typy), aby domyślne mapowania działały. Opcjonalnie możesz chcieć mieć tylko kilka węzłów w złożonej strukturze. Aby uzyskać poszczególne węzły, można spłaszczać dane przychodzące do kolekcji ciągów (zobacz outputFieldMappings , aby uzyskać to obejście).
Obsługiwane scenariusze
Przypadek użycia | opis |
---|---|
Rozbieżność nazw | Załóżmy, że źródło danych ma pole o nazwie _city . Biorąc pod uwagę, że usługa Azure AI Search nie zezwala na nazwy pól rozpoczynających się od podkreślenia, mapowanie pól umożliwia efektywne mapowanie wartości "_city" na "miasto". Jeśli wymagania dotyczące indeksowania obejmują pobieranie zawartości z wielu źródeł danych, gdzie nazwy pól różnią się między źródłami, możesz użyć mapowania pól, aby wyjaśnić ścieżkę. |
Rozbieżność typów | Załóżmy, że chcesz, aby pole źródłowej liczby całkowitej było typu Edm.String , aby można je było przeszukiwać w indeksie wyszukiwania. Ponieważ typy są różne, należy zdefiniować mapowanie pól, aby ścieżka danych powiodła się. Pamiętaj, że usługa Azure AI Search ma mniejszy zestaw obsługiwanych typów danych niż wiele źródeł danych. Jeśli importujesz dane SQL, mapowanie pól umożliwia mapowanie żądanego typu danych SQL w indeksie wyszukiwania. |
Ścieżki danych jeden do wielu | W indeksie można wypełnić wiele pól zawartością z tego samego pola źródłowego. Na przykład możesz zastosować różne analizatory do każdego pola, aby obsługiwać różne przypadki użycia w aplikacji klienckiej. |
Kodowanie i dekodowanie | Funkcje mapowania można stosować do obsługi kodowania lub dekodowania danych base64 podczas indeksowania. |
Dzielenie ciągów lub reemisji tablic na kolekcje | Możesz zastosować funkcje mapowania, aby podzielić ciąg zawierający ogranicznik lub wysłać tablicę JSON do pola wyszukiwania typu Collection(Edm.String) . |
Definiowanie mapowania pól
Mapowania pól są dodawane do fieldMappings
tablicy definicji indeksatora. Mapowanie pól składa się z trzech części.
"fieldMappings": [
{
"sourceFieldName": "_city",
"targetFieldName": "city",
"mappingFunction": null
}
]
Właściwości | opis |
---|---|
sourceFieldName | Wymagany. Reprezentuje pole w źródle danych. |
targetFieldName | Opcjonalny. Reprezentuje pole w indeksie wyszukiwania. Jeśli pominięto, przyjmuje się, że wartość parametru sourceFieldName jest przyjmowana dla elementu docelowego. Pola docelowe muszą być prostymi polami lub kolekcjami najwyższego poziomu. Nie może to być typ złożony ani kolekcja. Jeśli obsługujesz problem z typem danych, typ danych pola jest określony w definicji indeksu. Mapowanie pól musi mieć tylko nazwę pola. |
mappingFunction | Opcjonalny. Składa się ze wstępnie zdefiniowanych funkcji , które przekształcają dane. |
Jeśli wystąpi błąd podobny do "Field mapping specifies target field 'Address/city' that doesn't exist in the index"
, jest to spowodowane tym, że mapowania pól docelowych nie mogą być typem złożonym. Obejście polega na utworzeniu schematu indeksu, który jest identyczny z nieprzetworzonej zawartości dla nazw pól i typów danych. Zobacz Samouczek: zagnieżdżone obiekty blob JSON indeksu , aby zapoznać się z przykładem.
Usługa Azure AI Search używa porównania bez uwzględniania wielkości liter, aby rozpoznawać nazwy pól i funkcji w mapowaniach pól. Jest to wygodne (nie trzeba pobierać całej wielkości liter w prawo), ale oznacza to, że źródło danych lub indeks nie mogą mieć pól, które różnią się tylko wielkością liter.
Uwaga
Jeśli żadne mapowania pól nie są obecne, indeksatory zakładają, że pola źródła danych powinny być mapowane na pola indeksu o tej samej nazwie. Dodanie mapowania pól zastępuje domyślne mapowania pól dla pola źródłowego i docelowego. Niektóre indeksatory, takie jak indeksator magazynu obiektów blob, dodają domyślne mapowania pól dla pola klucza indeksu.
Do definiowania mapowań pól można użyć interfejsu API REST lub zestawu Azure SDK.
Użyj polecenia Create Indexer (REST) lub Update Indexer (REST), dowolnej wersji interfejsu API.
W tym przykładzie jest obsługiwana rozbieżność nazwy pola.
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" } ]
}
W tym przykładzie mapuje jedno pole źródłowe na wiele pól docelowych ("mapowania jeden do wielu"). Możesz "rozwidlić" pole, kopiując tę samą zawartość pola źródłowego do dwóch różnych pól indeksu, które będą analizowane lub przypisywane inaczej w indeksie.
"fieldMappings" : [
{ "sourceFieldName" : "text", "targetFieldName" : "textStandardEnglishAnalyzer" },
{ "sourceFieldName" : "text", "targetFieldName" : "textSoundexAnalyzer" }
]
Funkcje mapowania i przykłady
Funkcja mapowania pól przekształca zawartość pola przed zapisaniem go w indeksie. Obecnie obsługiwane są następujące funkcje mapowania:
base64Encode, funkcja
Wykonuje bezpieczne kodowanie base64 w adresie URL ciągu wejściowego. Przyjęto założenie, że dane wejściowe są zakodowane w formacie UTF-8.
Przykład: kodowanie podstawowe klucza dokumentu
Tylko bezpieczne znaki URL mogą być wyświetlane w kluczu dokumentu usługi Azure AI Search (dzięki czemu można adresować dokument przy użyciu interfejsu API wyszukiwania). Jeśli pole źródłowe klucza zawiera niebezpieczne znaki adresu URL, takie jak -
i \
, użyj base64Encode
funkcji , aby przekonwertować je w czasie indeksowania.
W poniższym przykładzie określono funkcję base64Encode, metadata_storage_name
aby obsługiwać nieobsługiwane znaki.
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 }
}
}
]
}
Klucz dokumentu (zarówno przed konwersją, jak i po konwersji) nie może być dłuższy niż 1024 znaki. Po pobraniu zakodowanego klucza w czasie wyszukiwania użyj base64Decode
funkcji , aby pobrać oryginalną wartość klucza i użyć go do pobrania dokumentu źródłowego.
Przykład: Tworzenie pola zakodowanego w formacie podstawowym "z możliwością wyszukiwania"
Czasami trzeba użyć zakodowanej wersji pola, takiej jak metadata_storage_path
klucz, ale także wersję niekodowaną do wyszukiwania pełnotekstowego. Aby obsługiwać oba scenariusze, można mapować metadata_storage_path
na dwa pola: jeden dla klucza (zakodowanego), a drugi dla pola ścieżki, które możemy założyć, jest przypisywany jako searchable
w schemacie indeksu.
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" }
]
}
Przykład — zachowywanie oryginalnych wartości
Indeksator magazynu obiektów blob automatycznie dodaje mapowanie pól z metadata_storage_path
, identyfikator URI obiektu blob do pola klucza indeksu, jeśli nie określono żadnego mapowania pól. Ta wartość jest zakodowana w formacie Base64, więc można jej używać jako klucza dokumentu usługi Azure AI Search. W poniższym przykładzie pokazano, jak jednocześnie mapować bezpieczną wersję base64 zakodowaną w adresie URL na index_key
pole i zachować oryginalną metadata_storage_path
wartość w metadata_storage_path
polu:
"fieldMappings": [
{
"sourceFieldName": "metadata_storage_path",
"targetFieldName": "metadata_storage_path"
},
{
"sourceFieldName": "metadata_storage_path",
"targetFieldName": "index_key",
"mappingFunction": {
"name": "base64Encode"
}
}
]
Jeśli nie dołączysz właściwości parameters dla funkcji mapowania, wartość domyślna to {"useHttpServerUtilityUrlTokenEncode" : true}
.
Usługa Azure AI Search obsługuje dwa różne kodowania Base64. Te same parametry należy użyć podczas kodowania i dekodowania tego samego pola. Aby uzyskać więcej informacji, zobacz opcje kodowania base64, aby zdecydować, które parametry mają być używane.
base64Decode, funkcja
Wykonuje dekodowanie Base64 ciągu wejściowego. Przyjmuje się, że dane wejściowe są ciągiem zakodowanym w formacie Base64 bezpiecznym pod adresem URL.
Przykład — dekodowanie metadanych lub adresów URL obiektów blob
Dane źródłowe mogą zawierać ciągi zakodowane w formacie Base64, takie jak ciągi metadanych obiektu blob lub adresy URL sieci Web, które mają być wyszukiwalne jako zwykły tekst. Za pomocą base64Decode
funkcji można przekształcić zakodowane dane z powrotem w zwykłe ciągi podczas wypełniania indeksu wyszukiwania.
"fieldMappings" : [
{
"sourceFieldName" : "Base64EncodedMetadata",
"targetFieldName" : "SearchableMetadata",
"mappingFunction" : {
"name" : "base64Decode",
"parameters" : { "useHttpServerUtilityUrlTokenDecode" : false }
}
}
]
Jeśli nie dołączysz właściwości parameters, wartość domyślna to {"useHttpServerUtilityUrlTokenEncode" : true}
.
Usługa Azure AI Search obsługuje dwa różne kodowania Base64. Te same parametry należy użyć podczas kodowania i dekodowania tego samego pola. Aby uzyskać więcej informacji, zobacz opcje kodowania base64, aby zdecydować, które parametry mają być używane.
Opcje kodowania base64
Usługa Azure AI Search obsługuje kodowanie base64 bezpieczne pod adresem URL i normalne kodowanie base64. Ciąg zakodowany w formacie base64 podczas indeksowania powinien zostać zdekodowany później z tymi samymi opcjami kodowania lub wynik nie będzie zgodny z oryginałem.
useHttpServerUtilityUrlTokenEncode
Jeśli odpowiednio ustawiono true
parametry lub useHttpServerUtilityUrlTokenDecode
kodowania i dekodowania na wartość , base64Encode
zachowuje się tak jak HttpServerUtility.UrlTokenEncode i base64Decode
zachowuje się jak HttpServerUtility.UrlTokenDecode.
Ostrzeżenie
Jeśli base64Encode
jest używany do tworzenia wartości klucza, useHttpServerUtilityUrlTokenEncode
należy ustawić wartość true. W przypadku wartości kluczy można używać tylko kodowania base64 bezpiecznego pod kątem adresu URL. Zobacz Reguły nazewnictwa, aby uzyskać pełny zestaw ograniczeń dotyczących znaków w wartościach klucza.
Biblioteki .NET w usłudze Azure AI Search zakładają, że pełny program .NET Framework zapewnia wbudowane kodowanie. Opcje useHttpServerUtilityUrlTokenEncode
i useHttpServerUtilityUrlTokenDecode
stosują tę wbudowaną funkcjonalność. Jeśli używasz platformy .NET Core lub innej platformy, zalecamy bezpośrednie ustawienie tych opcji na false
funkcje kodowania i dekodowania struktury oraz wywoływanie ich bezpośrednio.
W poniższej tabeli porównaliśmy różne kodowania base64 ciągu 00>00?00
. Aby określić wymagane przetwarzanie (jeśli istnieje) dla funkcji base64, zastosuj funkcję kodowania biblioteki w ciągu 00>00?00
i porównaj dane wyjściowe z oczekiwanymi danymi wyjściowymi MDA-MDA_MDA
.
Kodowanie | Dane wyjściowe kodowania base64 | Dodatkowe przetwarzanie po kodowaniu biblioteki | Dodatkowe przetwarzanie przed dekodowaniem biblioteki |
---|---|---|---|
Base64 z dopełnieniem | MDA+MDA/MDA= |
Użyj znaków bezpiecznych adresów URL i usuń dopełnienie | Użyj standardowych znaków base64 i dodaj dopełnienie |
Base64 bez dopełnienia | MDA+MDA/MDA |
Używanie znaków bezpiecznych adresów URL | Używanie standardowych znaków base64 |
Bezpieczny adres URL base64 z dopełniniem | MDA-MDA_MDA= |
Usuń dopełnienie | Dodaj dopełnienie |
Bezpieczny adres URL base64 bez dopełnienia | MDA-MDA_MDA |
Brak | Brak |
extractTokenAtPosition, funkcja
Dzieli pole ciągu przy użyciu określonego ogranicznika i wybiera token na określonej pozycji w wynikowym podziale.
Ta funkcja używa następujących parametrów:
delimiter
: ciąg, który ma być używany jako separator podczas dzielenia ciągu wejściowego.position
: położenie tokenu opartego na liczbą całkowitą, która ma być wybrana po podzieleniu ciągu wejściowego.
Jeśli na przykład dane wejściowe to Jane Doe
, wartość to " "
(spacja), a position
wartość to 0, wynik to Jane
; jeśli position
wartość to 1, wynik to Doe
delimiter
. Jeśli pozycja odwołuje się do tokenu, który nie istnieje, zwracany jest błąd.
Przykład — wyodrębnianie nazwy
Źródło danych zawiera PersonName
pole i chcesz je zaindeksować jako dwa oddzielne FirstName
i LastName
pola. Za pomocą tej funkcji można podzielić dane wejściowe przy użyciu znaku spacji jako ogranicznika.
"fieldMappings" : [
{
"sourceFieldName" : "PersonName",
"targetFieldName" : "FirstName",
"mappingFunction" : { "name" : "extractTokenAtPosition", "parameters" : { "delimiter" : " ", "position" : 0 } }
},
{
"sourceFieldName" : "PersonName",
"targetFieldName" : "LastName",
"mappingFunction" : { "name" : "extractTokenAtPosition", "parameters" : { "delimiter" : " ", "position" : 1 } }
}]
jsonArrayToStringCollection, funkcja
Przekształca ciąg sformatowany jako tablica JSON ciągów w tablicę ciągów, która może służyć do wypełniania Collection(Edm.String)
pola w indeksie.
Jeśli na przykład ciąg wejściowy to ["red", "white", "blue"]
, pole docelowe typu Collection(Edm.String)
zostanie wypełnione trzema wartościami red
, white
i blue
. W przypadku wartości wejściowych, których nie można przeanalizować jako tablic ciągów JSON, zwracany jest błąd.
Przykład — wypełnianie kolekcji z danych relacyjnych
Usługa Azure SQL Database nie ma wbudowanego typu danych, który naturalnie mapuje je na Collection(Edm.String)
pola w usłudze Azure AI Search. Aby wypełnić pola kolekcji ciągów, możesz wstępnie przetworzyć dane źródłowe jako tablicę ciągów JSON, a następnie użyć jsonArrayToStringCollection
funkcji mapowania.
"fieldMappings" : [
{
"sourceFieldName" : "tags",
"mappingFunction" : { "name" : "jsonArrayToStringCollection" }
}]
urlEncode, funkcja
Ta funkcja może służyć do kodowania ciągu, aby był "bezpieczny adres URL". W przypadku użycia z ciągiem zawierającym znaki, które nie są dozwolone w adresie URL, ta funkcja konwertuje te znaki "niebezpieczne" na odpowiedniki jednostek znaków. Ta funkcja używa formatu kodowania UTF-8.
Przykład — wyszukiwanie klucza dokumentu
urlEncode
funkcji można użyć jako alternatywy dla base64Encode
funkcji, jeśli tylko niebezpieczne znaki adresu URL mają być konwertowane, zachowując inne znaki zgodnie z rzeczywistym użyciem.
Załóżmy, że ciąg wejściowy to <hello>
— następnie pole docelowe typu (Edm.String)
zostanie wypełnione wartością %3chello%3e
Po pobraniu zakodowanego klucza w czasie wyszukiwania możesz użyć urlDecode
funkcji , aby uzyskać oryginalną wartość klucza i użyć go do pobrania dokumentu źródłowego.
"fieldMappings" : [
{
"sourceFieldName" : "SourceKey",
"targetFieldName" : "IndexKey",
"mappingFunction" : {
"name" : "urlEncode"
}
}
]
urlDecode, funkcja
Ta funkcja konwertuje ciąg zakodowany pod adresem URL na ciąg dekodowany przy użyciu formatu kodowania UTF-8.
Przykład — dekodowanie metadanych obiektu blob
Niektórzy klienci usługi Azure Storage automatycznie kodują metadane obiektów blob za pomocą adresu URL, jeśli zawierają znaki inne niż ASCII. Jeśli jednak chcesz, aby takie metadane były wyszukiwane (jako zwykły tekst), możesz użyć urlDecode
funkcji , aby przekształcić zakodowane dane z powrotem w zwykłe ciągi podczas wypełniania indeksu wyszukiwania.
"fieldMappings" : [
{
"sourceFieldName" : "UrlEncodedMetadata",
"targetFieldName" : "SearchableMetadata",
"mappingFunction" : {
"name" : "urlDecode"
}
}
]
fixedLengthEncode, funkcja
Ta funkcja konwertuje ciąg o dowolnej długości na ciąg o stałej długości.
Przykład — mapowanie kluczy dokumentów, które są za długie
Jeśli wystąpią błędy związane z długością klucza dokumentu przekraczającego 1024 znaki, można zastosować tę funkcję w celu zmniejszenia długości klucza dokumentu.
"fieldMappings" : [
{
"sourceFieldName" : "metadata_storage_path",
"targetFieldName" : "your key field",
"mappingFunction" : {
"name" : "fixedLengthEncode"
}
}
]
toJson, funkcja
Ta funkcja konwertuje ciąg na sformatowany obiekt JSON. Może to być używane w scenariuszach, w których źródło danych, takie jak Azure SQL, nie obsługuje natywnie złożonych lub hierarchicznych typów danych, a następnie mapuje je na złożone pola.
Przykład — mapowanie zawartości tekstowej na złożone pole
Załóżmy, że istnieje wiersz SQL z ciągiem JSON, który musi zostać zamapowany na (odpowiednio zdefiniowane) pole złożone w indeksie, toJson
funkcja może służyć do osiągnięcia tego celu. Jeśli na przykład należy wypełnić złożone pole w indeksie następującymi danymi:
{
"id": "5",
"info": {
"name": "Jane",
"surname": "Smith",
"skills": [
"SQL",
"C#",
"Azure"
],
"dob": "2005-11-04T12:00:00"
}
}
Można to osiągnąć za pomocą toJson
funkcji mapowania w kolumnie ciągu JSON w wierszu SQL, który wygląda następująco: {"id": 5, "info": {"name": "Jane", "surname": "Smith", "skills": ["SQL", "C#", "Azure"]}, "dob": "2005-11-04T12:00:00"}
.
Mapowanie pól należy określić, jak pokazano poniżej.
"fieldMappings" : [
{
"sourceFieldName" : "content",
"targetFieldName" : "complexField",
"mappingFunction" : {
"name" : "toJson"
}
}
]