Conexión de Cosmos DB con Azure Search mediante indexadoresConnecting Cosmos DB with Azure Search using indexers

En este artículo, aprenderá a:In this article, learn how to:

  • Configure un indexador de Azure Search que utilice una colección de Azure Cosmos DB como origen de datos.Configure Azure Search indexer that uses an Azure Cosmos DB collection as a data source.
  • Crear un índice de búsqueda con los tipos de datos compatibles con JSON.Create a search index with JSON-compatible data types.
  • Configurar un indexador para la indexación periódica y bajo demanda.Configure an indexer for on-demand and recurring indexing.
  • Actualizar incrementalmente el índice basado en cambios en los datos subyacentes.Incrementally refresh the index based on changes in the underlying data.

Nota

Azure Cosmos DB es la siguiente generación de DocumentDB.Azure Cosmos DB is the next generation of DocumentDB. Aunque se cambie el nombre de producto, la sintaxis documentdb de los indexadores de Azure Search todavía existe en las páginas de Azure Portal y de las API de Azure Search para la compatibilidad con versiones anteriores.Although the product name is changed, the documentdb syntax in Azure Search indexers still exists for backwards compatibility in both the Azure Search APIs and portal pages. Cuando configure los indexadores, no olvide especificar la sintaxis documentdb tal como se indica en este artículo.When configuring indexers, be sure to specify the documentdb syntax as instructed in this article.

En el siguiente vídeo, Andrew Liu, administrador de programas de Azure Cosmos DB, muestra cómo agregar un índice de Azure Search a un contenedor de Azure Cosmos DB.In the following video, Azure Cosmos DB Program Manager Andrew Liu demonstrates how to add an Azure Search index to an Azure Cosmos DB container.

Tipos admitidos de APISupported API types

Aunque Azure Cosmos DB admite una amplia variedad de modelos de datos y API, la compatibilidad de producción del indexador de Azure Search se extiende solamente a SQL API.Although Azure Cosmos DB supports a variety of data models and APIs, Azure Search indexer production support extends to the SQL API only. La compatibilidad con la API de MongoDB está actualmente en versión preliminar pública.Support for MongoDB API is currently in public preview.

Próximamente estará disponible la compatibilidad con API adicionales.Support for additional APIs is forthcoming. Para ayudarnos priorizar cuáles admitir en primer lugar, vaya al sitio web UserVoice y vote su opción:To help us prioritize which ones to support first, please cast your vote on the User Voice web site:

Requisitos previosPrerequisites

Además de una cuenta de Cosmos DB, debe tener un servicio de Azure Search.In addition to a Cosmos DB account, you need to have a Azure Search service.

En la cuenta de Cosmos DB, puede elegir si desea que la recopilación indexe automáticamente todos los documentos.In your Cosmos DB account you can choose whether you want the collection to automatically index all documents. De forma predeterminada, todos los documentos se indexan automáticamente, pero puede desactivar la indexación automática.By default, all documents are automatically indexed, but you can turn off automatic indexing. Cuando se desactiva la indexación, solo se puede acceder a los documentos a través de sus propios vínculos o mediante su identificador.When indexing is turned off, documents can be accessed only through their self-links or by queries by using the document ID. Azure Search necesita que se active la indexación automática de Cosmos DB en la colección que Azure Search va a indexar.Azure Search requires Cosmos DB automatic indexing to be turned on in the collection that will be indexed by Azure Search.

Conceptos del indexador de Azure SearchAzure Search indexer concepts

A origen de datos especifica los datos para indexar, las credenciales y las directivas para identificar cambios en los datos (por ejemplo, los documentos modificados o eliminados dentro de la colección).A data source specifies the data to index, credentials, and policies for identifying changes in the data (such as modified or deleted documents inside your collection). El origen de datos se define como un recurso independiente para que puedan usarlo múltiples indizadores.The data source is defined as an independent resource so that it can be used by multiple indexers.

Un indizador describe cómo fluyen los datos desde el origen de datos a un índice de búsqueda de destino.An indexer describes how the data flows from your data source into a target search index. Los indexadores se pueden utilizar para:An indexer can be used to:

  • Realizar una copia única de los datos para rellenar un índice.Perform a one-time copy of the data to populate an index.
  • Sincronizar un índice con los cambios del origen de datos en una programación.Sync an index with changes in the data source on a schedule.
  • Invocar actualizaciones a petición para un índice según sea necesario.Invoke on-demand updates to an index as needed.

