Importowanie danych z usługi Azure Cosmos DB for NoSQL na potrzeby zapytań w usłudze Azure AI Search

W tym artykule dowiesz się, jak skonfigurować indeksator , który importuje zawartość z usługi Azure Cosmos DB for NoSQL i umożliwia wyszukiwanie w usłudze Azure AI Search.

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

Ponieważ terminologia może być myląca, warto zauważyć, że indeksowanie usługi Azure Cosmos DB i indeksowanie usługi Azure AI Search są różnymi operacjami. Indeksowanie w usłudze Azure AI Search tworzy i ładuje indeks wyszukiwania w usłudze wyszukiwania.

Wymagania wstępne

• Konto , baza danych, kontener i elementy usługi Azure Cosmos DB. Użyj tego samego regionu zarówno dla usługi Azure AI Search, jak i usługi Azure Cosmos DB, aby uzyskać mniejsze opóźnienia i uniknąć opłat za przepustowość.

• Zasady automatycznego indeksowania w kolekcji usługi Azure Cosmos DB są ustawione na Spójne. To jest konfiguracja domyślna. Indeksowanie z opóźnieniem nie jest zalecane i może spowodować brak danych.

• Uprawnienia do odczytu. "Pełny dostęp" parametry połączenia zawiera klucz, który udziela dostępu do zawartości, ale jeśli używasz kontroli dostępu opartej na rolach platformy Azure (Microsoft Entra ID), upewnij się, że tożsamość zarządzana usługi wyszukiwania jest przypisana zarówno rola czytelnika konta usługi Cosmos DB, jak i wbudowana rola czytnika danych usługi Cosmos DB.

• Klient REST do tworzenia źródła danych, indeksu i indeksatora.

Definiowanie źródła danych

Definicja źródła danych określa dane do indeksowania, poświadczeń i zasad identyfikowania zmian w danych. Ź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=2023-11-01
   Content-Type: application/json
   api-key: [Search service admin key]
   {
       "name": "[my-cosmosdb-ds]",
       "type": "cosmosdb",
       "credentials": {
         "connectionString": "AccountEndpoint=https://[cosmos-account-name].documents.azure.com;AccountKey=[cosmos-account-key];Database=[cosmos-database-name]"
       },
       "container": {
         "name": "[my-cosmos-db-collection]",
         "query": null
       },
       "dataChangeDetectionPolicy": {
         "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
       "  highWaterMarkColumnName": "_ts"
       },
       "dataDeletionDetectionPolicy": null,
       "encryptionKey": null,
       "identity": null
   }
   

2. Ustaw wartość "type" na "cosmosdb" (wymagane). Jeśli używasz starszego interfejsu API wyszukiwania w wersji 2017-11-11, składnia "type" to "documentdb". W przeciwnym razie w przypadku wersji 2019-05-06 lub nowszej użyj polecenia "cosmosdb".

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

4. Ustaw wartość "container" na kolekcję. Właściwość "name" jest wymagana i określa identyfikator kolekcji bazy danych do indeksowania. Właściwość "query" jest opcjonalna. Służy do spłaszczania dowolnego dokumentu JSON do płaskiego schematu, który usługa Azure AI Search może indeksować.

5. Ustaw wartość "dataChangeDetectionPolicy" , jeśli dane są nietrwałe i chcesz, aby indeksator pobierał tylko nowe i zaktualizowane elementy w kolejnych uruchomieniach.

6. Ustaw wartość "dataDeletionDetectionPolicy" , jeśli chcesz usunąć dokumenty wyszukiwania z indeksu wyszukiwania po usunięciu elementu źródłowego.

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

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

Unikaj numerów portów w adresie URL punktu końcowego. Jeśli dołączysz numer portu, połączenie zakończy się niepowodzeniem.

Parametry połączenia pełnego dostępu
{ "connectionString" : "AccountEndpoint=https://<Cosmos DB account name>.documents.azure.com;AccountKey=<Cosmos DB auth key>;Database=<Cosmos DB database id>" }'
Możesz uzyskać parametry połączenia ze strony konta usługi Azure Cosmos DB w witrynie Azure Portal, wybierając pozycję Klucze 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.DocumentDB/databaseAccounts/<your cosmos db account name>/;(ApiKind=[api-kind];)/(IdentityAuthType=[identity-auth-type])" }
Ta parametry połączenia nie wymaga klucza konta, ale musisz mieć usługę wyszukiwania, która może łączyć się przy użyciu tożsamości zarządzanej. W przypadku połączeń przeznaczonych dla interfejsu API SQL można pominąć ApiKind z parametry połączenia. Aby uzyskać więcej informacji na temat ApiKindprogramu , IdentityAuthType zobacz Konfigurowanie połączenia indeksatora z bazą danych usługi Azure Cosmos DB przy użyciu tożsamości zarządzanej.

Używanie zapytań do kształtowania indeksowanych danych

We właściwości "query" w obszarze "container" można określić zapytanie SQL w celu spłaszczania zagnieżdżonych właściwości lub tablic, właściwości projektu JSON i filtrowania danych do indeksowania.

Przykładowy dokument:

    {
        "userId": 10001,
        "contact": {
            "firstName": "andy",
            "lastName": "hoh"
        },
        "company": "microsoft",
        "tags": ["azure", "cosmosdb", "search"]
    }

Zapytanie filtru:

SELECT * FROM c WHERE c.company = "microsoft" and c._ts >= @HighWaterMark ORDER BY c._ts

Spłaszczanie zapytania:

SELECT c.id, c.userId, c.contact.firstName, c.contact.lastName, c.company, c._ts FROM c WHERE c._ts >= @HighWaterMark ORDER BY c._ts

Zapytanie projekcji:

SELECT VALUE { "id":c.id, "Name":c.contact.firstName, "Company":c.company, "_ts":c._ts } FROM c WHERE c._ts >= @HighWaterMark ORDER BY c._ts

Zapytanie spłaszczania tablicy:

SELECT c.id, c.userId, tag, c._ts FROM c JOIN tag IN c.tags WHERE c._ts >= @HighWaterMark ORDER BY c._ts

Nieobsługiwane zapytania (DISTINCT i GROUP BY)

Zapytania używające słowa kluczowego DISTINCT lub klauzuli GROUP BY nie są obsługiwane. Usługa Azure AI Search opiera się na stronicowaniu zapytań SQL, aby w pełni wyliczyć wyniki zapytania. Ani klauzule DISTINCT lub GROUP BY nie są zgodne z tokenami kontynuacji używanymi do stronicowania wyników.

Przykłady nieobsługiwanych zapytań:

SELECT DISTINCT c.id, c.userId, c._ts FROM c WHERE c._ts >= @HighWaterMark ORDER BY c._ts

SELECT DISTINCT VALUE c.name FROM c ORDER BY c.name

SELECT TOP 4 COUNT(1) AS foodGroupCount, f.foodGroup FROM Food f GROUP BY f.foodGroup

Mimo że usługa Azure Cosmos DB ma obejście umożliwiające obsługę stronicowania zapytań SQL przy użyciu słowa kluczowego DISTINCT przy użyciu klauzuli ORDER BY, nie jest ona zgodna z usługą Azure AI Search. Zapytanie zwraca pojedynczą wartość JSON, natomiast usługa Azure AI Search oczekuje obiektu JSON.

-- The following query returns a single JSON value and isn't supported by Azure AI Search
SELECT DISTINCT VALUE c.name FROM c ORDER BY c.name

Dodawanie pól wyszukiwania do indeksu

W indeksie wyszukiwania dodaj pola, aby zaakceptować źródłowe dokumenty JSON lub dane wyjściowe projekcji zapytania niestandardowego. Upewnij się, że schemat indeksu wyszukiwania jest zgodny z danymi źródłowymi. W przypadku zawartości w usłudze Azure Cosmos DB schemat indeksu wyszukiwania powinien odpowiadać elementom usługi Azure Cosmos DB w źródle danych.

1. Utwórz lub zaktualizuj indeks , aby zdefiniować pola wyszukiwania, które przechowują dane:

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

2. Utwórz pole klucza dokumentu ("key": true). W przypadku kolekcji partycjonowanych domyślny klucz dokumentu to właściwość usługi Azure Cosmos DB _rid , do której usługa Azure AI Search automatycznie zmienia nazwę rid , ponieważ nazwy pól nie mogą zaczynać się od znaku podkreślenia. Ponadto wartości usługi Azure Cosmos DB _rid zawierają znaki, które są nieprawidłowe w kluczach usługi Azure AI Search. Z tego powodu _rid wartości są zakodowane w formacie Base64.

3. Utwórz więcej pól w celu uzyskania większej zawartości z możliwością wyszukiwania. Aby uzyskać szczegółowe informacje, zobacz Tworzenie indeksu .

Mapowanie typów danych

Typy danych JSON	Typy pól usługi Azure AI Search
Bool	Edm.Boolean, Edm.String
Liczby, które wyglądają jak liczby całkowite	Edm.Int32, Edm.Int64, Edm.String
Liczby, które wyglądają jak zmiennoprzecinkowe	Edm.Double, Edm.String
String	Edm.String
Tablice typów pierwotnych, takich jak ["a", "b", "c"]	Collection(Edm.String)
Ciągi, które wyglądają jak daty	Edm.DateTimeOffset, Edm.String
Obiekty GeoJSON, takie jak { "type": "Point", "coordinates": [long, lat] }	Edm.GeographyPoint
Inne obiekty JSON	Nie dotyczy

Konfigurowanie i uruchamianie indeksatora usługi Azure Cosmos DB

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=2023-11-01
   Content-Type: application/json
   api-key: [search service admin key]
   {
       "name" : "[my-cosmosdb-indexer]",
       "dataSourceName" : "[my-cosmosdb-ds]",
       "targetIndexName" : "[my-search-index]",
       "disabled": null,
       "schedule": null,
       "parameters": {
           "batchSize": null,
           "maxFailedItems": 0,
           "maxFailedItemsPerBatch": 0,
           "base64EncodeKeys": false,
           "configuration": {}
           },
       "fieldMappings": [],
       "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.

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, 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":"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 i zmienionych dokumentów

Gdy indeksator w pełni wypełni indeks wyszukiwania, możesz chcieć, aby kolejne indeksatory stopniowo indeksował tylko nowe i zmienione dokumenty w bazie danych.

Aby włączyć indeksowanie przyrostowe, ustaw właściwość "dataChangeDetectionPolicy" w definicji źródła danych. Ta właściwość informuje indeksator, który mechanizm śledzenia zmian jest używany na danych.

W przypadku indeksatorów usługi Azure Cosmos DB jedynymi obsługiwanymi zasadami jest HighWaterMarkChangeDetectionPolicy użycie _ts właściwości (sygnatury czasowej) udostępnianej przez usługę Azure Cosmos DB.

W poniższym przykładzie przedstawiono definicję źródła danych z zasadami wykrywania zmian:

"dataChangeDetectionPolicy": {
    "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
"  highWaterMarkColumnName": "_ts"
},

Indeksowanie przyrostowe i zapytania niestandardowe

Jeśli używasz zapytania niestandardowego do pobierania dokumentów, upewnij się, że zapytanie porządkuje wyniki według kolumny _ts . Umożliwia to okresowe sprawdzanie, które usługa Azure AI Search używa do zapewnienia przyrostowego postępu w obecności awarii.

W niektórych przypadkach, nawet jeśli zapytanie zawiera klauzulę ORDER BY [collection alias]._ts , usługa Azure AI Search może nie wnioskować, że zapytanie jest uporządkowane przez _tselement . Możesz poinformować usługę Azure AI Search, że wyniki są uporządkowane, ustawiając assumeOrderByHighWaterMarkColumn właściwość konfiguracji.

Aby określić tę wskazówkę, utwórz lub zaktualizuj definicję indeksatora w następujący sposób:

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

Indeksowanie usuniętych dokumentów

Gdy wiersze są usuwane z kolekcji, zwykle chcesz usunąć te wiersze z indeksu wyszukiwania. Celem zasad wykrywania usuwania danych jest efektywne identyfikowanie usuniętych elementów danych. Obecnie jedynymi obsługiwanymi zasadami są Soft Delete zasady (usunięcie jest oznaczone flagą pewnego rodzaju), która jest określona w definicji źródła danych w następujący sposób:

"dataDeletionDetectionPolicy"": {
    "@odata.type" : "#Microsoft.Azure.Search.SoftDeleteColumnDeletionDetectionPolicy",
    "softDeleteColumnName" : "the property that specifies whether a document was deleted",
    "softDeleteMarkerValue" : "the value that identifies a document as deleted"
}

Jeśli używasz zapytania niestandardowego, upewnij się, że właściwość, do której odwołuje się softDeleteColumnName kwerenda, jest przewidywana.

Musi softDeleteColumnName być polem najwyższego poziomu w indeksie. Używanie zagnieżdżonych pól w złożonych typach danych, ponieważ softDeleteColumnName nie jest obsługiwane.

Poniższy przykład tworzy źródło danych z zasadami usuwania nietrwałego:

POST https://[service name].search.windows.net/datasources?api-version=2023-11-01
Content-Type: application/json
api-key: [Search service admin key]

{
    "name": "[my-cosmosdb-ds]",
    "type": "cosmosdb",
    "credentials": {
        "connectionString": "AccountEndpoint=https://[cosmos-account-name].documents.azure.com;AccountKey=[cosmos-account-key];Database=[cosmos-database-name]"
    },
    "container": { "name": "[my-cosmos-collection]" },
    "dataChangeDetectionPolicy": {
        "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
        "highWaterMarkColumnName": "_ts"
    },
    "dataDeletionDetectionPolicy": {
        "@odata.type": "#Microsoft.Azure.Search.SoftDeleteColumnDeletionDetectionPolicy",
        "softDeleteColumnName": "isDeleted",
        "softDeleteMarkerValue": "true"
    }
}

Korzystanie z platformy .NET

Aby uzyskać dostęp do danych za pośrednictwem protokołu interfejsu API SQL, możesz użyć zestawu SDK platformy .NET do automatyzacji za pomocą indeksatorów. Zalecamy zapoznanie się z poprzednimi sekcjami interfejsu API REST, aby poznać pojęcia, przepływ pracy i wymagania. Następnie możesz zapoznać się z następującą dokumentacją referencyjną interfejsu API platformy .NET, aby zaimplementować indeksator JSON w kodzie zarządzanym:

• azure.search.documents.indexes.models.searchindexerdatasourceconnection
• azure.search.documents.indexes.models.searchindexerdatasourcetype
• azure.search.documents.indexes.models.searchindex
• azure.search.documents.indexes.models.searchindexer

Następne kroki

Teraz możesz kontrolować sposób uruchamiania indeksatora, monitorowania stanu lub planowania wykonywania indeksatora. Następujące artykuły dotyczą indeksatorów pobierających zawartość z usługi Azure Cosmos DB:

• Konfigurowanie połączenia indeksatora z bazą danych usługi Azure Cosmos DB przy użyciu tożsamości zarządzanej
• Indeksowanie dużych zestawów danych
• Indeksator dostępu do zawartości chronionej przez funkcje zabezpieczeń sieci platformy Azure