Indexování dat z Azure SQL ve službě Azure AI Search

V tomto článku se dozvíte, jak nakonfigurovat indexer , který importuje obsah ze služby Azure SQL Database nebo spravované instance Azure SQL a umožňuje vyhledávání ve službě Azure AI Search.

Tento článek doplňuje vytvoření indexeru s informacemi specifickými pro Azure SQL. 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.

Tento článek obsahuje také:

• Popis zásad detekce změn podporovaných indexerem Azure SQL, abyste mohli nastavit přírůstkové indexování.

• V části nejčastější dotazy najdete odpovědi na otázky týkající se kompatibility funkcí.

Požadavky

• Databáze Azure SQL s daty v jedné tabulce nebo zobrazení nebo ve spravované instanci SQL s veřejným koncovým bodem.

  Tabulku použijte, pokud jsou vaše data velká nebo pokud potřebujete přírůstkové indexování pomocí nativních funkcí detekce změn SQL.

  Pokud potřebujete konsolidovat data z více tabulek, použijte zobrazení. Velká zobrazení nejsou ideální pro indexer SQL. Alternativním řešením je vytvořit novou tabulku jen pro příjem dat do indexu Azure AI Search. Budete moct používat integrované sledování změn SQL, které je snazší implementovat než high water mark.

• Oprávnění ke čtení Azure AI Search podporuje ověřování SQL Serveru, kde jsou v připojovací řetězec zadané uživatelské jméno a heslo. Případně můžete nastavit spravovanou identitu a použít role Azure.

Pokud chcete projít příklady v tomto článku, potřebujete klienta REST.

Další přístupy k vytvoření indexeru Azure SQL zahrnují sady Azure SDK nebo Průvodce importem dat na webu Azure Portal. Pokud používáte Azure Portal, ujistěte se, že je v bráně firewall Azure SQL povolený přístup ke všem veřejným sítím a že má klient přístup přes příchozí pravidlo.

Definování zdroje dat

Definice zdroje dat určuje data, která se mají indexovat, přihlašovací údaje a zásady pro identifikaci změn v datech. Zdroj dat je definován jako nezávislý prostředek, aby ho mohl používat více indexerů.

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

    POST https://myservice.search.windows.net/datasources?api-version=2024-07-01
    Content-Type: application/json
    api-key: admin-key
   
    {
        "name" : "myazuresqldatasource",
        "description" : "A database for testing Azure AI Search indexes.",
        "type" : "azuresql",
        "credentials" : { "connectionString" : "Server=tcp:<your server>.database.windows.net,1433;Database=<your database>;User ID=<your user name>;Password=<your password>;Trusted_Connection=False;Encrypt=True;Connection Timeout=30;" },
        "container" : { 
            "name" : "name of the table or view that you want to index",
            "query" : null (not supported in the Azure SQL indexer)
            },
        "dataChangeDetectionPolicy": null,
        "dataDeletionDetectionPolicy": null,
        "encryptionKey": null,
        "identity": null
    }
   

2. Zadejte jedinečný název zdroje dat, který se řídí konvencemi vytváření názvů ve službě Azure AI Search.

3. Nastavte "typ" na "azuresql" (povinné).

4. Nastavte přihlašovací údaje na připojovací řetězec:

   • Úplný přístup připojovací řetězec získáte z webu Azure Portal. Použijte tuto ADO.NET connection string možnost. Nastavte uživatelské jméno a heslo.

   • Případně můžete zadat spravovanou identitu připojovací řetězec, která neobsahuje tajné kódy databáze s následujícím formátem: Initial Catalog|Database=<your database name>;ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Sql/servers/<your SQL Server name>/;Connection Timeout=connection timeout length;.

   Další informace najdete v tématu Připojení k indexeru služby Azure SQL Database pomocí spravované identity.

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

Do indexu vyhledávání přidejte pole, která odpovídají polím v databázi SQL. Ujistěte se, že schéma indexu vyhledávání je kompatibilní se zdrojovým schématem pomocí ekvivalentních datových typů.

1. Vytvořte nebo aktualizujte index a definujte vyhledávací pole, která budou ukládat data:

   POST https://[service name].search.windows.net/indexes?api-version=2024-07-01
   Content-Type: application/json
   api-key: [Search service admin key]
   {
       "name": "mysearchindex",
       "fields": [{
           "name": "id",
           "type": "Edm.String",
           "key": true,
           "searchable": false
       }, 
       {
           "name": "description",
           "type": "Edm.String",
           "filterable": false,
           "searchable": true,
           "sortable": false,
           "facetable": false,
           "suggestions": true
       }
     ]
   }
   

