Indexování dat z Azure Table Storage

Článek
09/01/2024

V tomto článku se dozvíte, jak nakonfigurovat indexer , který importuje obsah ze služby Azure Table Storage a umožňuje ho prohledávat ve službě Azure AI Search. Vstupy indexeru jsou vaše entity v jedné tabulce. Výstup je index vyhledávání s prohledávatelným obsahem a metadaty uloženými v jednotlivých polích.

Tento článek doplňuje vytvoření indexeru informacemi, které jsou specifické pro indexování z Azure Table Storage. Pomocí rozhraní REST API demonstruje třídílný pracovní postup společný pro všechny indexery: vytvoření zdroje dat, vytvoření indexeru a vytvoření indexeru. Extrakce dat nastane, když odešlete požadavek Create Indexer.

Požadavky

Azure Table Storage
Tabulky obsahující text Pokud máte binární data, zvažte rozšíření AI pro analýzu obrázků.
Oprávnění ke čtení ve službě Azure Storage Úplný přístup připojovací řetězec obsahuje klíč, který poskytuje přístup k obsahu, ale pokud používáte role Azure, ujistěte se, že spravovaná identita vyhledávací služby má oprávnění Data a Čtenář.
Pomocí klienta REST formulujte volání REST podobně jako volání, která jsou uvedená v tomto článku.

Definování zdroje dat

Definice zdroje dat určuje zdrojová data pro indexování, přihlašovací údaje a zásady pro detekci změn. Zdroj dat je nezávislý prostředek, který může používat více indexerů.

Vytvořte nebo aktualizujte zdroj dat a nastavte jeho definici:

 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
 }

Nastavte "typ" na "azuretable" (povinné).
Nastavte přihlašovací údaje na připojovací řetězec služby Azure Storage. Následující část popisuje podporované formáty.
Nastavte "kontejner" na název tabulky.
Volitelně můžete nastavit dotaz na filtr pro PartitionKey. Nastavení této vlastnosti je osvědčeným postupem, který zlepšuje výkon. Pokud má parametr "query" hodnotu null, spustí indexer úplnou kontrolu tabulky, což může vést k nízkému výkonu, pokud jsou tabulky velké.

Definice zdroje dat může také zahrnovat zásady obnovitelného odstranění, pokud chcete, aby indexer odstranil vyhledávací dokument, když je zdrojový dokument označen příznakem pro odstranění.

Podporované přihlašovací údaje a připojovací řetězec

Indexery se můžou připojit k tabulce pomocí následujících připojení.

Připojovací řetězec účtu úložiště s úplným přístupem
`{ "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<your storage account>;AccountKey=<your account key>;" }`
Připojovací řetězec můžete získat ze stránky účtu úložiště na webu Azure Portal výběrem přístupových klíčů v levém navigačním podokně. Nezapomeňte vybrat úplný připojovací řetězec a ne jenom klíč.

Připojovací řetězec spravované identity
`{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Storage/storageAccounts/<your storage account name>/;" }`
Tato připojovací řetězec nevyžaduje klíč účtu, ale dříve jste nakonfigurovali vyhledávací službu pro připojení pomocí spravované identity.

Sdílený přístupový podpis účtu úložiště** (SAS) připojovací řetězec
`{ "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;" }`
Sdílený přístupový podpis by měl mít u tabulek a entit oprávnění ke čtení.

Sdílený přístupový podpis kontejneru
`{ "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;" }`
Sdílený přístupový podpis by měl mít v kontejneru oprávnění ke čtení a seznam. Další informace naleznete v tématu Použití sdílených přístupových podpisů.

Poznámka:

Pokud používáte přihlašovací údaje SAS, budete muset přihlašovací údaje ke zdroji dat pravidelně aktualizovat obnovenými podpisy, aby se zabránilo jejich vypršení platnosti. Když vyprší platnost přihlašovacích údajů SAS, indexer selže s chybovou zprávou typu "Přihlašovací údaje zadané v připojovací řetězec jsou neplatné nebo vypršela jejich platnost".

Oddíl pro zvýšení výkonu

Azure AI Search ve výchozím nastavení používá následující interní filtr dotazů ke sledování toho, které zdrojové entity byly od posledního spuštění aktualizovány: Timestamp >= HighWaterMarkValue Vzhledem k tomu, že tabulky Azure nemají v poli sekundární index Timestamp , tento typ dotazu vyžaduje úplnou kontrolu tabulky, a proto je pomalý pro velké tabulky.

Abyste se vyhnuli úplnému prohledávání, můžete pomocí oddílů tabulky zúžit rozsah jednotlivých úloh indexeru.

Pokud je možné data přirozeně rozdělit do několika oblastí oddílů, vytvořte zdroj dat a odpovídající indexer pro každou oblast oddílů. Každý indexer teď musí zpracovat jenom konkrétní rozsah oddílů, což vede k lepšímu výkonu dotazů. Pokud data, která je potřeba indexovat, mají malý počet pevných oddílů, ještě lépe: každý indexer prohledá pouze oddíly.

