Indeksowanie danych z usługi Azure SQL Database

Z tego artykułu dowiesz się, jak skonfigurować indeksator , który importuje zawartość z usługi Azure SQL Database lub wystąpienia zarządzanego usługi Azure SQL i umożliwia wyszukiwanie w usłudze Azure AI Search.

Ten artykuł uzupełnia tworzenie indeksatora z informacjami specyficznymi dla usługi Azure SQL. 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 utworzenia indeksatora.

Ten artykuł zawiera również następujące elementy:

• Opis zasad wykrywania zmian obsługiwanych przez indeksator usługi Azure SQL, dzięki czemu można skonfigurować indeksowanie przyrostowe.

• Sekcja często zadawanych pytań (FAQ) zawierająca odpowiedzi na pytania dotyczące zgodności funkcji.

Wymagania wstępne

• Baza danych Azure SQL lub zarządzane wystąpienie SQL z publicznym punktem końcowym.

• Pojedyncza tabela lub widok.

  Użyj tabeli, jeśli dane są duże lub jeśli potrzebujesz indeksowania przyrostowego przy użyciu natywnych funkcji wykrywania zmian SQL (zintegrowane śledzenie zmian SQL), aby odzwierciedlić nowe, zmienione i usunięte wiersze w indeksie wyszukiwania.

  Użyj widoku, jeśli chcesz skonsolidować dane z wielu tabel. Duże widoki nie są idealne dla indeksatora SQL. Obejściem jest utworzenie nowej tabeli tylko do pobierania danych do indeksu usługi Azure AI Search. Jeśli zdecydujesz się wybrać widok, możesz użyć znacznika wysokiej wody do wykrywania zmian, ale musisz użyć obejścia do wykrywania usuwania.

• Klucz podstawowy musi być jednowartościowy. W tabeli musi być ona również nieklaterowana w celu pełnego śledzenia zmian zintegrowanych z programem SQL.

• Uprawnienia do odczytu. Usługa Azure AI Search obsługuje uwierzytelnianie programu SQL Server, gdzie w parametry połączenia podano nazwę użytkownika i hasło. Alternatywnie można skonfigurować tożsamość zarządzaną i używać ról platformy Azure z członkostwem w rolach współautora programu SQL Server lub współautora bazy danych SQL .

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 w zaporze Azure SQL Firewall i że klient ma dostęp za pośrednictwem reguły ruchu przychodzącego. W przypadku klienta REST, który działa lokalnie, skonfiguruj zaporę programu SQL Server, aby zezwolić na dostęp przychodzący z adresu IP urządzenia. Inne podejścia do tworzenia indeksatora usługi Azure SQL obejmują zestawy AZURE SDK.

Wypróbuj przykładowe dane

Skorzystaj z tych instrukcji, aby utworzyć i załadować tabelę w usłudze Azure SQL Database do celów testowych.

1. Pobierz hotels-azure-sql.sql z usługi GitHub, aby utworzyć tabelę w usłudze Azure SQL Database zawierającą podzbiór przykładowych zestawów danych hoteli.

2. Zaloguj się do Azure Portal i utwórz bazę danych Azure SQL i serwer Azure SQL. Rozważ skonfigurowanie zarówno uwierzytelniania SQL Server, jak i uwierzytelniania Microsoft Entra ID. Jeśli nie masz uprawnień do konfigurowania ról na platformie Azure, możesz użyć uwierzytelniania SQL jako obejścia.

3. Skonfiguruj zaporę serwera do wszystkich żądań przychodzących z urządzenia lokalnego.

4. W bazie danych Azure SQL Database wybierz pozycję Edytor zapytań (wersja zapoznawcza), a następnie wybierz pozycję Nowe zapytanie.

5. Wklej polecenie , a następnie uruchom skrypt języka T-SQL, który tworzy tabelę hotels. Klucz podstawowy bez klastra jest wymagany do śledzenia zintegrowanych zmian SQL.

   CREATE TABLE tbl_hotels
    (
        Id TINYINT PRIMARY KEY NONCLUSTERED,
        Modified DateTime NULL DEFAULT '0000-00-00 00:00:00',
        IsDeleted TINYINT,
        HotelName VARCHAR(40),
        Category VARCHAR(20),
        City VARCHAR(30),
        State VARCHAR(4),
        Description VARCHAR(500)
    );
   