2. Vytvořte pole klíče dokumentu ("key": true), které jednoznačně identifikuje každý vyhledávací dokument. Toto je jediné pole, které je povinné v indexu vyhledávání. Primární klíč tabulky se obvykle mapuje na pole s klíčem indexu. Klíč dokumentu musí být jedinečný a nesmí mít hodnotu null. Hodnoty můžou být číselné ve zdrojových datech, ale v indexu vyhledávání je klíč vždy řetězec.

3. Vytvořte další pole pro přidání prohledávatelnějšího obsahu. Pokyny najdete v tématu Vytvoření indexu .

Mapování datových typů

Konfigurace a spuštění indexeru Azure SQL

Po vytvoření indexu a zdroje dat můžete indexer vytvořit. Konfigurace indexeru určuje vstupy, parametry a vlastnosti, které řídí chování doby běhu.

1. 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
   Content-Type: application/json
   api-key: [search service admin key]
   {
       "name" : "[my-sqldb-indexer]",
       "dataSourceName" : "[my-sqldb-ds]",
       "targetIndexName" : "[my-search-index]",
       "disabled": null,
       "schedule": null,
       "parameters": {
           "batchSize": null,
           "maxFailedItems": 0,
           "maxFailedItemsPerBatch": 0,
           "base64EncodeKeys": false,
           "configuration": {
               "queryTimeout": "00:04:00",
               "convertHighWaterMarkToRowVersion": false,
               "disableOrderByHighWaterMarkColumn": false
           }
       },
       "fieldMappings": [],
       "encryptionKey": null
   }
   

2. V části parametrů má oddíl konfigurace parametry specifické pro Azure SQL:

   • Výchozí časový limit dotazu pro spuštění dotazu SQL je 5 minut, který můžete přepsat.

   • "convertHighWaterMarkToRowVersion" optimalizuje zásady detekce změn high water mark. Zásady detekce změn jsou nastavené ve zdroji dat. Pokud používáte nativní zásady detekce změn, nemá tento parametr žádný vliv.

   • "disableOrderByHighWaterMarkColumn" způsobí, že dotaz SQL používaný zásadami horní značky vody vynechá klauzuli ORDER BY. Pokud používáte nativní zásady detekce změn, nemá tento parametr žádný vliv.

3. 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.

