Indeksowanie danych z usługi Azure Table Storage

W tym artykule dowiesz się, jak skonfigurować indeksator , który importuje zawartość z usługi Azure Table Storage i umożliwia wyszukiwanie w usłudze Azure AI Search. Dane wejściowe indeksatora to jednostki w jednej tabeli. Dane wyjściowe to indeks wyszukiwania z zawartością z możliwością wyszukiwania i metadanymi przechowywanymi w poszczególnych polach.

Ten artykuł uzupełnia tworzenie indeksatora z informacjami specyficznymi dla indeksowania z usługi Azure Table Storage. Używa ona witryny Azure Portal i interfejsów API REST, aby zademonstrować trzyczęściowy przepływ pracy wspólny dla wszystkich indeksatorów: tworzenie źródła danych, tworzenie indeksu, tworzenie indeksatora. Wyodrębnianie danych odbywa się podczas przesyłania żądania Tworzenia indeksatora.

Wymagania wstępne

• Azure Table Storage

• Tabele zawierające tekst. Jeśli masz dane binarne, rozważ wzbogacanie sztucznej inteligencji na potrzeby analizy obrazów.

• Uprawnienia do odczytu w usłudze Azure Storage. Parametry połączenia "pełny dostęp" zawiera klucz, który zapewnia dostęp do zawartości, ale jeśli używasz ról platformy Azure, upewnij się, że tożsamość zarządzana usługi wyszukiwania ma uprawnienia Czytelnik i Dostęp do danych.

Aby pracować z przykładami w tym artykule, potrzebujesz witryny Azure Portal lub klienta REST. Jeśli używasz witryny Azure Portal, upewnij się, że dostęp do wszystkich sieci publicznych jest włączony. Inne podejścia do tworzenia indeksatora tabel platformy Azure obejmują zestawy AZURE SDK.

Wypróbuj przykładowe dane

Skorzystaj z tych instrukcji, aby utworzyć tabelę w usłudze Azure Storage na potrzeby testowania.

1. Zaloguj się do witryny Azure Portal, przejdź do konta magazynu i utwórz tabelę o nazwie hotels.

2. Zainstaluj Eksplorator usługi Azure Storage.

3. Pobierz HotelsData_toAzureSearch.csv z usługi GitHub. Ten plik jest podzbiorem wbudowanego przykładowego zestawu danych hoteli. Pomija kolekcję pokoi, przetłumaczone opisy i współrzędne geograficzne.

4. W Eksplorator usługi Azure Storage zaloguj się do platformy Azure, wybierz swoją subskrypcję, a następnie wybierz konto magazynu.

5. Otwórz tabele i wybierz hotele.

6. Wybierz pozycję Importuj na pasku poleceń, a następnie wybierz plik HotelsData_toAzureSearch.csv .

7. Zaakceptuj wartości domyślne. Wybierz pozycję Importuj , aby załadować dane.

W tabeli powinny znajdować się 50 rekordów hotelowych z automatycznie wygenerowanym kluczem partycji, kluczem wiersza i sygnaturą czasową. Teraz możesz używać tej zawartości do indeksowania w witrynie Azure Portal, kliencie REST lub zestawie Azure SDK.

Pole Opis zawiera najbardziej szczegółową zawartość. To pole powinno być przeznaczone dla wyszukiwania pełnotekstowego i opcjonalnych zapytań wektorowych.

Korzystanie z witryny Azure Portal

Możesz użyć Kreatora importu danych lub Kreatora importowania i wektoryzacji danych, aby zautomatyzować indeksowanie z tabeli lub widoku bazy danych SQL. Konfiguracja źródła danych jest podobna dla obu kreatorów.

1. Uruchom kreator.

2. Na stronie Połącz z danymi wybierz lub sprawdź, czy typ źródła danych to Azure Table Storage lub czy pola wyboru danych wyświetlają monit o tabele.

   Nazwa źródła danych odnosi się do obiektu połączenia źródła danych w usłudze Azure AI Search. Jeśli używasz kreatora wektorów, nazwa źródła danych jest generowana automatycznie przy użyciu niestandardowego prefiksu określonego na końcu przepływu pracy kreatora.