Pokud například chcete vytvořit zdroj dat pro zpracování rozsahu oddílů s klíči od 000 do 100, použijte dotaz podobný tomuto: "container" : { "name" : "my-table", "query" : "PartitionKey ge '000' and PartitionKey lt '100' " }
Pokud jsou data rozdělená podle času (například pokud vytváříte nový oddíl každý den nebo týden), zvažte následující přístup:
- V definici zdroje dat zadejte dotaz podobný následujícímu příkladu: (PartitionKey ge <TimeStamp>) and (other filters).
- Sledujte průběh indexeru pomocí rozhraní API pro získání stavu indexeru a pravidelně aktualizujte <TimeStamp> podmínku dotazu na základě nejnovější úspěšné hodnoty horní meze.
- Pokud při tomto přístupu potřebujete aktivovat úplné přeindexování, resetujte kromě indexeru také dotaz zdroje dat.

Přidání vyhledávacích polí do indexu

Do indexu vyhledávání přidejte pole pro příjem obsahu a metadat entit tabulky.

Vytvořte nebo aktualizujte index a definujte vyhledávací pole, která budou ukládat obsah z entit:

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 }
  ]
}

Vytvořte pole klíče dokumentu ("key": true), ale indexer ho automaticky naplní. Indexer tabulky naplní pole klíče zřetězenými klíči oddílu a klíčů řádků z tabulky. Pokud je například PartitionKey 1 řádku a RowKey je 1_123, pak hodnota klíče je 11_123. Pokud má klíč oddílu hodnotu null, použije se pouze klíč řádku.

Pokud k vytvoření indexu používáte Průvodce importem dat, portál odvodí pole Klíč pro index vyhledávání a použije implicitní mapování polí pro připojení zdrojových a cílových polí. Pole nemusíte přidávat sami a nemusíte nastavovat mapování polí.

Pokud používáte rozhraní REST API a chcete implicitní mapování polí, vytvořte a pojmenujte pole klíče dokumentu "Klíč" v definici indexu vyhledávání, jak je znázorněno v předchozím kroku ({ "name": "Key", "type": "Edm.String", "key": true, "searchable": false }). Indexer vyplní pole Klíč automaticky bez nutnosti mapování polí.

Pokud nechcete ve vyhledávacím indexu pole s názvem Klíč, přidejte do definice indexeru explicitní mapování polí s požadovaným názvem pole a nastavte zdrojové pole na Klíč:
```
 "fieldMappings" : [
   {
     "sourceFieldName" : "Key",
     "targetFieldName" : "MyDocumentKeyFieldName"
   }
]
```
Teď přidejte do indexu všechna další pole entity, která chcete použít. Pokud například entita vypadá jako v následujícím příkladu, měl by mít index vyhledávání pole pro HotelName, Description a Category, aby tyto hodnoty získal.

Použití stejných názvů a kompatibilních datových typů minimalizuje potřebu mapování polí. Pokud jsou názvy a typy stejné, indexer může automaticky určit cestu k datům.

Konfigurace a spuštění indexeru tabulky

Jakmile budete mít index a zdroj dat, budete připraveni vytvořit indexer. Konfigurace indexeru určuje vstupy, parametry a vlastnosti, které řídí chování doby běhu.

Vytvořte nebo aktualizujte indexer tak, že ho pojmenujte a odkazujete na zdroj dat a cílový index:

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
}

Určete mapování polí, pokud existují rozdíly v názvu nebo typu pole nebo pokud potřebujete v indexu vyhledávání více verzí zdrojového pole. Cílové pole je název pole v indexu vyhledávání.
```
 "fieldMappings" : [
   {
     "sourceFieldName" : "Description",
     "targetFieldName" : "HotelDescription"
   }
]
```
Další informace o dalších vlastnostech najdete v tématu Vytvoření indexeru .

Indexer se spustí automaticky při jeho vytvoření. Můžete tomu zabránit nastavením "zakázáno" na hodnotu true. Pokud chcete řídit provádění indexeru, spusťte indexer na vyžádání nebo ho umístěte do plánu.

Kontrola stavu indexeru

Pokud chcete monitorovat stav indexeru a historii spuštění, odešlete žádost o získání stavu indexeru:

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

Odpověď zahrnuje stav a počet zpracovaných položek. Měl by vypadat podobně jako v následujícím příkladu:

    {
        "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
        ]
    }

Historie provádění obsahuje až 50 naposledy dokončených spuštění, které jsou seřazeny v obráceném chronologickém pořadí tak, aby poslední spuštění bylo první.

Další kroky

Přečtěte si další informace o tom, jak spustit indexer, monitorovat stav nebo naplánovat spuštění indexeru. Následující články platí pro indexery, které načítá obsah ze služby Azure Storage:

Sdílet prostřednictvím