Copiar dados para/do Azure Cosmos DB for MongoDB usando o Azure Data Factory ou o Synapse Analytics

Artigo
01/05/2024

APLICA-SE A: Azure Data Factory Azure Synapse Analytics

Dica

Experimente o Data Factory no Microsoft Fabric, uma solução de análise tudo-em-um para empresas. O Microsoft Fabric abrange desde movimentação de dados até ciência de dados, análise em tempo real, business intelligence e relatórios. Saiba como iniciar uma avaliação gratuita!

Este artigo descreve como usar a atividade de cópia nos pipelines do Azure Data Factory e do Synapse Analytics a fim de copiar dados para/do Azure Cosmos DB for MongoDB. O artigo se baseia em Atividade Copy, que apresenta uma visão geral da atividade Copy.

Observação

Esse conector só dá suporte a dados de cópia para/do Azure Cosmos DB for MongoDB. Para o Azure Cosmos DB for NoSQL, confira o Conector do Azure Cosmos DB para NoSQL. Outros tipos de API não são compatíveis no momento.

Funcionalidades com suporte

Esse conector do Azure Cosmos DB for MongoDB tem suporte para os seguintes recursos:

Funcionalidades com suporte	IR	Ponto de extremidade privado gerenciado
Atividade de cópia (origem/coletor)	6/6	✓

① Runtime de integração do Azure ② Runtime de integração auto-hospedada

É possível copiar dados do Azure Cosmos DB for MongoDB para qualquer armazenamento de dados de coletor com suporte ou de qualquer armazenamento de dados de origem com suporte para o Azure Cosmos DB for MongoDB. Para obter uma lista de armazenamentos de dados que o Copy Activity suporta como fontes e coletores, consulte Armazenamentos de dados e formatos compatíveis.

É possível usar o conector do Azure Cosmos DB for MongoDB para o seguinte:

Copiar dados para/do Azure Cosmos DB for MongoDB.
Gravar no Azure Cosmos DB como insert ou upsert.
Importar e exportar documentos JSON no estado em que se encontram, ou copiar dados de ou para um conjunto de dados tabular. Exemplos incluem um Banco de Dados SQL e um arquivo CSV. Para copiar documentos no estado em que se encontram para ou de arquivos JSON de outra coleção do Azure Cosmos DB, confira Importar ou exportar documentos JSON.

Introdução

Para executar a atividade de Cópia com um pipeline, será possível usar as ferramentas ou os SDKs abaixo:

Criar um serviço vinculado ao Azure Cosmos DB for MongoDB usando a interface do usuário

Siga as etapas a seguir para criar um serviço vinculado ao Azure Cosmos DB for MongoDB na interface do usuário do portal do Azure.

Navegue até a guia Gerenciar no workspace do Azure Data Factory ou do Synapse, selecione Serviços Vinculados e clique em Novo:
- Azure Data Factory
- Azure Synapse
Pesquise o Azure Cosmos DB for MongoDB e selecione o conector.
Configure os detalhes do serviço, teste a conexão e crie o novo serviço vinculado.

Detalhes da configuração do conector

As seções a seguir fornecem detalhes sobre as propriedades que podem ser usadas para definir entidades do Data Factory específicas do Azure Cosmos DB for MongoDB.

Propriedades do serviço vinculado

As seguintes propriedades têm suporte para o serviço vinculado do Azure Cosmos DB for MongoDB:

Propriedade	Descrição	Obrigatório
type	O tipo de propriedade deve ser definido como CosmosDbMongoDbApi.	Sim
connectionString	Especifique a cadeia de conexão do Azure Cosmos DB for MongoDB. Ela pode ser encontrada no portal do Azure: > na folha do Azure Cosmos DB, > cadeia de conexão primária ou secundária. Para a versão 3.2 do servidor, o padrão de cadeia de caracteres é `mongodb://<cosmosdb-name>:<password>@<cosmosdb-name>.documents.azure.com:10255/?ssl=true&replicaSet=globaldb`. Para a versão 3.6 ou posterior, o padrão de cadeia de caracteres é `mongodb://<cosmosdb-name>:<password>@<cosmosdb-name>.mongo.cosmos.azure.com:10255/?ssl=true&replicaSet=globaldb&retrywrites=false&maxIdleTimeMS=120000&appName=@<cosmosdb-name>@`. Também é possível colocar uma senha no Azure Key Vault e extrair a configuração `password` da cadeia de conexão. Veja o artigo Credenciais de armazenamento no Azure Key Vault para saber mais detalhes.	Sim
Banco de Dados	O nome do banco de dados que você deseja criar.	Sim
isServerVersionAbove32	Especifique se a versão do servidor é superior a 3.2. Os valores permitidos são true e false (padrão). Isso determinará o driver a ser usado no serviço.	Sim
connectVia	O runtime de integração a ser usado para se conectar ao armazenamento de dados. Você poderá usar o Azure Integration Runtime ou um tempo de execução da integração auto-hospedada (se o armazenamento de dados estiver localizado em uma rede privada). Se essa propriedade não for especificada, o Azure Integration Runtime padrão será usado.	Não

Exemplo

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

Propriedades do conjunto de dados

Para obter uma lista completa de seções e propriedades disponíveis para definição de conjuntos de dados, consulte Conjuntos de dados e serviços vinculados. As seguintes propriedades são compatíveis com o conjunto de dados do Azure Cosmos DB for MongoDB:

Propriedade	Descrição	Obrigatório
type	O tipo de propriedade do conjunto de dados deve ser definido como CosmosDbMongoDbApiCollection.	Sim
collectionName	O nome da coleção do Azure Cosmos DB.	Sim

Exemplo

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

Propriedades da Atividade de Cópia