3. Określ nazwę konta magazynu i tabeli. Zapytanie jest opcjonalne. Jest to przydatne, jeśli masz określone kolumny, które chcesz zaimportować.

4. Określ metodę uwierzytelniania , tożsamość zarządzaną lub wbudowany klucz interfejsu API. Jeśli nie określisz połączenia tożsamości zarządzanej, w witrynie Azure Portal jest używany klucz.

   Jeśli skonfigurujesz usługę Azure AI Search do używania tożsamości zarządzanej i utworzysz przypisanie roli w usłudze Azure Storage, które przyznaje uprawnienia Czytelnik i Dostęp do danych tożsamości, indeksator może nawiązać połączenie z magazynem tabel przy użyciu identyfikatora i ról firmy Microsoft.

5. W przypadku kreatora importowania i wektoryzacji danych można określić opcje wykrywania usuwania,

   Wykrywanie usuwania wymaga wstępnie istniejącego pola w tabeli, które może być używane jako flaga usuwania nietrwałego. Powinno to być pole logiczne (można nazwać je IsDeleted). Określ true jako wartość usuwania nietrwałego. W indeksie wyszukiwania dodaj odpowiednie pole wyszukiwania o nazwie IsDeleted ustawione na pobieranie i filtrowanie.

6. Przejdź do pozostałych kroków, aby ukończyć pracę kreatora:

   • Szybki start: Kreator importowania danych

   • Szybki start: kreator importowania i wektoryzacji danych

Korzystanie z interfejsów API REST

W tej sekcji przedstawiono wywołania interfejsu API REST, które tworzą źródło danych, indeks i indeksator.

Definiowanie źródła danych

Definicja źródła danych określa dane źródłowe do indeksowania, poświadczeń i zasad wykrywania zmian. Źródło danych to niezależny zasób, który może być używany przez wiele indeksatorów.

1. Utwórz lub zaktualizuj źródło danych, aby ustawić jego definicję:

    POST https://[service name].search.windows.net/datasources?api-version=2024-07-01 
    {
        "name": "my-table-storage-ds",
        "description": null,
        "type": "azuretable",
        "subtype": null,
        "credentials": {
           "connectionString": "DefaultEndpointsProtocol=https;AccountName=<account name>"
        },
        "container": {
           "name": "my-table-in-azure-storage",
           "query": ""
        },
        "dataChangeDetectionPolicy": null,
        "dataDeletionDetectionPolicy": null,
        "encryptionKey": null,
        "identity": null
    }
   

2. Ustaw wartość "type" na "azuretable" (wymagane).

3. Ustaw wartość "credentials" na parametry połączenia usługi Azure Storage. W następnej sekcji opisano obsługiwane formaty.

4. Ustaw wartość "container" na nazwę tabeli.

5. Opcjonalnie ustaw wartość "query" na filtr PartitionKey. Ustawienie tej właściwości jest najlepszym rozwiązaniem, które poprawia wydajność. Jeśli "zapytanie" ma wartość null, indeksator wykonuje pełne skanowanie tabeli, co może spowodować niską wydajność, jeśli tabele są duże.

Definicja źródła danych może również obejmować zasady usuwania nietrwałego, jeśli indeksator ma usunąć dokument wyszukiwania, gdy dokument źródłowy jest oflagowany do usunięcia.

Obsługiwane poświadczenia i parametry połączenia

Indeksatory mogą łączyć się z tabelą przy użyciu następujących połączeń.

Partycja w celu zwiększenia wydajności

Domyślnie usługa Azure AI Search używa następującego wewnętrznego filtru zapytań, aby śledzić, które jednostki źródłowe zostały zaktualizowane od ostatniego uruchomienia: Timestamp >= HighWaterMarkValue. Ponieważ tabele platformy Azure nie mają indeksu pomocniczego w Timestamp polu, ten typ zapytania wymaga pełnego skanowania tabeli i dlatego jest powolny dla dużych tabel.

