Copiar dados de ou para o Azure Cosmos DB para MongoDB usando o Azure Data Factory ou o Synapse Analytics

Artigo
01/05/2024

APLICA-SE A: Azure Data Factory Azure Synapse Analytics

Gorjeta

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

Este artigo descreve como usar a Atividade de Cópia no Azure Data Factory e nos pipelines do Synapse Analytics para copiar dados de e para o Azure Cosmos DB para MongoDB. O artigo baseia-se na Atividade de Cópia, que apresenta uma visão geral da Atividade de Cópia.

Nota

Este conector suporta apenas copiar dados de/para o Azure Cosmos DB para MongoDB. Para o Azure Cosmos DB para NoSQL, consulte o conector do Azure Cosmos DB para NoSQL. Outros tipos de API não são suportados no momento.

Capacidades suportadas

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

Capacidades suportadas	IR	Ponto final privado gerido
Atividade de cópia (origem/coletor)	(1) (2)	✓

(1) Tempo de execução de integração do Azure (2) Tempo de execução de integração auto-hospedado

Você pode copiar dados do Azure Cosmos DB para MongoDB para qualquer armazenamento de dados de coletor com suporte ou copiar dados de qualquer armazenamento de dados de origem com suporte para o Azure Cosmos DB para MongoDB. Para obter uma lista de armazenamentos de dados que a Atividade de Cópia suporta como fontes e coletores, consulte Formatos e armazenamentos de dados suportados.

Você pode usar o conector do Azure Cosmos DB para MongoDB para:

Copie dados de e para o Azure Cosmos DB para MongoDB.
Escreva no Azure Cosmos DB como inserir ou atualizar.
Importe e exporte documentos JSON no estado em que se encontram ou copie dados de ou para um conjunto de dados tabular. Os exemplos incluem um banco de dados SQL e um arquivo CSV. Para copiar documentos como estão para ou de arquivos JSON ou de ou para outra coleção do Azure Cosmos DB, consulte Importar ou exportar documentos JSON.

Começar agora

Para executar a atividade Copiar com um pipeline, você pode usar uma das seguintes ferramentas ou SDKs:

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

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

Navegue até a guia Gerenciar em seu espaço de trabalho do Azure Data Factory ou Synapse e selecione Serviços Vinculados e clique em Novo:
- Fábrica de Dados do Azure
- Azure Synapse
Procure o Azure Cosmos DB para MongoDB e selecione esse conector.
Configure os detalhes do serviço, teste a conexão e crie o novo serviço vinculado.

Detalhes de configuração do conector

As seções a seguir fornecem detalhes sobre as propriedades que você pode usar para definir entidades do Data Factory que são específicas do Azure Cosmos DB para MongoDB.

Propriedades do serviço vinculado

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