6. Wklej skrypt T-SQL i uruchom go, który wstawia rekordy.

    -- Insert rows
    INSERT INTO tbl_hotels (Id, Modified, IsDeleted, HotelName, Category, City, State, Description) VALUES (1, CURRENT_TIMESTAMP, 0,  'Stay-Kay City Hotel', 'Boutique', 'New York', 'NY', 'This classic hotel is fully-refurbished and ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Times Square and the historic centre of the city, as well as other places of interest that make New York one of Americas most attractive and cosmopolitan cities.');
    INSERT INTO tbl_hotels (Id, Modified, IsDeleted, HotelName, Category, City, State, Description) VALUES (10, CURRENT_TIMESTAMP, 0, 'Countryside Hotel', 'Extended-Stay', 'Durham', 'NC', 'Save up to 50% off traditional hotels. Free WiFi, great location near downtown, full kitchen, washer & dryer, 24\/7 support, bowling alley, fitness center and more.');
    INSERT INTO tbl_hotels (Id, Modified, IsDeleted, HotelName, Category, City, State, Description) VALUES (11, CURRENT_TIMESTAMP, 0, 'Royal Cottage Resort', 'Extended-Stay', 'Bothell', 'WA', 'Your home away from home. Brand new fully equipped premium rooms, fast WiFi, full kitchen, washer & dryer, fitness center. Inner courtyard includes water features and outdoor seating. All units include fireplaces and small outdoor balconies. Pets accepted.');
    INSERT INTO tbl_hotels (Id, Modified, IsDeleted, HotelName, Category, City, State, Description) VALUES (12, CURRENT_TIMESTAMP, 0, 'Winter Panorama Resort', 'Resort and Spa', 'Wilsonville', 'OR', 'Plenty of great skiing, outdoor ice skating, sleigh rides, tubing and snow biking. Yoga, group exercise classes and outdoor hockey are available year-round, plus numerous options for shopping as well as great spa services. Newly-renovated with large rooms, free 24-hr airport shuttle & a new restaurant. Rooms\/suites offer mini-fridges & 49-inch HDTVs.');
    INSERT INTO tbl_hotels (Id, Modified, IsDeleted, HotelName, Category, City, State, Description) VALUES (13, CURRENT_TIMESTAMP, 0, 'Luxury Lion Resort', 'Luxury', 'St. Louis', 'MO', 'Unmatched Luxury. Visit our downtown hotel to indulge in luxury accommodations. Moments from the stadium and transportation hubs, we feature the best in convenience and comfort.');
    INSERT INTO tbl_hotels (Id, Modified, IsDeleted, HotelName, Category, City, State, Description) VALUES (14, CURRENT_TIMESTAMP, 0, 'Twin Vortex Hotel', 'Luxury', 'Dallas', 'TX', 'New experience in the making. Be the first to experience the luxury of the Twin Vortex. Reserve one of our newly-renovated guest rooms today.');
    INSERT INTO tbl_hotels (Id, Modified, IsDeleted, HotelName, Category, City, State, Description) VALUES (15, CURRENT_TIMESTAMP, 0, 'By the Market Hotel', 'Budget', 'New York', 'NY', 'Book now and Save up to 30%. Central location. Walking distance from the Empire State Building & Times Square, in the Chelsea neighborhood. Brand new rooms. Impeccable service.');
    INSERT INTO tbl_hotels (Id, Modified, IsDeleted, HotelName, Category, City, State, Description) VALUES (16, CURRENT_TIMESTAMP, 0, 'Double Sanctuary Resort', 'Resort and Spa', 'Seattle', 'WA', '5 Star Luxury Hotel - Biggest Rooms in the city. #1 Hotel in the area listed by Traveler magazine. Free WiFi, Flexible check in\/out, Fitness Center & espresso in room.');
    INSERT INTO tbl_hotels (Id, Modified, IsDeleted, HotelName, Category, City, State, Description) VALUES (17, CURRENT_TIMESTAMP, 0, 'City Skyline Antiquity Hotel', 'Boutique', 'New York', 'NY', 'In vogue since 1888, the Antiquity Hotel takes you back to bygone era. From the crystal chandeliers that adorn the Green Room, to the arched ceilings of the Grand Hall, the elegance of old New York beckons. Elevate Your Experience. Upgrade to a premiere city skyline view for less, where old world charm combines with dramatic views of the city, local cathedral and midtown.');
    INSERT INTO tbl_hotels (Id, Modified, IsDeleted, HotelName, Category, City, State, Description) VALUES (18, CURRENT_TIMESTAMP, 0, 'Ocean Water Resort & Spa', 'Luxury', 'Tampa', 'FL', 'New Luxury Hotel for the vacation of a lifetime. Bay views from every room, location near the pier, rooftop pool, waterfront dining & more.');
    INSERT INTO tbl_hotels (Id, Modified, IsDeleted, HotelName, Category, City, State, Description) VALUES (19, CURRENT_TIMESTAMP, 0, 'Economy Universe Motel', 'Budget', 'Redmond', 'WA', 'Local, family-run hotel in bustling downtown Redmond. We are a pet-friendly establishment, near expansive Marymoor park, haven to pet owners, joggers, and sports enthusiasts. Close to the highway and just a short drive away from major cities.');
    INSERT INTO tbl_hotels (Id, Modified, IsDeleted, HotelName, Category, City, State, Description) VALUES (20, CURRENT_TIMESTAMP, 0, 'Delete Me Hotel', 'Unknown', 'Nowhere', 'XX', 'Test-case row for change detection and delete detection . For change detection, modify any value, and then re-run the indexer. For soft-delete, change IsDelete from zero to a one, and then re-run the indexer.');
   
   