Aby uniknąć pełnego skanowania, można użyć partycji tabeli, aby zawęzić zakres każdego zadania indeksatora.

• Jeśli dane mogą być naturalnie podzielone na kilka zakresów partycji, utwórz źródło danych i odpowiedni indeksator dla każdego zakresu partycji. Każdy indeksator musi teraz przetwarzać tylko określony zakres partycji, co skutkuje lepszą wydajnością zapytań. Jeśli dane, które należy indeksować, mają niewielką liczbę stałych partycji, jeszcze lepiej: każdy indeksator wykonuje tylko skanowanie partycji.

  Aby na przykład utworzyć źródło danych do przetwarzania zakresu partycji z kluczami z 000 do 100, użyj zapytania w następujący sposób: "container" : { "name" : "my-table", "query" : "PartitionKey ge '000' and PartitionKey lt '100' " }

• Jeśli dane są partycjonowane według czasu (na przykład jeśli tworzysz nową partycję codziennie lub tydzień), rozważ następujące podejście:

  • W definicji źródła danych określ zapytanie podobne do następującego przykładu: (PartitionKey ge <TimeStamp>) and (other filters).

  • Monitoruj postęp indeksatora przy użyciu interfejsu API pobierania stanu indeksatora i okresowo aktualizuj <TimeStamp> stan zapytania na podstawie najnowszej pomyślnej wartości znacznika wysokiego poziomu.

  • W przypadku tego podejścia, jeśli musisz wyzwolić pełne ponowne indeksowanie, zresetuj zapytanie źródła danych oprócz zresetowania indeksatora.

Dodawanie pól wyszukiwania do indeksu

W indeksie wyszukiwania dodaj pola, aby zaakceptować zawartość i metadane jednostek tabeli.

1. Utwórz lub zaktualizuj indeks , aby zdefiniować pola wyszukiwania, które będą przechowywać zawartość z jednostek:

   POST https://[service name].search.windows.net/indexes?api-version=2024-07-01 
   {
     "name" : "my-search-index",
     "fields": [
       { "name": "Key", "type": "Edm.String", "key": true, "searchable": false },
       { "name": "SomeColumnInMyTable", "type": "Edm.String", "searchable": true }
     ]
   }
   

2. Utwórz pole klucza dokumentu ("key": true), ale zezwól indeksatorowi na automatyczne wypełnienie go. Indeksator tabeli wypełnia pole klucza połączonymi kluczami partycji i kluczami wierszy z tabeli. Jeśli na przykład klucz partycji wiersza to 1 , a wartość RowKey to 1_123, wartość klucza to 11_123. Jeśli klucz partycji ma wartość null, używany jest tylko klucz wiersza.

   Jeśli używasz kreatora importu danych do utworzenia indeksu, witryna Azure Portal wywnioskuje pole "Klucz" dla indeksu wyszukiwania i używa niejawnego mapowania pól w celu połączenia pól źródłowych i docelowych. Nie musisz samodzielnie dodawać pola i nie trzeba konfigurować mapowania pól.

   Jeśli używasz interfejsów API REST i chcesz niejawnych mapowań pól, utwórz i nadaj nazwę polu klucza dokumentu "Klucz" w definicji indeksu wyszukiwania, jak pokazano w poprzednim kroku ({ "name": "Key", "type": "Edm.String", "key": true, "searchable": false }). Indeksator wypełnia pole Klucz automatycznie bez wymaganych mapowań pól.

   Jeśli nie potrzebujesz pola o nazwie "Klucz" w indeksie wyszukiwania, dodaj jawne mapowanie pól w definicji indeksatora z odpowiednią nazwą pola, ustawiając pole źródłowe na "Klucz":

    "fieldMappings" : [
      {
        "sourceFieldName" : "Key",
        "targetFieldName" : "MyDocumentKeyFieldName"
      }
   ]
   

