Индексирование данных из Azure Cosmos DB для MongoDB для запросов в службе "Поиск ИИ Azure"

Статья
09/01/2024

Внимание

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

Из этой статьи вы узнаете, как настроить индексатор , который импортирует содержимое из 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 установите значение "Согласованный". Это конфигурация по умолчанию. Отложенное индексирование не рекомендуется и может привести к отсутствием данных.
Разрешения на чтение. Строка подключения "полный доступ" включает ключ, предоставляющий доступ к содержимому, но если вы используете роли Azure, убедитесь, что у управляемого удостоверения службы поиска есть разрешения для чтения учетных записей Cosmos DB.
Клиент REST для создания источника данных, индекса и индексатора.

Ограничения

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

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

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

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

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

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

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

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
}

Задайте для параметра type "cosmosdb" (обязательный).
Задайте для параметра "Учетные данные" значение строка подключения. В следующем разделе описаны поддерживаемые форматы.
Задайте для коллекции значение container. Свойство name является обязательным и указывает идентификатор коллекции баз данных для индексирования. Для Azure Cosmos DB для MongoDB "запрос" не поддерживается.
Задайте значение dataChangeDetectionPolicy, если данные являются переменными, и индексатор будет получать только новые и обновленные элементы при последующих запусках.
Установите параметр dataDeletionDetectionPolicy, если вы хотите удалить документы поиска из индекса поиска при удалении исходного элемента.

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

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

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

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

Полный доступ строка подключения
`{ "connectionString" : "AccountEndpoint=https://<Cosmos DB account name>.documents.azure.com;AccountKey=<Cosmos DB auth key>;Database=<Cosmos DB database id>;ApiKind=MongoDb" }`
Ключ проверки подлинности Cosmos DB можно получить на странице учетной записи Azure Cosmos DB в портал Azure, выбрав строку подключения в области навигации слева. Обязательно скопируйте первичный пароль и замените значение ключа проверки подлинности Cosmos DB на него.

{ "connectionString" : "AccountEndpoint=https://<Cosmos DB account name>.documents.azure.com;AccountKey=<Cosmos DB auth key>;Database=<Cosmos DB database id>;ApiKind=MongoDb" }

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

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

Управляемое удостоверение строка подключения
`{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.DocumentDB/databaseAccounts/<your cosmos db account name>/;(ApiKind=[api-kind];)" }`
Для этого строка подключения не требуется ключ учетной записи, но необходимо настроить службу поиска для подключения с помощью управляемого удостоверения и создать назначение ролей, которое предоставляет разрешения роли чтения учетных записей Cosmos DB. Дополнительные сведения см. в статье "Настройка подключения индексатора к базе данных Azure Cosmos DB с помощью управляемого удостоверения ".

{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.DocumentDB/databaseAccounts/<your cosmos db account name>/;(ApiKind=[api-kind];)" }

Для этого строка подключения не требуется ключ учетной записи, но необходимо настроить службу поиска для подключения с помощью управляемого удостоверения и создать назначение ролей, которое предоставляет разрешения роли чтения учетных записей Cosmos DB. Дополнительные сведения см. в статье "Настройка подключения индексатора к базе данных Azure Cosmos DB с помощью управляемого удостоверения ".

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

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

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

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

Создайте поле ключа документа ("key": true"). Для индекса поиска на основе коллекции MongoDB ключ документа может быть "doc_id", "rid" или другое строковое поле, содержащее уникальные значения. Если имена полей и типы данных одинаковы на обеих сторонах, сопоставление полей не требуется.
- "doc_id" представляет "_id" для идентификатора объекта. Если в индексе указано поле "doc_id", индексатор заполняет его значениями идентификатора объекта.
- "rid" — это системное свойство в Azure Cosmos DB. Если указать поле "rid" в индексе, индексатор заполняет его значением в кодировке Base64 свойства rid.
- Для любого другого поля поле поиска должно иметь то же имя, что и в коллекции.
Создайте дополнительные поля для более доступных для поиска содержимого. Дополнительные сведения см. в статье "Создание индекса ".

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

Тип данных JSON	Типы полей поиска ИИ Azure
Bool	Edm.Boolean, Edm.String
Числа, которые выглядят как целые числа	Edm.Int32, Edm.Int64, Edm.String
Числа, которые выглядят как числа с плавающей запятой	Edm.Double, Edm.String
Строка	Edm.String
Массивы примитивных типов, таких как ["a", "b", "c"]	Collection(Edm.String)
Строки, которые выглядят как даты	Edm.DateTimeOffset, Edm.String
Объекты GeoJSON, такие как { type: Point, "координаты": [long, lat] }	Edm.GeographyPoint
Другие объекты JSON	Н/П

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

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

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

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
}

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

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

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

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

GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2024-05-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=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"
    }
}

Следующие шаги

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

Поделиться через