7. Uruchom zapytanie, aby potwierdzić przekazanie.

   SELECT Description FROM tbl_hotels;
   

   Powinny zostać wyświetlone wyniki podobne do poniższego zrzutu ekranu.

   

Pole Opis zawiera najbardziej szczegółową zawartość. To pole powinno być przeznaczone dla wyszukiwania pełnotekstowego i wektoryzacji opcjonalnej.

Teraz, gdy masz tabelę bazy danych, możesz za pomocą witryny Azure Portal, klienta REST lub zestawu Azure SDK indeksować dane.

Skonfiguruj potok indeksatora

W tym kroku określ źródło danych, indeks i indeksator.

Sprawdzanie stanu indeksatora

Aby monitorować stan indeksatora i historię wykonywania, sprawdź historię wykonywania indeksatora w portalu Azure lub wyślij żądanie REST API Get Indexer Status.

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

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

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.

Indeksowanie nowych, zmienionych i usuniętych wierszy

Jeśli baza danych SQL obsługuje śledzenie zmian, indeksator wyszukiwania może pobrać tylko nową i zaktualizowaną zawartość na kolejnych uruchomieniach indeksatora.

Aby włączyć indeksowanie przyrostowe, ustaw właściwość "dataChangeDetectionPolicy" w definicji źródła danych. Właściwość ta informuje indeksator o mechanizmie śledzenia zmian używanym w tabeli lub widoku.

W przypadku indeksatorów usługi Azure SQL istnieją dwie zasady wykrywania zmian:

• "SqlIntegratedChangeTrackingPolicy" (dotyczy tylko tabel)

• Polityka wykrywania zmian HighWaterMark (działa dla widoków)

Zintegrowane zasady śledzenia zmian SQL

Zaleca się używanie "SqlIntegratedChangeTrackingPolicy" ze względu na jego wydajność i zdolność do identyfikowania usuniętych wierszy.

Wymagania dotyczące bazy danych:

• Azure SQL Database lub SQL Managed Instance. Program SQL Server 2016 lub nowszy, jeśli używasz maszyny wirtualnej platformy Azure.
• Baza danych musi mieć włączone śledzenie zmian
• Tylko tabele (bez widoków).
• Tabele nie mogą być klastrowane. Aby spełnić to wymaganie, usuń indeks klastrowany i utwórz go ponownie jako indeks nieklastrowany. Obejście często obniża wydajność. Duplikowanie zawartości w drugiej tabeli dedykowanej do przetwarzania indeksatora może być pomocnym ograniczeniem ryzyka.
• Tabele nie mogą być puste. Jeśli używasz narzędzia TRUNCATE TABLE do czyszczenia wierszy, resetowanie i ponowne uruchamianie indeksatora nie spowoduje usunięcia odpowiednich dokumentów wyszukiwania. pl-PL: Aby usunąć osierocone dokumenty wyszukiwania, należy je zaindeksować poprzez akcję usunięcia.
• Klucz podstawowy nie może być kluczem złożonym (zawierającym więcej niż jedną kolumnę).
• Jeśli chcesz wykryć usunięcie, klucz podstawowy musi być nieklasterowany.

Zasady wykrywania zmian są dodawane do definicji źródła danych. Aby użyć tych zasad, edytuj definicję źródła danych w witrynie Azure Portal lub użyj interfejsu REST, aby zaktualizować źródło danych w następujący sposób:

POST https://myservice.search.windows.net/datasources?api-version=2025-09-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"
        }
    }

W przypadku korzystania z zintegrowanych zasad śledzenia zmian SQL nie należy określać oddzielnych zasad wykrywania usuwania danych. Zintegrowane zasady śledzenia zmian SQL mają wbudowaną obsługę identyfikowania usuniętych wierszy. Jednak aby wiersze usunięte zostały wykryte automatycznie, klucz dokumentu w indeksie wyszukiwania musi być taki sam jak klucz podstawowy w tabeli SQL, a klucz podstawowy musi być nieklaterowany.

Polityka wykrywania zmian znacznika maksymalnego poziomu wody

Ta zasada wykrywania zmian opiera się na kolumnie "high water mark" w tabeli lub widoku, która przechwytuje wersję lub czas ostatniej aktualizacji wiersza. Jeśli używasz widoku systemowego, należy zastosować politykę wysokiego poziomu kontroli.

Kolumna wysokiego limitu wody musi spełniać następujące wymagania:

• Wszystkie wstawki określają wartość kolumny.
• Wszystkie aktualizacje elementu również zmieniają wartość kolumny.
• Wartość tej kolumny jest zwiększana przy każdym wstawieniu lub aktualizacji.
• Zapytania z następującymi klauzulami WHERE i ORDER BY można wykonywać wydajnie: WHERE [High Water Mark Column] > [Current High Water Mark Value] ORDER BY [High Water Mark Column]

Zasady wykrywania zmian są dodawane do definicji źródła danych. Aby użyć tych zasad, utwórz lub zaktualizuj źródło danych w następujący sposób:

POST https://myservice.search.windows.net/datasources?api-version=2025-09-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

Jeśli używasz typu danych rowversion dla kolumny znacznika końcowego, rozważ ustawienie właściwości convertHighWaterMarkToRowVersion w konfiguracji indeksatora. Ustawienie tej właściwości na true powoduje następujące zachowania:

• Używa typu danych rowversion dla kolumny punktu odniesienia w zapytaniu SQL wykorzystującym indeksowanie. Użycie poprawnego typu danych zwiększa wydajność zapytań indeksatora.

• Odejmuje jedną z wartości rowversion przed uruchomieniem zapytania indeksatora. Widoki ze sprzężeniami jeden do wielu mogą zawierać wiersze ze zduplikowanymi wartościami rowversion. Odejmowanie jednego gwarantuje, że zapytanie indeksatora nie przegapi tych wierszy.

Aby włączyć tę właściwość, utwórz lub zaktualizuj indeksator przy użyciu następującej konfiguracji:

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

limit czasu zapytania

Jeśli wystąpią błędy przekroczenia limitu czasu, ustaw queryTimeout ustawienie konfiguracji indeksatora na wartość wyższą niż domyślny limit czasu 5-minutowy. Aby na przykład ustawić limit czasu na 10 minut, utwórz lub zaktualizuj indeksator przy użyciu następującej konfiguracji:

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

wyłączSortowanieWedługKolumnyWysokiegoZnakuWodnego

Możesz również wyłączyć klauzulę ORDER BY [High Water Mark Column] . Nie jest to jednak zalecane, ponieważ jeśli wykonanie indeksatora zostanie przerwane przez błąd, indeksator musi ponownie przetworzyć wszystkie wiersze, jeśli zostanie uruchomiony później, nawet jeśli indeksator przetworzył już prawie wszystkie wiersze w czasie przerwania. Aby wyłączyć klauzulę ORDER BY, użyj ustawienia disableOrderByHighWaterMarkColumn w definicji indeksatora.

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

Polityka wykrywania miękkiego usunięcia kolumny

Po usunięciu wierszy z tabeli źródłowej prawdopodobnie chcesz również usunąć te wiersze z indeksu wyszukiwania. Jeśli używasz zintegrowanej polityki śledzenia zmian SQL, zostanie to dla Ciebie automatycznie obsłużone. Jednak zasady śledzenia zmian z wykorzystaniem znacznika wysokiej wody nie pomagają w przypadku usuniętych wierszy. Co robić?

Jeśli wiersze są fizycznie usuwane z tabeli, usługa Azure AI Search nie ma możliwości wnioskowania o obecności rekordów, które już nie istnieją. Można jednak użyć techniki "soft-delete", aby logicznie usunąć wiersze bez usuwania ich z tabeli. Dodaj kolumnę do tabeli lub widoku i oznacz wiersze jako usunięte przy użyciu tej kolumny.

W przypadku korzystania z techniki usuwania nietrwałego można określić zasady usuwania nietrwałego w następujący sposób podczas tworzenia lub aktualizowania źródła danych:

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

softDeleteMarkerValue musi być ciągiem w reprezentacji JSON twojego źródła danych. Użyj reprezentacji ciągu rzeczywistej wartości. Jeśli na przykład masz kolumnę całkowitą, w której usunięte wiersze są oznaczone wartością 1, użyj wartości "1". Jeśli masz kolumnę BIT, w której usunięte wiersze są oznaczone wartością true wartości logicznej, użyj literału "True" ciągu lub "true", wielkość liter nie ma znaczenia.

Jeśli konfigurujesz zasady usuwania miękkiego z portalu Azure, nie dodawaj cudzysłowów wokół wartości znacznika usuwania miękkiego. Zawartość pola jest już rozumiana jako ciąg i jest tłumaczona automatycznie na ciąg JSON. W poprzednich przykładach po prostu wpisz 1, True lub true w polu portalu Azure.

Często zadawane pytania

.: Czy mogę indeksować kolumny Always Encrypted?

Nie, kolumny Always Encrypted nie są obecnie obsługiwane przez indeksatory usługi Azure AI Search.

.: Czy mogę używać indeksatora Azure SQL z bazami danych SQL działającymi na maszynach wirtualnych IaaS na platformie Azure?

Tak. Należy jednak zezwolić usłudze wyszukiwania na łączenie się z bazą danych. Aby uzyskać więcej informacji, zobacz Konfigurowanie połączenia z indeksatora usługi Azure AI Search do programu SQL Server na maszynie wirtualnej platformy Azure.

.: Czy mogę używać indeksatora Azure SQL z bazami danych SQL działającymi lokalnie?

Nie bezpośrednio. Nie zalecamy ani nie obsługujemy bezpośredniego połączenia, ponieważ wymaga to otwarcia baz danych na ruch internetowy. Klienci odnieśli sukces w tym scenariuszu przy użyciu technologii pośredniczących, takich jak Azure Data Factory. Aby uzyskać więcej informacji, zobacz Wypychanie danych do indeksu usługi Azure AI Search przy użyciu usługi Azure Data Factory.

Czy mogę użyć repliki wtórnej w klastrze trybu przełączenia awaryjnego jako źródła danych?

To zależy. Aby uzyskać pełne indeksowanie tabeli lub widoku, można użyć repliki pomocniczej.

W przypadku indeksowania inkrementalnego usługa Azure AI Search obsługuje dwie zasady wykrywania zmian: zintegrowane śledzenie zmian SQL i wysoki punkt odniesienia.

W replikach tylko do odczytu usługa SQL Database nie obsługuje zintegrowanego śledzenia zmian. W związku z tym należy użyć polityki High Water Mark.

Naszym standardowym zaleceniem jest użycie typu danych rowversion dla kolumny granicznej wartości. Jednak użycie funkcji rowversion opiera się na MIN_ACTIVE_ROWVERSION, która nie jest obsługiwana na replikach w trybie tylko do odczytu. W związku z tym należy wskazać indeksator do repliki podstawowej, jeśli używasz funkcji rowversion.

Jeśli próbujesz użyć rowversion w replice tylko do odczytu, wystąpi następujący błąd:

Używanie kolumny rowversion do śledzenia zmian nie jest obsługiwane w dostępnych replikach tylko do odczytu. Zaktualizuj źródło danych i określ połączenie z repliką dostępności podstawowej. Bieżąca właściwość "Updateability" bazy danych to "READ_ONLY".

.: Czy mogę użyć alternatywnej kolumny innej niż rowversion na potrzeby śledzenia zmian znacznika górnego limitu wody?

Nie jest to zalecane. Tylko wersja wiersza umożliwia niezawodną synchronizację danych. Jednak w zależności od logiki aplikacji może to być bezpieczne, jeśli:

• Możesz upewnić się, że po uruchomieniu indeksatora nie ma zaległych transakcji w tabeli indeksowanej (na przykład wszystkie aktualizacje tabel są wykonywane jako partia zgodnie z harmonogramem, a harmonogram indeksatora usługi Azure AI Search jest ustawiony, aby uniknąć nakładania się na harmonogram aktualizacji tabeli).

• Okresowo wykonujesz pełne ponowne indeksowanie, aby odebrać wszystkie pominięte wiersze.