Mapowania pól i przekształcenia przy użyciu indeksatorów usługi Azure AI Search
W tym artykule wyjaśniono, jak ustawić jawne mapowania pól, które ustanawiają ścieżkę danych między polami źródłowymi w obsługiwanym źródle danych i polami docelowymi w indeksie wyszukiwania.
Kiedy ustawić mapowanie pól
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 ścieżki danych. Logiczne struktury danych utworzone przez umiejętności znajdują się tylko w pamięci. Użyj elementów outputFieldMappings, aby mapować węzły w pamięci na pola wyjściowe w indeksie wyszukiwania.
Tylko nadrzędne indeksy wyszukiwania sztucznej inteligencji. W przypadku indeksów pomocniczych z dokumentami podrzędnymi lub "fragmentami" zapoznaj się z zaawansowanymi scenariuszami mapowania pól.
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.
Obsługiwane scenariusze
Upewnij się, że używasz obsługiwanego źródła danych do indeksowania indeksatora.
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) . |
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, automatycznie dodają domyślne mapowania pól dla pola klucza indeksu.
Pola złożone nie są obsługiwane w mapowaniu pól. Struktura źródłowa (zagnieżdżone lub hierarchiczne struktury) musi dokładnie odpowiadać typowi złożonemu w indeksie, aby domyślne mapowania działały. Aby uzyskać więcej informacji, zobacz Samouczek: zagnieżdżone obiekty blob JSON indeksu na przykład. 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.
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).
Definiowanie mapowania pól
W tej sekcji opisano kroki konfigurowania mapowań pól.
Użyj metody Create Indexer lub Create lub Update Indexer lub równoważnej metody w zestawie Azure SDK. Oto przykład definicji indeksatora.
{ "name": "myindexer", "description": null, "dataSourceName": "mydatasource", "targetIndexName": "myindex", "schedule": { }, "parameters": { }, "fieldMappings": [], "disabled": false, "encryptionKey": { } }
Wypełnij tablicę,
fieldMappings
aby określić mapowania. 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.
Przykład: rozbieżność nazwy lub typu
Jawne mapowanie pól ustanawia ścieżkę danych dla przypadków, w których nazwa i typ nie są identyczne.
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.
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" } ]
}
Przykład: ścieżki danych typu jeden do wielu lub rozwidlenia
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" }
]
Możesz użyć podobnego podejścia do zawartości wygenerowanej przez umiejętności.
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:
Należy pamiętać, że te funkcje są obecnie obsługiwane wyłącznie dla indeksów nadrzędnych. Nie są one zgodne z mapowaniem indeksu fragmentowanego, dlatego te funkcje nie mogą być używane na potrzeby projekcji indeksów.
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=2024-07-01
{
"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=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" }
]
}
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"
}
}
]
Zaawansowane scenariusze mapowania pól
W scenariuszach, w których istnieją relacje dokumentów "jeden do wielu", takie jak fragmentowanie lub dzielenie danych, postępuj zgodnie z tymi wytycznymi dotyczącymi mapowania pól z dokumentów nadrzędnych na "podrzędne" dokumenty (fragmenty):
1. Pomijanie indeksowania dokumentów nadrzędnych
Jeśli pomijasz indeksowanie dokumentów nadrzędnych (przez ustawienie projectionMode
na skipIndexingParentDocuments
wartość w zestawie indexProjections
umiejętności), użyj projekcji indeksu do mapowania pól z dokumentów nadrzędnych na dokumenty podrzędne .
2. Indeksowanie dokumentów nadrzędnych i "podrzędnych"
Jeśli indeksujesz zarówno dokumenty nadrzędne, jak i dokumenty podrzędne:
- Mapowania pól umożliwiają mapowanie pól na dokumenty nadrzędne.
- Projekcje indeksu umożliwiają mapowanie pól na dokumenty podrzędne.
3. Mapowanie wartości przekształconych przez funkcję na dokumenty nadrzędne i/lub "podrzędne"
Jeśli pole w dokumencie nadrzędnym wymaga przekształcenia (przy użyciu funkcji mapowania, takich jak kodowanie) i musi zostać zamapowane na dokumenty nadrzędne i/lub "podrzędne":
- Zastosuj transformację przy użyciu funkcji mapowań pól w indeksatorze.
- Projekcje indeksu w zestawie umiejętności umożliwiają mapowanie przekształconego pola na dokumenty "podrzędne".