Para configurar un indexador de Azure Cosmos DB, es preciso crear un índice, un origen de datos y, por último, el indexador.To set up an Azure Cosmos DB indexer, you need to create an index, datasource, and finally the indexer. Para crear estos objetos, se pueden usar el portal, el SDK de .NET o la API de REST.You can create these objects using the portal, .NET SDK, or REST API.

En este artículo se muestra cómo usar la API de REST.This article shows how to use the REST API. Si opta por usar el portal, el Asistente para la importación de datos le guiará a través de la creación de estos recursos, incluyendo el índice.If you opt for the portal, the Import data wizard guides you through the creation of all these resources, including the index.

Sugerencia

Puede iniciar el asistente para importar datos desde el panel de Azure Cosmos DB para simplificar la indexación para ese origen de datos.You can launch the Import data wizard from the Azure Cosmos DB dashboard to simplify indexing for that data source. En el panel de navegación de la izquierda, vaya a Colecciones > Add Azure Search (Añadir búsqueda de Azure) para empezar.In left-navigation, go to Collections > Add Azure Search to get started.

Nota

Por ahora, no puede crear ni editar orígenes de datos de MongoDB mediante Azure Portal ni el SDK de .NET.For now, you cannot create or edit MongoDB data sources using Azure Portal or the .NET SDK. Sin embargo, se puede supervisar el historial de ejecución de los indexadores de MongoDB en el portal.However, you can monitor execution history of MongoDB indexers in the portal.

Paso 1: Creación de un origen de datosStep 1: Create a data source

Pasos para crear un origen de datos, realice un POST:To create a data source, do a POST:

POST https://[service name].search.windows.net/datasources?api-version=2017-11-11
Content-Type: application/json
api-key: [Search service admin key]

{
    "name": "mydocdbdatasource",
    "type": "documentdb",
    "credentials": {
        "connectionString": "AccountEndpoint=https://myCosmosDbEndpoint.documents.azure.com;AccountKey=myCosmosDbAuthKey;Database=myCosmosDbDatabaseId"
    },
    "container": { "name": "myCollection", "query": null },
    "dataChangeDetectionPolicy": {
        "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
        "highWaterMarkColumnName": "_ts"
    }
}

El cuerpo de la solicitud contiene la definición del origen de datos, que debe incluir los siguientes campos:The body of the request contains the data source definition, which should include the following fields:

  • nombre: elija un nombre para representar la base de datos.name: Choose any name to represent your database.
  • type: debe ser documentdb.type: Must be documentdb.
  • credenciales:credentials:

    • connectionString: obligatorio.connectionString: Required. Especifique la información de conexión a la base de datos de Azure Cosmos DB con el formato siguiente: AccountEndpoint=<Cosmos DB endpoint url>;AccountKey=<Cosmos DB auth key>;Database=<Cosmos DB database id> Para colecciones de MongoDB, agregue ApiKind=MongoDb a la cadena de conexión: AccountEndpoint=<Cosmos DB endpoint url>;AccountKey=<Cosmos DB auth key>;Database=<Cosmos DB database id>;ApiKind=MongoDbSpecify the connection info to your Azure Cosmos DB database in the following format: AccountEndpoint=<Cosmos DB endpoint url>;AccountKey=<Cosmos DB auth key>;Database=<Cosmos DB database id> For MongoDB collections, add ApiKind=MongoDb to the connection string: AccountEndpoint=<Cosmos DB endpoint url>;AccountKey=<Cosmos DB auth key>;Database=<Cosmos DB database id>;ApiKind=MongoDb Evite los números de puerto en la dirección URL del punto de conexión.Avoid port numbers in the endpoint url. Si incluye el número de puerto, Azure Search no podrá indexar la base de datos de Azure Cosmos DB.If you include the port number, Azure Search will be unable to index your Azure Cosmos DB database.
  • contenedor:container:

    • nombre: obligatorio.name: Required. Especifique el id. de la colección de la base de datos que se va a indexar.Specify the id of the database collection to be indexed.
    • consulta: opcional.query: Optional. Puede especificar una consulta para acoplar un documento JSON arbitrario en un esquema plano que Azure Search pueda indizar.You can specify a query to flatten an arbitrary JSON document into a flat schema that Azure Search can index. Para las colecciones de MongoDB, no se admiten las consultas.For MongoDB collections, queries are not supported.
  • dataChangeDetectionPolicy: se recomienda.dataChangeDetectionPolicy: Recommended. Consulte la sección Indexación de documentos modificados.See Indexing Changed Documents section.
  • dataDeletionDetectionPolicy: opcional.dataDeletionDetectionPolicy: Optional. Consulte la sección Indexación de documentos eliminados.See Indexing Deleted Documents section.

