Индексирование данных из Azure Cosmos DB для MongoDB для запросов в Поиск с использованием ИИ Azure (предварительная версия)

Azure Cosmos DB для индексатора MongoDB (предварительная версия) импортирует содержимое из Azure Cosmos DB для MongoDB и делает его доступным для поиска в Поиск с использованием ИИ Azure.

Эта статья дополняет Создание индексатора информацией, относящейся к Cosmos DB. В нем используются ИНТЕРФЕЙСы REST API для демонстрации трех частей рабочего процесса, общего для всех индексаторов: создание источника данных, создание индекса, создание индексатора. Извлечение данных происходит при отправке запроса create Indexer.

Поскольку терминология может быть запутана, стоит отметить, что Azure Cosmos DB индексирование и Поиск с использованием ИИ Azure индексирование являются разными операциями. Индексирование в Поиск с использованием ИИ Azure создает и загружает индекс поиска в службе поиска.

Необходимые условия

• Заполните форму регистрации индексатора предварительной версии. Регистрация автоматически утверждена.

• Учетная запись Azure Cosmos DB, база данных, коллекция и документы. Используйте один и тот же регион для Поиск с использованием ИИ Azure и Azure Cosmos DB для снижения задержки и предотвращения расходов на пропускную способность.

• Политика индексирования автоматическая в коллекции Azure Cosmos DB, установлено на Consistent. Этот параметр является конфигурацией по умолчанию. Отложенное индексирование не рекомендуется и может привести к отсутствием данных.

• Разрешения на чтение. Connection string "полный доступ" включает ключ, предоставляющий доступ к содержимому, но если вы используете роли Azure, убедитесь, что у управляемой идентичности службы search service есть разрешение на роль Читатель учетных записей Cosmos DB.

• Клиент REST для создания источника данных, индекса и индексатора.

Ограничения

Это ограничения этой функции:

• Пользовательские запросы не поддерживаются для указания набора данных.

• Имя _ts столбца — это зарезервированное слово. Если вам нужно это поле, рассмотрите альтернативные решения для заполнения индекса.

• Атрибут $ref MongoDB — это зарезервированное слово. Если это необходимо в коллекции MongoDB, рассмотрите альтернативные решения для заполнения индекса.

В качестве альтернативы этому соединителю, если в вашем сценарии есть какие-либо из этих требований, вы можете использовать Push API/SDK или рассмотреть возможность использования Фабрика данных Azure с индексом Поиск с использованием ИИ Azure в качестве конечного хранилища.

Определение источника данных

Определение источника данных указывает данные для индексирования, учетных данных и политик для выявления изменений в данных. Источник данных определяется как независимый ресурс, чтобы его можно было использовать несколькими индексаторами.

Для этого вызова укажите предварительную версию REST API, чтобы создать источник данных, который подключается через API MongoDB. Вы можете использовать 2020-06-30-preview или более позднюю версию. Рекомендуется использовать последнюю предварительную версию REST API.

1. Создайте или обновите источник данных , чтобы задать его определение:

   POST https://[service name].search.windows.net/datasources?api-version=2026-08-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]"
     },
     "dataChangeDetectionPolicy": {
       "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
       "highWaterMarkColumnName": "_ts"
     },
     "dataDeletionDetectionPolicy": null,
     "encryptionKey": null,
     "identity": null
   }
   

2. Установите «type» на "cosmosdb" (обязательно).

3. Установите "учетные данные" в строку подключения. В следующем разделе описаны поддерживаемые форматы.

4. Задайте для коллекции значение container. Свойство name является обязательным и указывает идентификатор коллекции баз данных для индексирования. Для Azure Cosmos DB для MongoDB запрос не поддерживается.

5. Задайте значение dataChangeDetectionPolicy, если данные являются переменными, и индексатор будет получать только новые и обновленные элементы при последующих запусках.

6. Установите параметр dataDeletionDetectionPolicy, если вы хотите удалить документы поиска из индекса поиска при удалении исходного элемента.

Поддерживаемые учетные данные и строки подключения

Индексаторы могут подключаться к коллекции с помощью следующих подключений. Для подключений, предназначенных для API MongoDB, обязательно включите ApiKind в строка подключения.

Избегайте номеров портов в URL-адресе конечной точки. Если включить номер порта, подключение завершается ошибкой.

Добавление полей поиска в индекс

В индексе поиска добавьте поля, чтобы принять исходные документы JSON или выходные данные пользовательской проекции запроса. Убедитесь, что схема индекса поиска совместима с исходными данными. Для содержимого в Azure Cosmos DB схема индекса поиска должна соответствовать элементам Azure Cosmos DB в источнике данных.

1. Создайте или обновите индекс , чтобы определить поля поиска, в которые хранятся данные:

   POST https://[service name].search.windows.net/indexes?api-version=2026-08-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. Создайте поле ключа документа ("key": true"). Для индекса поиска на основе коллекции MongoDB ключ документа может быть "doc_id", "rid" или другое строковое поле, содержащее уникальные значения. Если имена полей и типы данных одинаковы на обеих сторонах, сопоставление полей не требуется.

   • "doc_id" означает "_id" в качестве идентификатора объекта. Если в индексе указано поле "doc_id", индексатор заполняет его значениями идентификатора объекта.

   • "rid" — это системное свойство в Azure Cosmos DB. Если указать поле "rid" в индексе, индексатор заполняет его значением в кодировке Base64 свойства rid.

   • Для любого другого поля поле поиска должно иметь то же имя, что и в коллекции.

3. Создайте дополнительные поля для более удобного для поиска содержимого. См. статью "Создание индекса" для получения дополнительных сведений.

Сопоставление типов данных

Настройка и запуск Azure Cosmos DB для индексатора MongoDB

После создания индекса и источника данных вы будете готовы к созданию индексатора. Конфигурация индексатора задает входные данные, параметры и свойства, управляющие поведением во время выполнения.

1. Создайте или обновите индексатор , предоставив ему имя и ссылаясь на источник данных и целевой индекс:

   POST https://[service name].search.windows.net/indexers?api-version=2026-08-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. Укажите сопоставления полей , если существуют различия в имени или типе поля, или если в индексе поиска требуется несколько версий исходного поля.

3. Дополнительные сведения о других свойствах см. в статье "Создание индексатора ".

Индексатор запускается автоматически при его создании. Это можно предотвратить, задав для параметра "Отключено" значение true. Чтобы управлять выполнением индексатора, запустите индексатор по запросу или поместите его в расписание.

Проверка состояния индексатора

Чтобы отслеживать состояние индексатора и журнал выполнения, отправьте запрос получения состояния индексатора:

GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2026-08-01-preview
  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
        ]
    }

Журнал выполнения содержит до 50 последних завершенных выполнений, которые сортируются в обратном хронологическом порядке, чтобы последнее выполнение было первым.

Индексирование новых и измененных документов

После полного заполнения индексатора поиска может потребоваться, чтобы последующий индексатор запускался для добавочного индекса только новых и измененных документов в базе данных.

Чтобы включить добавочное индексирование, задайте свойство dataChangeDetectionPolicy в определении источника данных. Это свойство сообщает индексатору, какой механизм отслеживания изменений используется для данных.

Для индексаторов Azure Cosmos DB поддерживается только политика HighWaterMarkChangeDetectionPolicy с помощью свойства _ts (метка времени), предоставленного Azure Cosmos DB.

В следующем примере показано определение источника данных с политикой обнаружения изменений:

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

Индексирование удаленных документов

При удалении строк из коллекции обычно требуется удалить эти строки из индекса поиска. Целью политики обнаружения удаления данных является эффективное определение удаленных элементов данных. В настоящее время единственная поддерживаемая политика — политика Soft Delete (удаление отмечается флагом какого-либо типа), которая указывается в определении источника данных следующим образом:

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

Если вы используете пользовательский запрос, убедитесь, что свойство, на которое ссылается softDeleteColumnName, проецируется запросом.

В следующем примере создается источник данных с политикой обратимого удаления:

POST https://[service name].search.windows.net/datasources?api-version=2026-08-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"
    }
}

Дальнейшие действия

Теперь вы можете управлять запуском индексатора, отслеживанием состояния или запланированным выполнением индексатора. Следующие статьи относятся к индексаторам, которые извлекают содержимое из Azure Cosmos DB.

• Настройка подключения индексатора к базе данных Azure Cosmos DB с помощью управляемого удостоверения
• Индексирование больших наборов данных
• доступ Indexer к содержимому, защищенному функциями безопасности сети Azure