Индексирование данных из Azure Cosmos DB для NoSQL для запросов в поиске ИИ Azure

Статья
01/18/2024

Из этой статьи вы узнаете, как настроить индексатор , который импортирует содержимое из Azure Cosmos DB для NoSQL и делает его доступным для поиска в Azure AI Search.

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

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

Необходимые компоненты

Учетная запись Azure Cosmos DB, база данных, контейнер и элементы. Используйте один и тот же регион для поиска ИИ Azure и Azure Cosmos DB для снижения задержки и для предотвращения расходов на пропускную способность.
Политика автоматического индексирования в коллекции Azure Cosmos DB установите значение "Согласованный". Это конфигурация по умолчанию. Отложенное индексирование не рекомендуется и может привести к отсутствием данных.
Разрешения на чтение. Строка подключения "полный доступ" включает ключ, который предоставляет доступ к содержимому, но если вы используете Azure RBAC (идентификатор Microsoft Entra ID), убедитесь, что управляемое удостоверение службы поиска назначено как роль читателя учетной записи Cosmos DB, так и встроенная роль чтения данных Cosmos DB.
Клиент REST для создания источника данных, индекса и индексатора.

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

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

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

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
}

Задайте для параметра type "cosmosdb" (обязательный). Если вы используете более старый API поиска версии 2017-11-11, используется "documentdb"синтаксис типа. В противном случае для 2019-05-06 и более поздних версий используйте "cosmosdb".
Задайте для параметра "Учетные данные" значение строка подключения. В следующем разделе описаны поддерживаемые форматы.
Задайте для коллекции значение container. Свойство name является обязательным и указывает идентификатор коллекции баз данных для индексирования. Свойство query является необязательным. Используйте его для выравнивания произвольного документа JSON в неструктурированной схеме, которую может индексировать поиск ИИ Azure.
Задайте значение dataChangeDetectionPolicy, если данные являются переменными, и индексатор будет получать только новые и обновленные элементы при последующих запусках.
Установите параметр dataDeletionDetectionPolicy, если вы хотите удалить документы поиска из индекса поиска при удалении исходного элемента.

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

Индексаторы могут подключаться к коллекции с помощью следующих подключений.

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

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

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

Управляемое удостоверение строка подключения
`{ "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])" }`
Для этого строка подключения не требуется ключ учетной записи, но у вас должна быть служба поиска, которая может подключаться с помощью управляемого удостоверения. Для подключений, предназначенных для API SQL, можно исключить `ApiKind` из строка подключения. Дополнительные сведения см. в `ApiKindIdentityAuthType` статье "Настройка подключения индексатора к базе данных 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];)/(IdentityAuthType=[identity-auth-type])" }

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

Использование запросов для формирования индексированных данных

В свойстве query в разделе "контейнер" можно указать SQL-запрос для плоских вложенных свойств или массивов, свойств проекта JSON и отфильтровать данные для индексирования.

Пример документа:

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

Запрос на фильтрацию:

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

Преобразование запросов:

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

Запрос на проектирование:

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

Массив преобразованных запросов:

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

Неподдерживаемые запросы (DISTINCT и GROUP BY)

Запросы, использующие предложение DISTINCT ключевое слово или GROUP BY, не поддерживаются. Поиск ИИ Azure использует разбиение на страницы SQL-запроса, чтобы полностью перечислить результаты запроса. Ни предложения DISTINCT ключевое слово или GROUP BY не совместимы с маркерами продолжения, используемыми для получения результатов разбивки на страницы.

Примеры неподдерживаемых запросов

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

Несмотря на то, что Azure Cosmos DB имеет обходное решение для поддержки разбиения запросов SQL с помощью инструкции DISTINCT ключевое слово с помощью предложения ORDER BY, оно несовместимо с поиском ИИ Azure. Запрос возвращает одно значение JSON, в то время как служба "Поиск ИИ Azure" ожидает объект 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

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

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

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

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

Создайте поле ключа документа ("key": true"). Для секционированных коллекций ключ документа по умолчанию — это свойство Azure Cosmos DB _rid , в которое служба "Поиск ИИ Azure" автоматически переименовывается rid , так как имена полей не могут начинаться с символа подчеркивания. Кроме того, значения Azure Cosmos DB _rid содержат символы, недопустимые в ключах поиска ИИ Azure. Поэтому значения _rid представлены в кодировке Base64.
Создайте дополнительные поля для более доступных для поиска содержимого. Дополнительные сведения см. в статье "Создание индекса ".

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

Типы данных 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 для NoSQL

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

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

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
}

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

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

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

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

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

Добавочное индексирование и пользовательские запросы

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

В некоторых случаях, даже если запрос содержит ORDER BY [collection alias]._ts предложение, поиск ИИ Azure может не определить порядок _tsзапроса. Вы можете сообщить Службе поиска ИИ Azure, что результаты упорядочены, задав assumeOrderByHighWaterMarkColumn свойство конфигурации.

Чтобы указать это указание, создайте или обновите определение индексатора следующим образом:

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

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

Строки, удаляемые из исходной коллекции, вероятно, также следует удалить из индекса поиска. Политика обнаружения удаления данных предназначена для эффективного определения удаленных элементов данных. В настоящее время единственная поддерживаемая политика — 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 ссылается ссылка, проецируется запросом.

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

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

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

Использование .NET

Для доступа к данным через протокол API SQL можно использовать пакет SDK для .NET для автоматизации с помощью индексаторов. Мы рекомендуем ознакомиться с предыдущими разделами REST API, чтобы узнать о понятиях, рабочих процессах и требованиях. Затем можно обратиться к следующей справочной документации по API .NET, чтобы реализовать индексатор JSON в управляемом коде:

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

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