3. Teraz dodaj inne pola jednostki, które mają być w indeksie. Jeśli na przykład jednostka wygląda jak w poniższym przykładzie, indeks wyszukiwania powinien zawierać pola HotelName, Description i Category, aby otrzymywać te wartości.

   

   Użycie tych samych nazw i zgodnych typów danych minimalizuje potrzebę mapowania pól. Gdy nazwy i typy są takie same, indeksator może automatycznie określić ścieżkę danych.

Konfigurowanie i uruchamianie indeksatora tabel

Po utworzeniu indeksu i źródła danych możesz utworzyć indeksator. Konfiguracja indeksatora określa dane wejściowe, parametry i właściwości kontrolujące zachowania czasu wykonywania.

1. Utwórz lub zaktualizuj indeksator , podając mu nazwę i odwołując się do źródła danych i indeksu docelowego:

   POST https://[service name].search.windows.net/indexers?api-version=2024-07-01
   {
       "name" : "my-table-indexer",
       "dataSourceName" : "my-table-storage-ds",
       "targetIndexName" : "my-search-index",
       "disabled": null,
       "schedule": null,
       "parameters" : {
           "batchSize" : null,
           "maxFailedItems" : null,
           "maxFailedItemsPerBatch" : null,
           "configuration" : { }
       },
       "fieldMappings" : [ ],
       "cache": null,
       "encryptionKey": null
   }
   

2. Określ mapowania pól, jeśli istnieją różnice w nazwie lub typie pola lub jeśli potrzebujesz wielu wersji pola źródłowego w indeksie wyszukiwania. Pole Target (Cel) to nazwa pola w indeksie wyszukiwania.

    "fieldMappings" : [
      {
        "sourceFieldName" : "Description",
        "targetFieldName" : "HotelDescription"
      }
   ]
   

3. Aby uzyskać więcej informacji na temat innych właściwości, zobacz Tworzenie indeksatora .

Indeksator jest uruchamiany automatycznie po jego utworzeniu. Możesz temu zapobiec, ustawiając wartość "disabled" na true. Aby kontrolować wykonywanie indeksatora, uruchom indeksator na żądanie lub umieść go zgodnie z harmonogramem.

Sprawdzanie stanu indeksatora

Aby monitorować stan indeksatora i historię wykonywania, sprawdź historię wykonywania indeksatora w witrynie Azure Portal lub wyślij interfejs API REST Get Indexer Status REST

GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2024-07-01
  Content-Type: application/json  
  api-key: [admin key]

    {
        "status":"running",
        "lastResult": {
            "status":"success",
            "errorMessage":null,
            "startTime":"2023-02-21T00:23:24.957Z",
            "endTime":"2023-02-21T00:36:47.752Z",
            "errors":[],
            "itemsProcessed":1599501,
            "itemsFailed":0,
            "initialTrackingState":null,
            "finalTrackingState":null
        },
        "executionHistory":
        [
            {
                "status":"success",
                "errorMessage":null,
                "startTime":"2023-02-21T00:23:24.957Z",
                "endTime":"2023-02-21T00:36:47.752Z",
                "errors":[],
                "itemsProcessed":1599501,
                "itemsFailed":0,
                "initialTrackingState":null,
                "finalTrackingState":null
            },
            ... earlier history items
        ]
    }

Historia wykonywania zawiera do 50 ostatnio wykonanych wykonań, które są sortowane w odwrotnej kolejności chronologicznej, tak aby najnowsze wykonanie było wykonywane jako pierwsze.

Następne kroki

Dowiedz się więcej na temat uruchamiania indeksatora, monitorowania stanu lub planowania wykonywania indeksatora. Następujące artykuły dotyczą indeksatorów, które ściągają zawartość z usługi Azure Storage:

• Samouczek: indeksowanie obiektów blob JSON z usługi Azure Storage
• Samouczek: indeksowanie zaszyfrowanych obiektów blob w usłudze Azure Storage