Property	Descrição	Obrigatório
tipo	A propriedade type deve ser definida como CosmosDbMongoDbApi.	Sim
connectionString	Especifique a cadeia de conexão para seu Azure Cosmos DB para MongoDB. Você pode encontrá-lo no portal do Azure -> sua folha do Azure Cosmos DB -> cadeia de conexão primária ou secundária. Para a versão do servidor 3.2, o padrão de cadeia de caracteres é `mongodb://<cosmosdb-name>:<password>@<cosmosdb-name>.documents.azure.com:10255/?ssl=true&replicaSet=globaldb`. Para versões de servidor 3.6+, 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>@`. Você também pode colocar uma senha no Cofre de Chaves do Azure e extrair a `password` configuração da cadeia de conexão. Consulte Armazenar credenciais no Azure Key Vault com mais detalhes.	Sim
base de dados	Nome do banco de dados que você deseja acessar.	Sim
isServerVersionAbove32	Especifique se a versão do servidor está acima de 3.2. Os valores permitidos são true e false(default). Isso determinará o driver a ser usado no serviço.	Sim
ConecteVia	O tempo de execução de integração a ser usado para se conectar ao armazenamento de dados. Você pode usar o Tempo de Execução de Integração do Azure ou um tempo de execução de integração auto-hospedado (se seu armazenamento de dados estiver localizado em uma rede privada). Se essa propriedade não for especificada, o Tempo de Execução de Integração do Azure 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 definir conjuntos de dados, consulte Conjuntos de dados e serviços vinculados. As seguintes propriedades têm suporte para o conjunto de dados do Azure Cosmos DB for MongoDB:

Property	Descrição	Obrigatório
tipo	A propriedade type do conjunto de dados deve ser definida 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"
        }
    }
}

Copiar propriedades da atividade

Esta seção fornece uma lista de propriedades que o Azure Cosmos DB para MongoDB suporta de origem e coletor.

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

Azure Cosmos DB para MongoDB como origem

As seguintes propriedades são suportadas na seção Copiar fonte de atividade:

Property	Descrição	Obrigatório
tipo	A propriedade type da fonte de atividade de cópia deve ser definida como CosmosDbMongoDbApiSource.	Sim
filtrar	Especifica o filtro de seleção usando operadores de consulta. Para retornar todos os documentos de 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 esse 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 retornados pelo servidor. 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. Os limites do Azure Cosmos DB para cada lote não podem exceder 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)

Gorjeta

Suporte do ADF consumindo documento BSON no modo estrito. Verifique se a consulta de filtro está no modo Estrito em vez do modo Shell. Mais descrição pode ser encontrada 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 para MongoDB como coletor

As seguintes propriedades são suportadas na seção Copiar coletor de atividade:

Property	Descrição	Obrigatório
tipo	A propriedade type do coletor Copy Activity deve ser definida como CosmosDbMongoDbApiSink.	Sim
writeBehavior	Descreve como gravar dados no Azure Cosmos DB. Valores permitidos: inserir e upsert. O comportamento do upsert é substituir o documento se já existir um documento com o mesmo `_id` , caso contrário, insira o documento. Nota: O serviço gera automaticamente um `_id` para um documento se um `_id` não for especificado no documento original ou por mapeamento de coluna. Isso significa que você deve garantir que, para que o upsert funcione conforme o esperado, seu documento tenha um ID.	Não (o padrão é inserir)
writeBatchSize	A propriedade writeBatchSize controla o tamanho dos documentos a serem gravados 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 de lote termine antes que ela atinja o tempo limite. O valor permitido é timepan.	Não (o padrão é 00:30:00 - 30 minutos)

Gorjeta

Para importar documentos JSON no estado em que se encontram, consulte a seção Importar ou exportar documentos JSON; para copiar de dados em forma de tabela, 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:

Copie documentos entre duas coleções do Azure Cosmos DB no estado em que se encontram.
Importe documentos JSON de várias fontes para o Azure Cosmos DB, incluindo do MongoDB, do armazenamento de Blobs do Azure, do Azure Data Lake Store e de outros armazenamentos baseados em arquivos suportados pelo serviço.
Exporte documentos JSON de uma coleção do Azure Cosmos DB para vários repositórios baseados em arquivos.

Para obter uma cópia independente do esquema:

Ao usar a ferramenta Copiar Dados, selecione a opção Exportar como está para arquivos JSON ou Coleção do Azure Cosmos DB.
Ao usar a criação de atividades, escolha o formato JSON com o armazenamento de arquivos correspondente para origem ou coletor.

Mapeamento de esquema

Para copiar dados do Azure Cosmos DB para MongoDB para coletor tabular ou invertido, consulte mapeamento de esquema.

Especificamente para escrever no Azure Cosmos DB, para garantir que você preencha o Azure Cosmos DB com a ID de objeto correta de seus dados de origem, por exemplo, você tem uma coluna "id" na tabela do banco de dados SQL e deseja usar o valor disso como a ID do documento no MongoDB para inserir/upsert, você precisa definir o mapeamento de esquema adequado de acordo com a definição de modo estrito (_id.$oid) do MongoDB da seguinte forma:

ID do mapa na pia do MongoDB

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

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

Para obter uma lista de armazenamentos de dados que a Atividade de Cópia suporta como fontes e coletores, consulte Armazenamentos de dados suportados.

Partilhar via

Copiar dados de ou para o Azure Cosmos DB para MongoDB usando o Azure Data Factory ou o Synapse Analytics

Capacidades suportadas

Começar agora

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

Detalhes de configuração do conector

Propriedades do serviço vinculado

Propriedades do conjunto de dados

Copiar propriedades da atividade

Azure Cosmos DB para MongoDB como origem

Azure Cosmos DB para MongoDB como coletor

Importar e exportar documentos JSON

Mapeamento de esquema

Comentários

Recursos adicionais

Partilhar via

Copiar dados de ou para o Azure Cosmos DB para MongoDB usando o Azure Data Factory ou o Synapse Analytics

Capacidades suportadas

Começar agora

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

Detalhes de configuração do conector

Propriedades do serviço vinculado

Propriedades do conjunto de dados

Copiar propriedades da atividade

Azure Cosmos DB para MongoDB como origem

Azure Cosmos DB para MongoDB como coletor

Importar e exportar documentos JSON

Mapeamento de esquema

Conteúdos relacionados

Comentários

Recursos adicionais