Индексирование данных из Azure Cosmos DB с помощью API MongoDB

  • Статья
  • Чтение занимает 7 мин

Важно!

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

Из этой статьи вы узнаете, как настроить индексатор , который импортирует содержимое с помощью API MongoDB из Azure Cosmos DB.

Эта статья дополняет создание индексатора сведениями, характерными для API MongoDB Cosmos DB. Он использует REST API для демонстрации трехкомпонентного рабочего процесса, общего для всех индексаторов: создание источника данных, создание индекса, создание индексатора. Извлечение данных происходит при отправке запроса create Indexer.

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

Обязательные условия

Ограничения

Ниже перечислены ограничения этой функции.

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

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

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

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

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

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

    POST https://[service name].search.windows.net/datasources?api-version=2021-04-30-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. Задайте для "type" "cosmosdb" значение (обязательно).

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

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

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

  6. Если вы хотите удалить документы поиска из индекса поиска при удалении исходного элемента, задайте значение 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 можно получить на странице учетной записи 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 . Дополнительные сведения см . в статье "Настройка подключения индексатора к базе данных Cosmos DB с помощью управляемого удостоверения ".

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

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

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

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

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

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

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

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

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

Тип данных JSON Типы полей Когнитивного поиска
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", "coordinates": [long, lat] } Edm.GeographyPoint
Другие объекты JSON Н/Д

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

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

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

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

Для индексаторов Cosmos DB единственной поддерживаемой политикой является HighWaterMarkChangeDetectionPolicy использование _ts свойства (timestamp), предоставляемого 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=2020-06-30
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: