Copia de datos desde o hacia Azure Cosmos DB for MongoDB mediante Azure Data Factory o Synapse Analytics

Artículo
01/05/2024

SE APLICA A: Azure Data Factory Azure Synapse Analytics

Sugerencia

Pruebe Data Factory en Microsoft Fabric, una solución de análisis todo en uno para empresas. Microsoft Fabric abarca todo, desde el movimiento de datos hasta la ciencia de datos, el análisis en tiempo real, la inteligencia empresarial y los informes. Obtenga información sobre cómo iniciar una nueva evaluación gratuita.

En este artículo se resume el uso de la actividad de copia en canalizaciones de Azure Data Factory y Synapse Analytics para copiar datos con Azure Cosmos DB for MongoDB como origen y destino. El artículo se basa en Actividad de copia, en el que se ofrece información general acerca de la actividad de copia.

Nota

Este conector solo admite la copia de datos desde y hacia Azure Cosmos DB for MongoDB. Para Azure Cosmos DB for NoSQL, consulte Conector de Azure Cosmos DB for NoSQL. Actualmente, no se admiten otros tipos de API.

Funcionalidades admitidas

Este conector de Azure Cosmos DB for MongoDB admite las siguientes funcionalidades:

Funcionalidades admitidas	IR	Puntos de conexión privados administrados de Synapse (versión preliminar)
Actividad de copia (origen/receptor)	7,7	✓

① Azure Integration Runtime ② Entorno de ejecución de integración autohospedado

Puede copiar datos desde Azure Cosmos DB for MongoDB a cualquier almacén de datos de receptor compatible, o bien puede copiar datos desde cualquier almacén de datos de origen compatible a Azure Cosmos DB for MongoDB. Para obtener una lista de almacenes de datos que la actividad de copia admite como orígenes y receptores, consulte Almacenes de datos y formatos que se admiten.

Puede usar el conector de Azure Cosmos DB for MongoDB para:

Copiar datos desde y hacia Azure Cosmos DB for MongoDB.
Escriba en Azure Cosmos DB como insert o upsert.
Importe y exporte documentos JSON tal cual, o copie datos desde o hacia un conjunto de datos tabular. Entre los ejemplos se incluyen una base de datos SQL y un archivo CSV. Para copiar datos tal cual desde o hacia archivos JSON u otra colección de Azure Cosmos DB, consulte Importación o exportación de documentos JSON.

Introducción

Para realizar la actividad de copia con una canalización, puede usar una de los siguientes herramientas o SDK:

Creación de un servicio vinculado a Azure Cosmos DB for MongoDB mediante la interfaz de usuario

Siga estos pasos para crear un servicio vinculado a Azure Cosmos DB for MongoDB en la interfaz de usuario de Azure Portal.

Vaya a la pestaña Administrar en el área de trabajo de Azure Data Factory o Synapse, seleccione Servicios vinculados y, después, haga clic en Nuevo:
- Azure Data Factory
- Azure Synapse
Busque Azure Cosmos DB for MongoDB y seleccione ese conector.
Configure los detalles del servicio, pruebe la conexión y cree el nuevo servicio vinculado.

Detalles de configuración del conector

En las secciones siguientes, se proporcionan detalles sobre las propiedades que puede usar para definir entidades de Data Factory específicas de Azure Cosmos DB for MongoDB.

Propiedades del servicio vinculado

Las siguientes propiedades son compatibles con el servicio vinculado de Azure Cosmos DB for MongoDB:

Propiedad	Descripción	Obligatorio
type	La propiedad type tiene que establecerse en CosmosDbMongoDbApi.	Sí
connectionString	Especifique la cadena de conexión para Azure Cosmos DB for MongoDB. La encontrará en Azure Portal -> su hoja de Azure Cosmos DB -> cadena de conexión principal o secundaria. Para la versión 3.2 del servidor, el patrón de cadena es `mongodb://<cosmosdb-name>:<password>@<cosmosdb-name>.documents.azure.com:10255/?ssl=true&replicaSet=globaldb`. Para la versión 3.6 y superior del servidor, el patrón de cadena es `mongodb://<cosmosdb-name>:<password>@<cosmosdb-name>.mongo.cosmos.azure.com:10255/?ssl=true&replicaSet=globaldb&retrywrites=false&maxIdleTimeMS=120000&appName=@<cosmosdb-name>@`. También puede establecer una contraseña en Azure Key Vault y extraer la configuración de `password` de la cadena de conexión. Consulte el artículo Almacenamiento de credenciales en Azure Key Vault para obtener información detallada.	Sí
database	Nombre de la base de datos a la que desea acceder.	Sí
isServerVersionAbove32	Especifique si la versión del servidor es superior a la 3.2. Los valores permitidos son true y false (predeterminado). Esta elección determinará el controlador que se va a usar en el servicio.	Sí
connectVia	Instancia de Integration Runtime que se usará para conectarse al almacén de datos. Se puede usar Azure Integration Runtime o un entorno de ejecución de integración autohospedado (si el almacén de datos se encuentra en una red privada). Si no se especifica esta propiedad, se usa el valor predeterminado de Azure Integration Runtime.	No

Ejemplo

{
    "name": "CosmosDbMongoDBAPILinkedService",
    "properties": {
        "type": "CosmosDbMongoDbApi",
        "typeProperties": {
            "connectionString": "mongodb://<cosmosdb-name>:<password>@<cosmosdb-name>.documents.azure.com:10255/?ssl=true&replicaSet=globaldb",
            "database": "myDatabase",
            "isServerVersionAbove32": "false"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Propiedades del conjunto de datos

Para ver una lista completa de las secciones y propiedades disponibles para definir conjuntos de datos, consulte Conjuntos de datos y servicios vinculados. Las siguientes propiedades son compatibles con el conjunto de datos de Azure Cosmos DB for MongoDB:

Propiedad	Descripción	Obligatorio
type	La propiedad type del conjunto de datos tiene que establecerse en CosmosDbMongoDbApiCollection.	Sí
collectionName	Nombre de la colección de Azure Cosmos DB.	Sí

Ejemplo

{
    "name": "CosmosDbMongoDBAPIDataset",
    "properties": {
        "type": "CosmosDbMongoDbApiCollection",
        "typeProperties": {
            "collectionName": "<collection name>"
        },
        "schema": [],
        "linkedServiceName":{
            "referenceName": "<Azure Cosmos DB for MongoDB linked service name>",
            "type": "LinkedServiceReference"
        }
    }
}

Propiedades de la actividad de copia

En esta sección, se proporciona una lista de las propiedades admitidas por el origen y el receptor de Azure Cosmos DB for MongoDB.

Para ver una lista completa de las secciones y propiedades que hay disponibles para definir actividades, consulte Canalizaciones.

Azure Cosmos DB for MongoDB como origen

La sección source de la actividad de copia admite las siguientes propiedades:

Propiedad	Descripción	Obligatorio
type	La propiedad type del origen de la actividad de copia tiene que establecerse en CosmosDbMongoDbApiSource.	Sí
filter	Especifica el filtro de selección mediante operadores de consulta. Para que se devuelvan todos los documentos de una colección, omita este parámetro o pase un documento vacío ({}).	No
cursorMethods.project	Especifica los campos a devolver en los documentos para la proyección. Para devolver todos los campos en los documentos coincidentes, omita este parámetro.	No
cursorMethods.sort	Especifica el orden en que la consulta devuelve los documentos coincidentes. Consulte cursor.sort().	No
cursorMethods.limit	Especifica el número máximo de documentos que devuelve el servidor. Consulte cursor.limit().	No
cursorMethods.skip	Especifica el número de documentos que se omitirán y desde donde empieza MongoDB a devolver resultados. Consulte cursor.skip().	No
batchSize	Especifica el número de documentos a devolver en cada lote de la respuesta de la instancia de MongoDB. En la mayoría de los casos, modificar el tamaño del lote no afectará al usuario ni a la aplicación. Azure Cosmos DB limita el tamaño de cada lote a 40 MB como máximo, que es la suma de los números de batchSize del tamaño de los documentos, por lo que debe reducir este valor si el tamaño del documento es mayor.	No (el valor predeterminado es 100)

Sugerencia

ADF admite el consumo de documentos BSON en modo strict. Asegúrese de que la consulta de filtro está en modo strict en lugar de en modo Shell. Para obtener una descripción más detallada, consulte el manual de MongoDB.

Ejemplo

"activities":[
    {
        "name": "CopyFromCosmosDBMongoDBAPI",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<Azure Cosmos DB for MongoDB input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "CosmosDbMongoDbApiSource",
                "filter": "{datetimeData: {$gte: ISODate(\"2018-12-11T00:00:00.000Z\"),$lt: ISODate(\"2018-12-12T00:00:00.000Z\")}, _id: ObjectId(\"5acd7c3d0000000000000000\") }",
                "cursorMethods": {
                    "project": "{ _id : 1, name : 1, age: 1, datetimeData: 1 }",
                    "sort": "{ age : 1 }",
                    "skip": 3,
                    "limit": 3
                }
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

Azure Cosmos DB for MongoDB como receptor

La sección sink de la actividad de copia admite las siguientes propiedades:

Propiedad	Descripción	Obligatorio
type	La propiedad type del receptor “Copy Activity” (Actividad de copia) tiene que establecerse en CosmosDbMongoDbApiSink.	Sí
writeBehavior	Describe cómo escribir datos en Azure Cosmos DB. Valores permitidos: insert y upsert. El comportamiento de upsert consiste en reemplazar el documento si ya existe un documento con el mismo `_id`; en caso contrario, inserta el documento. Nota: El servicio genera automáticamente un `_id` para un documento si no se especifica un `_id` en el documento original o mediante la asignación de columnas. Esto significa que debe asegurarse de que, para que upsert funcione según lo esperado, el documento tenga un identificador.	No (el valor predeterminado es insert)
writeBatchSize	La propiedad writeBatchSize controla el tamaño de los documentos que se escribirán en cada lote. Puede intentar aumentar el valor de writeBatchSize para mejorar el rendimiento y reducir el valor si el documento tiene un tamaño grande.	No (el valor predeterminado es 10 000)
writeBatchTimeout	Tiempo que se concede a la operación de inserción por lotes para que finalice antes de que se agote el tiempo de espera. El valor permitido es TimeSpan.	No (El valor predeterminado es 00:30:00 [30 minutos]).

Sugerencia

Para importar documentos JSON tal cual, vea la sección Importar o exportar documentos JSON; para copiar de datos con formato tabular, vea Asignación de esquemas.

Ejemplo

"activities":[
    {
        "name": "CopyToCosmosDBMongoDBAPI",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<Document DB output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "<source type>"
            },
            "sink": {
                "type": "CosmosDbMongoDbApiSink",
                "writeBehavior": "upsert"
            }
        }
    }
]

Importación y exportación de documentos JSON

Puede utilizar este conector de Azure Cosmos DB para hacer lo siguiente con facilidad:

Copiar documentos entre dos colecciones de Azure Cosmos DB tal cual.
Importar documentos JSON desde varios orígenes a Azure Cosmos DB, incluido MongoDB, Azure Blob Storage, Azure Data Lake Store y otros almacenes basados en archivos compatibles con el servicio.
Exportar documentos JSON de una colección de Azure Cosmos DB a varios almacenes basados en archivos.

Para lograr una copia independiente del esquema:

Cuando use la herramienta Copiar datos, seleccione la opción Export as-is to JSON files or Azure Cosmos DB collection (Exportar tal cual a archivos JSON o colección de Azure Cosmos DB).
Cuando use la creación de actividades, elija el formato JSON con el almacén de archivos correspondiente para el origen o el receptor.

Asignación de esquemas

Para copiar datos de Azure Cosmos DB for MongoDB en un receptor tabular o inverso, consulte Asignación de esquemas.

En concreto, para escribir en Azure Cosmos DB y asegurarse de rellenar Azure Cosmos DB con el identificador de objeto correcto de los datos de origen (por ejemplo, si tiene una columna “id” en la tabla de la base de datos SQL y quiere usar el valor como el identificador del documento en MongoDB para inserción/upsert), necesita establecer la asignación de esquemas correcta según la definición de modo estricto de MongoDB (_id.$oid), como se indica a continuación:

Map ID in MongoDB sink

Después de ejecutar “Copiar actividad”, a continuación se genera el elemento ObjectId de JSON en el receptor:

{
    "_id": ObjectId("592e07800000000000000000")
}

Para obtener una lista de los almacenes de datos que la actividad de copia admite como orígenes y receptores, vea Almacenes de datos compatibles.

Copia de datos desde o hacia Azure Cosmos DB for MongoDB mediante Azure Data Factory o Synapse Analytics

Funcionalidades admitidas

Introducción

Creación de un servicio vinculado a Azure Cosmos DB for MongoDB mediante la interfaz de usuario

Detalles de configuración del conector

Propiedades del servicio vinculado

Propiedades del conjunto de datos

Propiedades de la actividad de copia

Azure Cosmos DB for MongoDB como origen

Azure Cosmos DB for MongoDB como receptor

Importación y exportación de documentos JSON

Asignación de esquemas

Contenido relacionado

Recursos adicionales