Indeksowanie danych z usługi Azure Table Storage

Artykuł
02/22/2024

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 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 Dane i Czytelnik.
Użyj klienta REST, aby sformułować wywołania REST podobne do tych przedstawionych w tym artykule.

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.

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

 POST https://[service name].search.windows.net/datasources?api-version=2023-11-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
 }

Ustaw wartość "type" na "azuretable" (wymagane).
Ustaw wartość "credentials" na parametry połączenia usługi Azure Storage. W następnej sekcji opisano obsługiwane formaty.
Ustaw wartość "container" na nazwę tabeli.
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ń.

Pełny dostęp do konta magazynu parametry połączenia
`{ "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<your storage account>;AccountKey=<your account key>;" }`
Parametry połączenia można uzyskać na stronie Konto magazynu w witrynie Azure Portal, wybierając pozycję Klucze dostępu w okienku nawigacji po lewej stronie. Pamiętaj, aby wybrać pełny parametry połączenia, a nie tylko klucz.

Parametry połączenia tożsamości zarządzanej
`{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Storage/storageAccounts/<your storage account name>/;" }`
Ta parametry połączenia nie wymaga klucza konta, ale musisz wcześniej skonfigurować usługę wyszukiwania w celu nawiązania połączenia przy użyciu tożsamości zarządzanej.

Sygnatura dostępu współdzielonego konta magazynu** (SAS) parametry połączenia
`{ "connectionString" : "BlobEndpoint=https://<your account>.blob.core.windows.net/;SharedAccessSignature=?sv=2016-05-31&sig=<the signature>&spr=https&se=<the validity end time>&srt=co&ss=b&sp=rl;" }`
Sygnatura dostępu współdzielonego powinna mieć uprawnienia do wyświetlania listy i odczytu tabel i jednostek.

Sygnatura dostępu współdzielonego kontenera
`{ "connectionString" : "ContainerSharedAccessUri=https://<your storage account>.blob.core.windows.net/<container name>?sv=2016-05-31&sr=c&sig=<the signature>&se=<the validity end time>&sp=rl;" }`
Sygnatura dostępu współdzielonego powinna mieć uprawnienia do odczytu i listy w kontenerze. Aby uzyskać więcej informacji, zobacz Using Shared Access Signatures (Używanie sygnatur dostępu współdzielonego).

Uwaga

Jeśli używasz poświadczeń sygnatury dostępu współdzielonego, musisz okresowo aktualizować poświadczenia źródła danych przy użyciu odnowionych podpisów, aby zapobiec ich wygaśnięciu. Po wygaśnięciu poświadczeń sygnatury dostępu współdzielonego indeksator zakończy się niepowodzeniem z komunikatem o błędzie podobnym do "Poświadczenia podane w parametry połączenia są nieprawidłowe lub wygasły".

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.

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=2023-11-01 
{
  "name" : "my-search-index",
  "fields": [
    { "name": "Key", "type": "Edm.String", "key": true, "searchable": false },
    { "name": "SomeColumnInMyTable", "type": "Edm.String", "searchable": true }
  ]
}

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, 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"
   }
]
```
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.

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=2023-11-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,
        "base64EncodeKeys" : null,
        "configuration" : { }
    },
    "fieldMappings" : [ ],
    "cache": null,
    "encryptionKey": null
}

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"
   }
]
```
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, wyślij żądanie pobierz stan indeksatora:

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

Odpowiedź zawiera stan i liczbę przetworzonych elementów. Powinien on wyglądać podobnie do poniższego przykładu:

    {
        "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: