Indizador de datos de Azure Cosmos DB for MongoDB para consultas en Búsqueda de Azure AI

Importante

La compatibilidad con la API de MongoDB se encuentra actualmente en versión preliminar pública en los Términos de uso complementarios. Actualmente, no hay compatibilidad con el SDK.

En este artículo aprenderá a configurar un indexador que importa contenido de Azure Cosmos DB for MongoDB y permite que se realicen búsquedas en Azure AI Search.

Este artículo complementa al artículo Creación de indexadores con información específica de Cosmos DB. Usa las API REST para mostrar un flujo de trabajo de tres partes común a todos los indexadores: crear un origen de datos, crear un índice y crear un indexador. La extracción de datos se produce cuando se envía la solicitud para crear un indexador.

Dado que la terminología puede ser confusa, merece la pena tener en cuenta que la indexación de Azure Cosmos DB y la indexación de Azure AI Search son operaciones diferentes. La indexación en Azure AI Search crea y carga un índice de búsqueda en el servicio de búsqueda.

Requisitos previos

• Regístrese para obtener la versión preliminar y proporcionar comentarios sobre escenarios. Puede acceder a la característica automáticamente después del envío del formulario.

• Una cuenta, una base de datos, una colección y documentos de Azure Cosmos DB. Puede usar la misma región tanto para Azure AI Search como para Azure Cosmos DB para reducir la latencia y evitar los cargos debido al consumo de ancho de banda.

• Una directiva de indexación automática en la colección de Azure Cosmos DB, establecida en Coherente. Esta es la configuración predeterminada. No se recomienda la indexación diferida, ya que puede dar lugar a que falte información.

• Permisos de lectura. Una cadena de conexión de "acceso completo" incluye una clave que concede acceso al contenido, pero si usa roles de Azure, asegúrese de que la identidad administrada del servicio de búsqueda disponga de permisos de rol de lector de cuentas de Cosmos DB.

• Un cliente de REST para crear el origen de datos, el índice y el indexador.

Limitaciones

Esta característica tiene las limitaciones siguientes:

• No se admiten consultas personalizadas para especificar el conjunto de datos.

• El nombre de columna _ts es una palabra reservada. Si necesita este campo, considere soluciones alternativas para rellenar un índice.

• El atributo $ref de MongoDB es una palabra reservada. Si la necesita en su colección de MongoDB, considere la posibilidad de soluciones alternativas para rellenar un índice.

Como alternativa a este conector, si el escenario tiene cualquiera de esos requisitos, puede usar la API o el SDK de inserción o considerar Azure Data Factory con un índice de Azure AI Search como receptor.

Definición del origen de datos

La definición del origen de datos especifica los datos que se indexan, las credenciales y las directivas para identificar los cambios en los datos. Un origen de datos se define como un recurso independiente de forma que puedan usarlo varios indexadores.

Para esta llamada, especifique una versión preliminar de la API de REST. Puede usar 2020-06-30-preview o posterior para crear un origen de datos que se conecte a través de la API de MongoDB. Se recomienda la versión preliminar más reciente de la API de REST.

1. Cree o actualice un origen de datos para establecer su definición:

   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. Establezca "type" en "cosmosdb" (obligatorio).

3. Establezca "credentials" en una cadena de conexión. En la sección siguiente se describen los formatos admitidos.

4. Establezca "container" en la colección. La propiedad "name" es necesaria y especifica el identificador de la colección de base de datos que se va a indexar. En el caso de Azure Cosmos DB for MongoDB, no se admite "query".

5. Establezca "dataChangeDetectionPolicy" si los datos son volátiles y desea que el indexador seleccione solo los elementos nuevos y actualizados en ejecuciones posteriores.

6. Establezca "dataDeletionDetectionPolicy" si desea quitar documentos de búsqueda de un índice de búsqueda cuando se elimine el elemento de origen.

Credenciales y cadenas de conexión admitidas

Los indexadores pueden conectarse a una colección mediante las siguientes conexiones. Para las conexiones que se dirigen a MongoDB API, asegúrese de incluir "ApiKind" en la cadena de conexión.

Evite los números de puerto en la dirección URL del punto de conexión. Si incluye el número de puerto, se producirá un error en la conexión.

Cadena de conexión de acceso completo
{ "connectionString" : "AccountEndpoint=https://<Cosmos DB account name>.documents.azure.com;AccountKey=<Cosmos DB auth key>;Database=<Cosmos DB database id>;ApiKind=MongoDb" }
Puede obtener la clave de autentificación de Cosmos DB desde la página de la cuenta de Azure Cosmos DB en Azure Portal, al seleccionar Cadena de conexión en el panel de navegación izquierdo. Asegúrate de copiar la contraseña principal y reemplazar el valor de la clave de autenticación de Cosmos DB con ella.