Uso de consultas para dar forma a los datos indizadosUsing queries to shape indexed data

Puede especificar una consulta de SQL para eliminar el formato de las propiedades o matrices anidadas y de las propiedades JSON del proyecto, y para filtrar los datos que se van a indexar.You can specify a SQL query to flatten nested properties or arrays, project JSON properties, and filter the data to be indexed.

Advertencia

No se admiten consultas personalizadas para colecciones de MongoDB: el parámetro container.query debe establecerse en null u omitirse.Custom queries are not supported for MongoDB collections: container.query parameter must be set to null or omitted. Si tiene que usar una consulta personalizada, háganoslo saber en User Voice.If you need to use a custom query, please let us know on User Voice.

Documento de ejemplo:Example document:

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

Consulta de filtro:Filter query:

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

Consulta sin formato:Flattening query:

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

Consulta de proyección:Projection query:

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

Consulta sin formato de matriz:Array flattening query:

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

Paso 2: Creación de un índiceStep 2: Create an index

Si aún no tiene un índice de Azure Search de destino, créelo.Create a target Azure Search index if you don’t have one already. Puede crearlo mediante la interfaz de usuario de Azure Portal, la API de REST de Create Index o la clase Index.You can create an index using the Azure portal UI, the Create Index REST API or Index class.

En el ejemplo siguiente se crea un índice con un campo de identificador y de descripción:The following example creates an index with an id and description field:

POST https://[service name].search.windows.net/indexes?api-version=2017-11-11
Content-Type: application/json
api-key: [Search service admin key]

{
   "name": "mysearchindex",
   "fields": [{
     "name": "id",
     "type": "Edm.String",
     "key": true,
     "searchable": false
   }, {
     "name": "description",
     "type": "Edm.String",
     "filterable": false,
     "sortable": false,
     "facetable": false,
     "suggestions": true
   }]
 }

Asegúrese de que el esquema del índice de destino es compatible con el de los documentos JSON de origen o el resultado de la proyección de consultas personalizada.Ensure that the schema of your target index is compatible with the schema of the source JSON documents or the output of your custom query projection.

Nota

Para las colecciones particionadas, la clave de documento predeterminada es la propiedad _rid de Azure Cosmos DB, para la que Azure Search cambia el nombre automáticamente a rid, porque los nombres de los campos no pueden comenzar con un carácter de guion bajo.For partitioned collections, the default document key is Azure Cosmos DB's _rid property, which Azure Search automatically renames to rid because field names cannot start with an undescore character. Además, los valores _rid de Azure Cosmos DB contienen caracteres que no son válidos en las claves de Azure Search.Also, Azure Cosmos DB _rid values contain characters that are invalid in Azure Search keys. Por este motivo, la _rid valores están codificados con Base64.For this reason, the _rid values are Base64 encoded.

Para las colecciones de MongoDB, Azure Search cambia el nombre de la propiedad _id automáticamente a doc_id.For MongoDB collections, Azure Search automatically renames the _id property to doc_id.

asignación entre tipos de datos de JSON y de Azure SearchMapping between JSON Data Types and Azure Search Data Types

Tipo de datos de JSONJSON data type Tipos de campos de índice de destino compatiblesCompatible target index field types
BooleanoBool Edm.Boolean, Edm.StringEdm.Boolean, Edm.String
Números que parecen enterosNumbers that look like integers Edm.Int32, Edm.Int64, Edm.StringEdm.Int32, Edm.Int64, Edm.String
Números que parecen puntos flotantesNumbers that look like floating-points Edm.Double, Edm.StringEdm.Double, Edm.String
stringString Edm.StringEdm.String
Matrices de tipos primitivos, por ejemplo ["a", "b", "c"]Arrays of primitive types, for example ["a", "b", "c"] Collection(Edm.String)Collection(Edm.String)
Cadenas que parecen fechasStrings that look like dates Edm.DateTimeOffset, Edm.StringEdm.DateTimeOffset, Edm.String
Objetos GeoJSON, por ejemplo, {"tipo": "Punto", "coordenadas": [long, lat]}GeoJSON objects, for example { "type": "Point", "coordinates": [long, lat] } Edm.GeographyPointEdm.GeographyPoint
Otros objetos JSONOther JSON objects N/DN/A

