Indexar datos de Azure Cosmos DB para MongoDB para consultas en Búsqueda de Azure AI (versión preliminar)

El Azure Cosmos DB para el indexador de MongoDB (versión preliminar) importa contenido de Azure Cosmos DB para MongoDB y hace que se pueda buscar en Búsqueda de Azure AI.

En este artículo se complementa la creación de un indexador 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 al enviar la solicitud Crear indexador.

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

Requisitos previos

• Complete el formulario de registro de vista previa del indexador. El registro se aprueba automáticamente.

• Una cuenta Azure Cosmos DB, base de datos, colección y documentos. Use la misma región para Búsqueda de Azure AI y Azure Cosmos DB para reducir la latencia y para evitar cargos de ancho de banda.

• Directiva de indexación automática en la colección Azure Cosmos DB, establecida en Consistente. Esta configuración es la configuración predeterminada. No se recomienda la indexación diferida y podría provocar la ausencia de datos.

• 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 REST para crear el origen de datos, el índice y el indexador.

Limitaciones

Estas son las limitaciones de esta característica:

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

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

• El atributo $ref MongoDB es una palabra reservada. Si lo necesita en la 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 Búsqueda de Azure AI como receptor.

Definición del origen de datos

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

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

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

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

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

4. Establezca "contenedor" 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 Azure Cosmos DB para MongoDB, no se admite la consulta.

5. Establezca "dataChangeDetectionPolicy" si los datos son volátiles y desea que el indexador recoja 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 elimina el elemento de origen.

Credenciales admitidas y cadenas de conexión

Los indexadores pueden conectarse a una colección mediante las siguientes conexiones. Para las conexiones que tienen como destino la API de MongoDB, asegúrese de incluir "ApiKind" en el 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 produce un error en la conexió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 de índice de búsqueda sea compatible con los datos de origen. Para el contenido de Azure Cosmos DB, el esquema de índice de búsqueda debe corresponder a los elementos Azure Cosmos DB en el origen de datos.

1. Crear o actualizar un índice para definir campos de búsqueda que almacenan datos:

   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. 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 de objeto. Si especifica un campo de "doc_id" en el índice, el indexador lo rellena con los valores del identificador de 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 se define en la colección.

3. Cree campos adicionales para obtener contenido más buscable. Consulte Creación de un índice para obtener más información.

Mapeo de tipos de datos

Configuración y ejecución del indexador de Azure Cosmos DB para MongoDB

Una vez creado el índice y el origen de datos, está listo para crear el indexador. La configuración del indexador especifica las entradas, los parámetros y las propiedades que controlan los comportamientos de tiempo de ejecución.

1. Cree o actualice un indexador ; para ello, asígnele un nombre y haga referencia al origen de datos y al índice de destino:

   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. Especifique las 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 obtener más información sobre otras propiedades.

Un indexador se ejecuta automáticamente cuando se crea. Para evitarlo, establezca "disabled" en true. Para controlar la ejecución del indexador, ejecute un indexador a petición o colóquelo según una programación.

Comprobación del estado del indexador

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

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

La respuesta incluye el estado y el número de elementos procesados. Debería ser similar al ejemplo siguiente:

    {
        "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 hasta 50 de las ejecuciones completadas más recientemente, que se ordenan en el orden cronológico inverso para que la ejecución más reciente llegue primero.

Indexación de documentos nuevos y modificados

Una vez que un indexador haya rellenado completamente un índice de búsqueda, es posible que desee que el indexador posterior se ejecute para indexar 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.

Para los indexadores de Azure Cosmos DB, la única directiva admitida es la HighWaterMarkChangeDetectionPolicy mediante la propiedad _ts (marca de tiempo) proporcionada por 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 colección, normalmente desea eliminar esas filas del índice de búsqueda también. El propósito de una directiva de detección de eliminación de datos es identificar eficazmente los elementos de datos eliminados. Actualmente, la única directiva admitida es la directiva Soft Delete (la eliminación se indica con algún tipo de marca), que se especifica en la definición del origen de datos de la siguiente manera:

"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 propiedad referenciada por softDeleteColumnName sea proyectada por la consulta.

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

Pasos siguientes

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

• Configurar una conexión de indexador a una base de datos de Azure Cosmos DB usando una identidad administrada
• Indexación de grandes conjuntos de datos
• Acceso del indexador al contenido protegido por las características de seguridad de red de Azure.