Cadena de conexión de identidad administrada
{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.DocumentDB/databaseAccounts/<your cosmos db account name>/;(ApiKind=[api-kind];)" }
Esta cadena de conexión no requiere una clave de cuenta, pero debe haber configurado previamente un servicio de búsqueda para conectarse mediante una identidad administrada y haber creado una asignación de roles que conceda permisos de rol de lector de la cuenta de Cosmos DB. Consulte Configuración de una conexión de indexador a una base de datos de Azure Cosmos DB mediante una identidad administrada para más información.

Adición de campos de búsqueda a un índice

En un índice de búsqueda, agregue campos para aceptar los documentos JSON de origen o la salida de la proyección de consulta personalizada. Asegúrese de que el esquema del índice de búsqueda sea compatible con los datos de origen. En el caso del contenido de Azure Cosmos DB, el esquema del índice de búsqueda se debe corresponder con los elementos de Azure Cosmos DB del origen de datos.

1. Cree o actualice un índice para definir campos de búsqueda que almacenarán los datos:

   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. Cree un campo de clave de documento ("key": true). Para un índice de búsqueda basado en una colección de MongoDB, la clave del documento puede ser "doc_id", "rid" o algún otro campo de cadena que contenga valores únicos. Siempre que los nombres de campo y los tipos de datos sean los mismos en ambos lados, no se requieren asignaciones de campos.

   • "doc_id" representa "_id" para el identificador del objeto. Si especifica un campo "doc_id" en el índice, el indexador lo rellena con los valores del identificador del objeto.

   • "rid" es una propiedad del sistema en Azure Cosmos DB. Si especifica un campo de "rid" en el índice, el indexador lo rellena con el valor codificado en base64 de la propiedad "rid".

   • Para cualquier otro campo, el campo de búsqueda debe tener el mismo nombre que el definido en la colección.

3. Cree campos adicionales para obtener más contenido que se puede buscar. Consulte Creación de un índice en Azure Cognitive Search para más información.

Asignación de tipos de datos

Tipo de datos JSON	Tipos de campos de Azure AI Search
Booleano	Edm.Boolean, Edm.String
Números que parecen enteros	Edm.Int32, Edm.Int64, Edm.String
Números que parecen puntos flotantes	Edm.Double, Edm.String
String	Edm.String
Matrices de tipos primitivos, como ["a", "b", "c"]	Collection(Edm.String)
Cadenas que parecen fechas	Edm.DateTimeOffset, Edm.String
Objetos GeoJSON, como { "type": "Point", "coordinates": [long, lat] }	Edm.GeographyPoint
Otros objetos JSON	N/D

Configuración y ejecución del indizador Azure Cosmos DB for MongoDB

Una vez creados el índice y el origen de datos, ya podrá crear el indexador. La configuración del indexador especifica las entradas, los parámetros y las propiedades que controlan los comportamientos en tiempo de ejecución.

1. Cree o actualice un indexador asignándole un nombre y haciendo referencia al origen de datos y al índice de destino:

   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. Especifique asignaciones de campos si hay diferencias en el nombre o el tipo de campo, o si necesita varias versiones de un campo de origen en el índice de búsqueda.

3. Consulte Creación de un indexador para más información sobre otras propiedades.

Un indexador se ejecuta automáticamente cuando se crea. Puede evitarlo estableciendo el valor de "disabled" en true. Para controlar la ejecución del indexador, ejecute un indexador a petición o prográmelo.

Comprobación del estado del indexador

Para supervisar el estado del indexador y el historial de ejecución, envíe una solicitud para Obtener el estado del indexador:

GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2024-05-01-preview
  Content-Type: application/json  
  api-key: [admin key]

La respuesta incluye el estado y el número de elementos procesados. Debe tener un aspecto similar al siguiente ejemplo:

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

El historial de ejecución contiene como máximo las 50 ejecuciones completadas más recientemente en orden cronológico inverso (la ejecución más reciente aparece en primer lugar).

Indexación de documentos nuevos y modificados

Una vez que un indexador ha rellenado por completo un índice de búsqueda, es posible que quiera que las ejecuciones posteriores del indexador indexen incrementalmente solo los documentos nuevos y modificados de la base de datos.

Para habilitar la indexación incremental, establezca la propiedad "dataChangeDetectionPolicy" en la definición del origen de datos. Esta propiedad indica al indexador qué mecanismo de seguimiento de cambios se usa en los datos.

En el caso de los indexadores de Azure Cosmos DB, la única directiva compatible es HighWaterMarkChangeDetectionPolicy con la propiedad _ts (marca de tiempo) que proporciona Azure Cosmos DB.

En el ejemplo siguiente se muestra una definición de origen de datos con una directiva de detección de cambios:

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

Indexación de documentos eliminados

Cuando se eliminan filas de la recopilación, lo habitual es que también se deseen eliminar del índice de búsqueda. El fin de una directiva de detección de eliminación de datos es identificar eficazmente los elementos de datos eliminados. Actualmente, solo se admite la directiva Soft Delete (la eliminación se indica con algún tipo de marca), especificada de la siguiente forma en el origen de datos:

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

Si usa una consulta personalizada, asegúrese de que la consulta proyecte la propiedad a la que hace referencia softDeleteColumnName.

En el ejemplo siguiente se crea un origen de datos con una directiva de eliminación temporal:

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

Pasos siguientes

Ahora puede controlar cómo ejecutar el indexador, supervisar el estado o programar la ejecución del indexador. Los siguientes artículos se aplican a los indexadores que extraen contenido de Azure Cosmos DB:

• Configuración de una conexión de indexador a una base de datos de Azure Cosmos DB mediante una identidad administrada
• Indexar grandes conjuntos de datos
• Acceso del indexador al contenido protegido mediante las características de seguridad de red de Azure