Paso 3: Creación de un indexadorStep 3: Create an indexer

Una vez creados el origen de datos y los índices, ya podrá crear el indizador:Once the index and data source have been created, you're ready to create the indexer:

POST https://[service name].search.windows.net/indexers?api-version=2017-11-11
Content-Type: application/json
api-key: [admin key]

{
  "name" : "mydocdbindexer",
  "dataSourceName" : "mydocdbdatasource",
  "targetIndexName" : "mysearchindex",
  "schedule" : { "interval" : "PT2H" }
}

Este indexador se ejecuta cada dos horas (el intervalo de programación se establece en "PT2H").This indexer runs every two hours (schedule interval is set to "PT2H"). Para ejecutar un indizador cada 30 minutos, establézcalo en PT30M.To run an indexer every 30 minutes, set the interval to "PT30M". El intervalo más breve que se admite es de 5 minutos.The shortest supported interval is 5 minutes. La programación es opcional: si se omite, el indizador solo se ejecuta una vez cuando se crea.The schedule is optional - if omitted, an indexer runs only once when it's created. Sin embargo, puede ejecutarlo a petición en cualquier momento.However, you can run an indexer on-demand at any time.

Para más información sobre la API Create Indexer, consulte Crear indexador.For more details on the Create Indexer API, check out Create Indexer.

Ejecución del indexador a peticiónRunning indexer on-demand

Además de ejecutarse periódicamente de forma programada, un indexador también puede invocarse a petición:In addition to running periodically on a schedule, an indexer can also be invoked on demand:

POST https://[service name].search.windows.net/indexers/[indexer name]/run?api-version=2017-11-11
api-key: [Search service admin key]

Nota

Cuando la API de Run se devuelve correctamente, se ha programado la invocación del indexador, pero el procesamiento real se produce de forma asincrónica.When Run API returns successfully, the indexer invocation has been scheduled, but the actual processing happens asynchronously.

El estado del indexador se puede supervisar en el portal o mediante la API de Get Indexer Status, lo que se describe a continuación.You can monitor the indexer status in the portal or using the Get Indexer Status API, which we describe next.

Obtención del estado del indexadorGetting indexer status

Puede recuperar el estado y el historial de ejecución de un indexador:You can retrieve the status and execution history of an indexer:

GET https://[service name].search.windows.net/indexers/[indexer name]/status?api-version=2017-11-11
api-key: [Search service admin key]

La respuesta contiene el estado general del indexador, la última vez que se invocó al indexador (o en curso) y el historial de las recientes invocaciones al indexador.The response contains overall indexer status, the last (or in-progress) indexer invocation, and the history of recent indexer invocations.

{
    "status":"running",
    "lastResult": {
        "status":"success",
        "errorMessage":null,
        "startTime":"2014-11-26T03:37:18.853Z",
        "endTime":"2014-11-26T03:37:19.012Z",
        "errors":[],
        "itemsProcessed":11,
        "itemsFailed":0,
        "initialTrackingState":null,
        "finalTrackingState":null
     },
    "executionHistory":[ {
        "status":"success",
         "errorMessage":null,
        "startTime":"2014-11-26T03:37:18.853Z",
        "endTime":"2014-11-26T03:37:19.012Z",
        "errors":[],
        "itemsProcessed":11,
        "itemsFailed":0,
        "initialTrackingState":null,
        "finalTrackingState":null
    }]
}

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).Execution history contains up to the 50 most recent completed executions, which are sorted in reverse chronological order (so the latest execution comes first in the response).

Indexación de documentos modificadosIndexing changed documents

El fin de una directiva de detección de cambios de datos es identificar de forma eficaz los elementos de datos que han cambiado.The purpose of a data change detection policy is to efficiently identify changed data items. Actualmente, High Water Mark es la única directiva compatible que usa la propiedad _ts (marca de tiempo) que proporciona Azure Cosmos DB, y se especifica de la siguiente forma:Currently, the only supported policy is the High Water Mark policy using the _ts (timestamp) property provided by Azure Cosmos DB, which is specified as follows:

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