Esta seção fornece uma lista de propriedades compatíveis com a fonte e o coletor do Azure Cosmos DB for MongoDB.

Para obter uma lista completa de seções e propriedades que estão disponíveis para definir atividades, consulte Pipelines.

Azure Cosmos DB for MongoDB como origem

As seguintes propriedades são suportadas na seção source da atividade de cópia:

Propriedade	Descrição	Obrigatório
type	O tipo de propriedade da fonte da atividade de cópia deve ser definido como CosmosDbMongoDbApiSource.	Sim
filter	Especifica o filtro de seleção usando operadores de consulta. Para retornar todos os documentos em uma coleção, omita esse parâmetro ou passe um documento vazio ({}).	Não
cursorMethods.project	Especifica os campos a serem retornados nos documentos para projeção. Para retornar todos os campos nos documentos correspondentes, omita este parâmetro.	Não
cursorMethods.sort	Especifica a ordem na qual a consulta retorna documentos correspondentes. Consulte cursor.sort().	Não
cursorMethods.limit	Especifica o número máximo de documentos que o servidor retorna. Consulte cursor.limit().	Não
cursorMethods.skip	Especifica o número de documentos a serem ignorados e de onde o MongoDB começa a retornar resultados. Consulte cursor.skip().	Não
batchSize	Especifica o número de documentos a serem retornados em cada lote da resposta da instância do MongoDB. Na maioria dos casos, modificar o tamanho do lote não afetará o usuário ou o aplicativo. O Azure Cosmos DB limita cada lote para que não exceda 40 MB de tamanho, que é a soma do número batchSize do tamanho dos documentos. Portanto, diminua esse valor se o tamanho do documento for grande.	Não (o padrão é 100)

Dica

Suporte do ADF consumindo o documento BSON em Modo estrito. Verifique se sua consulta de filtro está em Modo estrito em vez do modo Shell. Mais detalhes podem ser encontrados no Manual do MongoDB.

Exemplo

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

As seguintes propriedades são suportadas na seção Copy Activity sink:

Propriedade	Descrição	Obrigatório
type	O tipo de propriedade do coletor de atividade de cópia deve ser definido como CosmosDbMongoDbApiSink.	Sim
writeBehavior	Descreve como gravar dados no Azure Cosmos DB. Valores permitidos são insert e upsert. O comportamento de upsert será substituir o documento se um documento com a mesma `_id` já existir; caso contrário, insira o documento. Nota: o serviço gera automaticamente uma `_id` ID para um documento `_id` se não for especificada uma ID no documento original ou no mapeamento de coluna. Isso significa que, para upsert funcionar conforme esperado, o documento deve ter uma ID.	No (o padrão é insert)
writeBatchSize	A propriedade writeBatchSize controla o tamanho dos documentos que escrevemos em cada lote. Você pode tentar aumentar o valor de writeBatchSize para melhorar o desempenho e diminuir o valor se o tamanho do documento for grande.	Não (o padrão é 10.000)
writeBatchTimeout	O tempo de espera para que a operação de inserção em lote seja concluída antes de atingir o tempo limite. O valor permitido é timespan.	Não (o padrão é 30:00:00 - 30 minutos)

Dica

Para importar documentos JSON como eles estão, consulte a seção importar ou exportar documentos JSON; para copiar de dados em formato tabular, consulte mapeamento de esquema.

Exemplo

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

Importar e exportar documentos JSON

Você pode usar esse conector do Azure Cosmos DB para facilmente:

Copiar documentos entre duas coleções do Azure Cosmos DB no estado em que se encontram.
Importar documentos JSON de várias fontes para o Azure Cosmos DB, incluindo no MongoDB, no Armazenamento de Blobs do Azure, no Azure Data Lake Storage e em outros repositórios baseados em arquivo compatíveis com o serviço.
Exportar documentos JSON de uma coleção do Azure Cosmos DB para vários repositórios baseados em arquivo.

Para obter uma cópia independente de esquema:

Ao usar a ferramenta Copiar Dados, selecione a opção Exportar no estado em que se encontra para arquivos JSON ou uma coleção do Azure Cosmos DB.
Ao usar a criação de atividade, escolha o formato JSON com o repositório de arquivos correspondente para a origem ou o coletor.

Mapeamento de esquema

Para copiar dados do Azure Cosmos DB for MongoDB para o coletor tabular ou o revertido, confira o mapeamento de esquema.

Especificamente para gravações no Azure Cosmos DB, a fim de garantir o preenchimento com a ID de objeto correta de seus dados de origem no Azure Cosmos DB, por exemplo, caso você tenha uma coluna "ID" na tabela do banco de dados SQL e deseja usar esse valor como a ID do documento no MongoDB para inserção/upsert, você precisa definir o mapeamento de esquema adequado de acordo com a definição de modo estrito do MongoDB (_id.$oid) da seguinte forma:

Map ID in MongoDB sink

Após a cópia de execução da atividade, o ObjectId BSON abaixo é gerado no coletor:

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

Para obter uma lista de armazenamentos de dados aos quais a atividade Copy oferece suporte, como fontes e coletores, consulte Armazenamentos de dados compatíveis.

Copiar dados para/do Azure Cosmos DB for MongoDB usando o Azure Data Factory ou o Synapse Analytics

Funcionalidades com suporte

Introdução

Criar um serviço vinculado ao Azure Cosmos DB for MongoDB usando a interface do usuário

Detalhes da configuração do conector

Propriedades do serviço vinculado

Propriedades do conjunto de dados

Propriedades da Atividade de Cópia

Azure Cosmos DB for MongoDB como origem

Azure Cosmos DB for MongoDB como coletor

Importar e exportar documentos JSON

Mapeamento de esquema

Conteúdo relacionado

Recursos adicionais