4. 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":"2022-02-21T00:23:24.957Z",
            "endTime":"2022-02-21T00:36:47.752Z",
            "errors":[],
            "itemsProcessed":1599501,
            "itemsFailed":0,
            "initialTrackingState":null,
            "finalTrackingState":null
        },
        "executionHistory":
        [
            {
                "status":"success",
                "errorMessage":null,
                "startTime":"2022-02-21T00:23:24.957Z",
                "endTime":"2022-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í.

Indexování nových, změněných a odstraněných řádků

Pokud vaše databáze SQL podporuje sledování změn, může indexer vyhledávání vyzvednout pouze nový a aktualizovaný obsah při následných spuštěních indexeru.

Chcete-li povolit přírůstkové indexování, nastavte vlastnost dataChangeDetectionPolicy v definici zdroje dat. Tato vlastnost říká indexeru, který mechanismus sledování změn se používá v tabulce nebo zobrazení.

Pro indexery Azure SQL existují dvě zásady detekce změn:

• SqlIntegratedChangeTrackingPolicy (platí jenom pro tabulky)

• HighWaterMarkChangeDetectionPolicy (funguje pro tabulky a zobrazení)

Integrované zásady sledování změn SQL

Pro efektivitu a schopnost identifikovat odstraněné řádky doporučujeme použít sqlIntegratedChangeTrackingPolicy.

Požadavky na databázi:

• SQL Server 2012 SP3 nebo novější, pokud používáte SQL Server na virtuálních počítačích Azure
• Azure SQL Database nebo SQL Managed Instance
• Pouze tabulky (bez zobrazení)
• V databázi povolte sledování změn pro tabulku.
• V tabulce není složený primární klíč (primární klíč obsahující více než jeden sloupec).
• V tabulce nejsou žádné clusterované indexy. Alternativním řešením může být vyřazení a opětovné vytvoření jakéhokoli clusterovaného indexu jako neclusterovaného indexu, ale výkon může být ve zdroji ovlivněn v porovnání s clusterovaným indexem.

Zásady detekce změn se přidají do definic zdrojů dat. Pokud chcete použít tuto zásadu, vytvořte nebo aktualizujte zdroj dat takto:

POST https://myservice.search.windows.net/datasources?api-version=2024-07-01
Content-Type: application/json
api-key: admin-key
    {
        "name" : "myazuresqldatasource",
        "type" : "azuresql",
        "credentials" : { "connectionString" : "connection string" },
        "container" : { "name" : "table name" },
        "dataChangeDetectionPolicy" : {
            "@odata.type" : "#Microsoft.Azure.Search.SqlIntegratedChangeTrackingPolicy"
    }

Při použití integrovaných zásad sledování změn SQL nezadávejte samostatné zásady detekce odstranění dat. Integrované zásady sledování změn SQL mají integrovanou podporu pro identifikaci odstraněných řádků. Aby se však odstraněné řádky detekovaly automaticky, musí být klíč dokumentu v indexu vyhledávání stejný jako primární klíč v tabulce SQL.

Zásady detekce změn horních znamétek

Tato zásada detekce změn závisí na sloupci "Horní značka" v tabulce nebo zobrazení, které zachycuje verzi nebo čas poslední aktualizace řádku. Pokud používáte zobrazení, musíte použít zásadu horní značky.

Sloupec horní značky musí splňovat následující požadavky:

• Všechna vložení určují hodnotu sloupce.
• Všechny aktualizace položky také změní hodnotu sloupce.
• Hodnota tohoto sloupce se zvyšuje při každém vložení nebo aktualizaci.
• Dotazy s následujícími klauzulemi WHERE a ORDER BY je možné efektivně spouštět: WHERE [High Water Mark Column] > [Current High Water Mark Value] ORDER BY [High Water Mark Column]

Zásady detekce změn se přidají do definic zdrojů dat. Pokud chcete použít tuto zásadu, vytvořte nebo aktualizujte zdroj dat takto:

POST https://myservice.search.windows.net/datasources?api-version=2024-07-01
Content-Type: application/json
api-key: admin-key
    {
        "name" : "myazuresqldatasource",
        "type" : "azuresql",
        "credentials" : { "connectionString" : "connection string" },
        "container" : { "name" : "table or view name" },
        "dataChangeDetectionPolicy" : {
            "@odata.type" : "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
            "highWaterMarkColumnName" : "[a rowversion or last_updated column name]"
        }
    }

convertHighWaterMarkToRowVersion

Pokud pro sloupec horní meze používáte datový typ rowversion , zvažte nastavení vlastnosti v konfiguraci indexeru convertHighWaterMarkToRowVersion . Nastavení této vlastnosti na hodnotu true má za následek následující chování:

• Používá datový typ rowversion pro sloupec horní značky v dotazu SQL indexeru. Použití správného datového typu zlepšuje výkon dotazů indexeru.

• Odečte jednu z hodnoty rowversion před spuštěním dotazu indexeru. Zobrazení s spojeními 1:N můžou obsahovat řádky s duplicitními hodnotami rowversion. Odečtením jednoho z nich zajistíte, že dotaz indexeru tyto řádky nezmešká.

Pokud chcete tuto vlastnost povolit, vytvořte nebo aktualizujte indexer pomocí následující konfigurace:

    {
      ... other indexer definition properties
     "parameters" : {
            "configuration" : { "convertHighWaterMarkToRowVersion" : true } }
    }

queryTimeout

Pokud dojde k chybám časového limitu queryTimeout , nastavte nastavení konfigurace indexeru na hodnotu vyšší než výchozí 5minutový časový limit. Pokud chcete například nastavit časový limit na 10 minut, vytvořte nebo aktualizujte indexer pomocí následující konfigurace:

    {
      ... other indexer definition properties
     "parameters" : {
            "configuration" : { "queryTimeout" : "00:10:00" } }
    }

disableOrderByHighWaterMarkColumn

Klauzuli ORDER BY [High Water Mark Column] můžete také zakázat. To ale nedoporučujeme, protože pokud je spuštění indexeru přerušeno chybou, indexer musí znovu zpracovat všechny řádky, pokud se spustí později, i když indexer už zpracoval téměř všechny řádky v době přerušení. Pokud chcete klauzuli ORDER BY zakázat, použijte disableOrderByHighWaterMarkColumn nastavení v definici indexeru:

    {
     ... other indexer definition properties
     "parameters" : {
            "configuration" : { "disableOrderByHighWaterMarkColumn" : true } }
    }

Zásady detekce obnovitelného odstranění sloupců

Když se řádky odstraní ze zdrojové tabulky, pravděpodobně budete chtít odstranit i tyto řádky z indexu vyhledávání. Pokud používáte integrované zásady sledování změn SQL, postará se o to za vás. Zásady sledování změn horních znamék vám ale nepomůžou s odstraněnými řádky. Co dělat?

Pokud jsou řádky fyzicky odebrány z tabulky, Azure AI Search nemůže odvodit přítomnost záznamů, které už neexistují. Pomocí techniky obnovitelného odstranění ale můžete logicky odstranit řádky, aniž byste je z tabulky odebrali. Přidejte sloupec do tabulky nebo zobrazení a označte řádky jako odstraněné pomocí tohoto sloupce.

Při použití techniky obnovitelného odstranění můžete zásadu obnovitelného odstranění zadat následujícím způsobem při vytváření nebo aktualizaci zdroje dat:

    {
        …,
        "dataDeletionDetectionPolicy" : {
           "@odata.type" : "#Microsoft.Azure.Search.SoftDeleteColumnDeletionDetectionPolicy",
           "softDeleteColumnName" : "[a column name]",
           "softDeleteMarkerValue" : "[the value that indicates that a row is deleted]"
        }
    }

SoftDeleteMarkerValue musí být řetězec v reprezentaci JSON vašeho zdroje dat. Použijte řetězcovou reprezentaci skutečné hodnoty. Pokud máte například celočíselnou hodnotu, ve které jsou odstraněné řádky označené hodnotou 1, použijte "1". Pokud máte sloupec BIT, ve kterém jsou odstraněné řádky označené logickou hodnotou true, použijte řetězcový literál "True" nebo "true"případ nezáleží.

Pokud nastavujete zásadu obnovitelného odstranění z webu Azure Portal, nepřidávejte uvozovky kolem hodnoty značky obnovitelného odstranění. Obsah pole je již pochopen jako řetězec a automaticky se přeloží do řetězce JSON. Ve výše uvedených příkladech jednoduše zadejte 1True nebo true do pole portálu.

Často kladené dotazy

Otázka: Můžu indexovat sloupce Always Encrypted?

Ne, indexery Azure AI Search v současné době nepodporují sloupce Always Encrypted .

Otázka: Můžu použít indexer Azure SQL s databázemi SQL běžícími na virtuálních počítačích IaaS v Azure?

Ano. Musíte ale službě Search povolit připojení k databázi. Další informace najdete v tématu Konfigurace připojení z indexeru Azure AI Search k SQL Serveru na virtuálním počítači Azure.

Otázka: Můžu použít indexer Azure SQL s databázemi SQL spuštěnými místně?

Ne přímo. Nedoporučujeme ani nepodporujeme přímé připojení, stejně jako byste museli otevírat databáze pro internetový provoz. Zákazníci s tímto scénářem uspěli pomocí technologií mostu, jako je Azure Data Factory. Další informace najdete v tématu Zápis dat do indexu Azure AI Search pomocí služby Azure Data Factory.

Otázka: Můžu jako zdroj dat použít sekundární repliku v clusteru s podporou převzetí služeb při selhání?

To záleží na okolnostech. Pro úplné indexování tabulky nebo zobrazení můžete použít sekundární repliku.

Pro přírůstkové indexování azure AI Search podporuje dvě zásady detekce změn: integrované sledování změn SQL a high water mark.

U replik jen pro čtení nepodporuje SQL Database integrované sledování změn. Proto musíte použít zásady vysoké značky.

Naším standardním doporučením je použití datového typu rowversion pro sloupec horní meze. Použití rowversion ale spoléhá na MIN_ACTIVE_ROWVERSION funkci, která není podporována na replikách jen pro čtení. Proto pokud používáte rowversion, musíte indexer nasměrovat na primární repliku.

Pokud se pokusíte použít rowversion v replice jen pro čtení, zobrazí se následující chyba:

Použití sloupce rowversion pro sledování změn není podporováno u sekundárních replik dostupnosti (jen pro čtení). Aktualizujte zdroj dat a zadejte připojení k primární replice dostupnosti. Aktuální vlastnost Aktualizovatelnost databáze je READ_ONLY.

Otázka: Můžu použít alternativní sloupec bez rowversion pro sledování změn horní značky?

Nedoporučuje se. Pouze rowversion umožňuje spolehlivou synchronizaci dat. V závislosti na logice vaší aplikace ale může být bezpečné, pokud:

• Můžete zajistit, aby při spuštění indexeru nedošlo k žádným nevyřízeným transakcím v tabulce, která se indexuje (například všechny aktualizace tabulek probíhají jako dávka podle plánu, a plán indexeru služby Azure AI Search je nastavený tak, aby se nepřekrývaly s plánem aktualizace tabulky).

• Pravidelně provedete úplné přeindexování a vyzvednete všechny zmeškané řádky.