Indeksowanie danych z usługi Azure Cosmos DB dla bazy danych MongoDB na potrzeby zapytań w usłudze Azure AI Search

Ważne

Obsługa interfejsu API bazy danych MongoDB jest obecnie dostępna w publicznej wersji zapoznawczej w ramach uzupełniających warunków użytkowania. Obecnie nie ma obsługi zestawu SDK.

W tym artykule dowiesz się, jak skonfigurować indeksator, który importuje zawartość z usługi Azure Cosmos DB dla bazy danych MongoDB 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

• Zarejestruj się, aby uzyskać informacje o wersji zapoznawczej , aby przekazać opinię na temat scenariusza. Dostęp do funkcji można uzyskać automatycznie po przesłaniu formularza.

• Konto, baza danych, kolekcja i dokumenty 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 ról platformy Azure, upewnij się, że tożsamość zarządzana usługi wyszukiwania ma uprawnienia roli Czytelnik konta usługi Cosmos DB.

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

Ograniczenia

Są to ograniczenia tej funkcji:

• Zapytania niestandardowe nie są obsługiwane do określania zestawu danych.

• Nazwa _ts kolumny jest słowem zarezerwowanym. Jeśli potrzebujesz tego pola, rozważ alternatywne rozwiązania do wypełniania indeksu.

• Atrybut $ref Bazy danych MongoDB jest słowem zastrzeżonym. Jeśli potrzebujesz tego w kolekcji bazy danych MongoDB, rozważ alternatywne rozwiązania do wypełniania indeksu.

Alternatywą dla tego łącznika, jeśli twój scenariusz ma jakiekolwiek z tych wymagań, możesz użyć interfejsu API wypychania/zestawu SDK lub rozważyć usługę Azure Data Factory z indeksem usługi Azure AI Search jako ujściem.

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 jest definiowane jako niezależny zasób, dzięki czemu może być używane przez wiele indeksatorów.

Dla tego wywołania określ wersję zapoznawczą interfejsu API REST. Możesz użyć wersji 2020-06-30-preview lub nowszej, aby utworzyć źródło danych łączące się za pośrednictwem interfejsu API bazy danych MongoDB. Zalecamy najnowszą wersję zapoznawczą interfejsu API REST.

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

   POST https://[service name].search.windows.net/datasources?api-version=2024-05-01-preview
   Content-Type: application/json
   api-key: [Search service admin key]
   {
     "name": "[my-cosmosdb-mongodb-ds]",
     "type": "cosmosdb",
     "credentials": {
       "connectionString": "AccountEndpoint=https://[cosmos-account-name].documents.azure.com;AccountKey=[cosmos-account-key];Database=[cosmos-database-name];ApiKind=MongoDb;"
     },
     "container": {
       "name": "[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).

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 przypadku usługi Azure Cosmos DB dla bazy danych MongoDB "zapytanie" nie jest obsługiwane.

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ń. W przypadku połączeń przeznaczonych dla interfejsu API bazy danych MongoDB należy uwzględnić element "ApiKind" w parametry połączenia.

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>;ApiKind=MongoDb" }
Klucz uwierzytelniania usługi Cosmos DB można pobrać ze strony konta usługi Azure Cosmos DB w witrynie Azure Portal, wybierając pozycję Parametry połączenia w okienku nawigacji po lewej stronie. Pamiętaj, aby skopiować hasło podstawowe i zastąpić wartość klucza uwierzytelniania usługi Cosmos DB.

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];)" }
Ta parametry połączenia nie wymaga klucza konta, ale musisz wcześniej skonfigurować usługę wyszukiwania, aby nawiązać połączenie przy użyciu tożsamości zarządzanej i utworzyć przypisanie roli, które przyznaje uprawnienia roli czytelnika konta usługi Cosmos DB. Aby uzyskać więcej informacji, zobacz Konfigurowanie połączenia indeksatora z bazą danych usługi Azure Cosmos DB przy użyciu tożsamości zarządzanej.

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 będą przechowywać dane:

   POST https://[service name].search.windows.net/indexes?api-version=2024-05-01-preview
   Content-Type: application/json
   api-key: [Search service admin key]
   
   {
       "name": "mysearchindex",
       "fields": [{
           "name": "doc_id",
           "type": "Edm.String",
           "key": true,
           "retrievable": 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 indeksu wyszukiwania opartego na kolekcji bazy danych MongoDB klucz dokumentu może mieć wartość "doc_id", "rid" lub inne pole ciągu zawierające unikatowe wartości. Jeśli nazwy pól i typy danych są takie same po obu stronach, nie są wymagane żadne mapowania pól.

   • Wyrażenie "doc_id" reprezentuje wartość "_id" dla identyfikatora obiektu. Jeśli określisz pole "doc_id" w indeksie, indeksator wypełni go wartościami identyfikatora obiektu.

   • "rid" to właściwość systemowa w usłudze Azure Cosmos DB. Jeśli określisz pole "rid" w indeksie, indeksator wypełni go wartością zakodowaną w formacie base64 właściwości "rid".

   • W przypadku dowolnego innego pola wyszukiwania pole powinno mieć taką samą nazwę jak zdefiniowana w kolekcji.

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

Mapowanie typów danych

Typ 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 dla bazy danych MongoDB

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=2024-05-01-preview
   Content-Type: application/json
   api-key: [search service admin key]
   {
       "name" : "[my-cosmosdb-indexer]",
       "dataSourceName" : "[my-cosmosdb-mongodb-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=2024-05-01-preview
  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 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.

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

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

{
    "name": ["my-cosmosdb-mongodb-ds]",
    "type": "cosmosdb",
    "credentials": {
        "connectionString": "AccountEndpoint=https://[cosmos-account-name].documents.azure.com;AccountKey=[cosmos-account-key];Database=[cosmos-database-name];ApiKind=MongoDB"
    },
    "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"
    }
}

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