Se recomienda encarecidamente usar esta directiva para garantizar un buen rendimiento del indexador.Using this policy is highly recommended to ensure good indexer performance.

Si usa una consulta personalizada, asegúrese de que la consulta proyecta la propiedad _ts.If you are using a custom query, make sure that the _ts property is projected by the query.

Progreso incremental y consultas personalizadasIncremental progress and custom queries

El progreso incremental durante la indexación garantiza que si se interrumpe la ejecución del indexador por errores transitorios o por el límite de tiempo de ejecución, dicho indexador puede retomar la ejecución por donde la dejó la próxima vez que se ejecute, en lugar de tener que volver a indexar toda la colección desde el principio.Incremental progress during indexing ensures that if indexer execution is interrupted by transient failures or execution time limit, the indexer can pick up where it left off next time it runs, instead of having to reindex the entire collection from scratch. Esto es especialmente importante cuando se indexan colecciones grandes.This is especially important when indexing large collections.

Para habilitar el progreso incremental cuando se usa una consulta personalizada, asegúrese de que la consulta ordena los resultados por la columna _ts.To enable incremental progress when using a custom query, ensure that your query orders the results by the _ts column. Esto permite la creación de puntos de comprobación, que Azure Search usa para proporcionar el progreso incremental en presencia de errores.This enables periodic check-pointing that Azure Search uses to provide incremental progress in the presence of failures.

En algunos casos, incluso si la consulta contiene una cláusula ORDER BY [collection alias]._ts, Azure Search puede no deducir que la consulta se ordene por _ts.In some cases, even if your query contains an ORDER BY [collection alias]._ts clause, Azure Search may not infer that the query is ordered by the _ts. Puede indicar a Azure Search que los resultados se ordenen mediante el uso de la propiedad de configuración assumeOrderByHighWaterMarkColumn.You can tell Azure Search that results are ordered by using the assumeOrderByHighWaterMarkColumn configuration property. Para especificar esta sugerencia, cree o actualice el indexador como se indica a continuación:To specify this hint, create or update your indexer as follows:

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

Indexación de documentos eliminadosIndexing deleted documents

Cuando se eliminan filas de la recopilación, lo habitual es que también se deseen eliminar del índice de búsqueda.When rows are deleted from the collection, you normally want to delete those rows from the search index as well. El fin de una directiva de detección de eliminación de datos es identificar eficazmente los elementos de datos eliminados.The purpose of a data deletion detection policy is to efficiently identify deleted data items. Actualmente, solo es compatible la directiva Soft Delete (la eliminación se indica con algún tipo de marca), especificada de la siguiente forma:Currently, the only supported policy is the Soft Delete policy (deletion is marked with a flag of some sort), which is specified as follows:

{
    "@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 proyecta la propiedad a la que softDeleteColumnName hace referencia.If you are using a custom query, make sure that the property referenced by softDeleteColumnName is projected by the query.

En el ejemplo siguiente se crea un origen de datos con una directiva de eliminación temporal:The following example creates a data source with a soft-deletion policy:

POST https://[service name].search.windows.net/datasources?api-version=2017-11-11
Content-Type: application/json
api-key: [Search service admin key]

{
    "name": "mydocdbdatasource",
    "type": "documentdb",
    "credentials": {
        "connectionString": "AccountEndpoint=https://myDocDbEndpoint.documents.azure.com;AccountKey=myDocDbAuthKey;Database=myDocDbDatabaseId"
    },
    "container": { "name": "myDocDbCollectionId" },
    "dataChangeDetectionPolicy": {
        "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
        "highWaterMarkColumnName": "_ts"
    },
    "dataDeletionDetectionPolicy": {
        "@odata.type": "#Microsoft.Azure.Search.SoftDeleteColumnDeletionDetectionPolicy",
        "softDeleteColumnName": "isDeleted",
        "softDeleteMarkerValue": "true"
    }
}

Pasos siguientesNext steps

Felicidades.Congratulations! En este artículo, aprendió a integrar Azure Cosmos DB con Azure Search con un indexador.You have learned how to integrate Azure Cosmos DB with Azure Search using an indexer.