Mapowania pól i przekształcenia przy użyciu indeksatorów usługi Azure AI Search

  • Artykuł

Indexer Stages

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 trueparametry 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 Doedelimiter . 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, whitei 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"
    }
  }
]

Zobacz też