Copiar e transformar dados no Azure Cosmos DB para NoSQL usando o Azure Data Factory

APLICA-SE A: Azure Data Factory Azure Synapse Analytics

Este artigo descreve como usar o Copy Activity no Azure Data Factory para copiar dados do e para o Azure Cosmos DB para NoSQL, e usar o Fluxo de Dados para transformar dados no Azure Cosmos DB para NoSQL. Para saber mais, leia os artigos introdutórios para Azure Data Factory e Azure Synapse Analytics.

Capacidades suportadas

Este conector Azure Cosmos DB para NoSQL suporta as seguintes capacidades:

(1) Runtime de integração Azure (2) Runtime de integração auto-hospedado

Para atividade Copy, este conector Azure Cosmos DB for NoSQL suporta:

• Copie dados do e para o Azure Cosmos DB para NoSQL usando key, service principal ou identidades geridas para autenticações de recursos do Azure.
• Escreva para Azure Cosmos DB como insert ou upsert.
• 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 tal como estão para ou a partir de ficheiros JSON ou para ou a partir de outra coleção do Azure Cosmos DB, consulte Importar e exportar documentos JSON.

Os pipelines do Data Factory e do Synapse integram-se com a biblioteca Azure Cosmos DB bulk executor para proporcionar o melhor desempenho ao escrever no Azure Cosmos DB.

Introdução

Para executar a atividade de cópia com um pipeline, você pode usar uma das seguintes ferramentas ou SDKs:

• Ferramenta Copiar dados
• Portal do Azure
• .NET SDK
• Python SDK
• Azure PowerShell
• API REST
• Modelo do Azure Resource Manager

Criar um serviço ligado para o Azure Cosmos DB usando a interface de utilizador

Use os passos seguintes para criar um serviço ligado ao Azure Cosmos DB na interface do portal Azure.

1. Vá ao separador Gerir no seu espaço de trabalho Azure Data Factory ou Synapse e selecione Serviços Ligados. Depois seleciona Novo:

   • Fábrica de Dados do Azure
   • Azure Synapse

   

2. Procure Azure Cosmos DB para NoSQL e selecione o Azure Cosmos DB para conector NoSQL.

   

3. Configure os detalhes do serviço, teste a conexão e crie o novo serviço vinculado.

   

Detalhes de configuração do conector

As secções seguintes fornecem detalhes sobre propriedades que pode usar para definir entidades específicas do Azure Cosmos DB para NoSQL.

Propriedades do serviço vinculado

O conector Azure Cosmos DB for NoSQL suporta os seguintes tipos de autenticação. Para mais detalhes, veja as secções correspondentes:

• Autenticação de chave
• Autenticação do principal de serviço
• Autenticação de identidade gerenciada atribuída pelo sistema
• Autenticação de identidade gerenciada atribuída pelo usuário

Autenticação da chave

| Propriedade | Descrição | Obrigatório | |:--- |:--- |:--- | | tipo | Defina a propriedade de tipo para CosmosDb. | Sim | | connectionString | Especifique a informação necessária para se ligar à base de dados do Azure Cosmos DB. Nota: Deve especificar a informação da base de dados na cadeia de ligação, conforme mostrado nos exemplos seguintes. Também podes guardar a chave da conta no Azure Key Vault e remover a accountKey configuração da cadeia de ligação. Para mais informações, consulte os seguintes exemplos e armazene as credenciais no Azure Key Vault. |Sim | | connectVia | O Integration Runtime para usar para se ligar ao armazenamento de dados. Use o Azure Integration Runtime ou um integration runtime auto-hospedado (se o seu armazenamento de dados estiver numa rede privada). Se não especificares esta propriedade, usa-se a Azure Integration Runtime padrão. |Não |

Example

{
    "name": "CosmosDbSQLAPILinkedService",
    "properties": {
        "type": "CosmosDb",
        "typeProperties": {
            "connectionString": "AccountEndpoint=<EndpointUrl>;AccountKey=<AccessKey>;Database=<Database>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Exemplo: armazenar a chave da conta em Azure Key Vault

{
    "name": "CosmosDbSQLAPILinkedService",
    "properties": {
        "type": "CosmosDb",
        "typeProperties": {
            "connectionString": "AccountEndpoint=<EndpointUrl>;Database=<Database>",
            "accountKey": { 
                "type": "AzureKeyVaultSecret", 
                "store": { 
                    "referenceName": "<Azure Key Vault linked service name>", 
                    "type": "LinkedServiceReference" 
                }, 
                "secretName": "<secretName>" 
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Autenticação do principal de serviço

Para usar a autenticação da entidade de serviço, siga estas etapas.

1. Registe uma aplicação na plataforma de identidades da Microsoft. Para saber como, veja Quickstart: Registe uma candidatura com a plataforma de identidades da Microsoft. Anote estes valores, que você usa para definir o serviço vinculado:

   • ID da aplicação
   • Chave de aplicação
   • ID do inquilino

2. Conceda à entidade de serviço a permissão adequada. Veja exemplos sobre como funcionam as permissões em Azure Cosmos DB a partir de listas de controlo de acesso em ficheiros e diretórios. Mais especificamente, crie uma definição de função e atribua a função à entidade de serviço por meio da ID do objeto da entidade de serviço.

O serviço ligado suporta estas propriedades:

Exemplo: usando a autenticação de chave da entidade de serviço

Também pode armazenar a chave principal de serviço no Azure Key Vault.

{
    "name": "CosmosDbSQLAPILinkedService",
    "properties": {
        "type": "CosmosDb",
        "typeProperties": {
            "accountEndpoint": "<account endpoint>",
            "database": "<database name>",
            "servicePrincipalId": "<service principal id>",
            "servicePrincipalCredentialType": "ServicePrincipalKey",
            "servicePrincipalCredential": {
                "type": "SecureString",
                "value": "<service principal key>"
            },
            "tenant": "<tenant info, e.g. microsoft.onmicrosoft.com>" 
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Exemplo: usando a autenticação de certificado da entidade de serviço

{
    "name": "CosmosDbSQLAPILinkedService",
    "properties": {
        "type": "CosmosDb",
        "typeProperties": {
            "accountEndpoint": "<account endpoint>",
            "database": "<database name>", 
            "servicePrincipalId": "<service principal id>",
            "servicePrincipalCredentialType": "ServicePrincipalCert",
            "servicePrincipalCredential": { 
                "type": "AzureKeyVaultSecret", 
                "store": { 
                    "referenceName": "<AKV reference>", 
                    "type": "LinkedServiceReference" 
                }, 
                "secretName": "<certificate name in AKV>" 
            },
            "tenant": "<tenant info, e.g. microsoft.onmicrosoft.com>" 
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Autenticação de identidade gerenciada atribuída pelo sistema

Pode associar uma fábrica de dados ou pipeline Synapse a uma identidade gerida atribuída pelo sistema para recursos do Azure, que representa esta instância de serviço específica. Pode usar esta identidade gerida diretamente para autenticação do Azure Cosmos DB, de forma semelhante ao uso do seu próprio principal de serviço. Concede a este recurso designado acesso para copiar dados para ou a partir da sua instância do Azure Cosmos DB.

Para usar identidades geridas atribuídas pelo sistema para autenticação de recursos no Azure, siga estes passos.

1. Recupere as informações de identidade gerida atribuídas pelo sistema copiando o valor do ID do objeto de identidade gerida gerado juntamente com o seu serviço.

2. Conceda à identidade gerenciada atribuída pelo sistema a permissão adequada. Veja exemplos sobre como funcionam as permissões em Azure Cosmos DB a partir de listas de controlo de acesso em ficheiros e diretórios. Mais especificamente, crie uma definição de função e atribua a função à identidade gerenciada atribuída ao sistema.

O serviço ligado suporta estas propriedades:

Example:

{
    "name": "CosmosDbSQLAPILinkedService",
    "properties": {
        "type": "CosmosDb",
        "typeProperties": {
            "accountEndpoint": "<account endpoint>",
            "database": "<database name>",
            "subscriptionId": "<subscription id>",
            "tenantId": "<tenant id>",
            "resourceGroup": "<resource group>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Autenticação de identidade gerenciada atribuída pelo usuário

Pode associar uma fábrica de dados ou pipeline Synapse a identidades geridas atribuídas pelo utilizador, que representam instâncias específicas de serviço. Use esta identidade gerida diretamente para autenticação do Azure Cosmos DB, semelhante a usar o seu próprio principal de serviço. Concede a este recurso designado acesso para copiar dados para ou a partir da sua instância do Azure Cosmos DB.

Para usar identidades geridas atribuídas pelo utilizador para autenticação de recursos no Azure, siga estes passos.

1. Crie uma ou várias identidades gerenciadas atribuídas pelo usuário e conceda à identidade gerenciada atribuída pelo usuário a permissão adequada. Veja exemplos sobre como funcionam as permissões em Azure Cosmos DB a partir de listas de controlo de acesso em ficheiros e diretórios. Mais especificamente, crie uma definição de função e atribua a função à identidade gerenciada atribuída pelo usuário.

2. Atribua uma ou várias identidades gerenciadas atribuídas pelo usuário ao seu data factory e crie credenciais para cada identidade gerenciada atribuída pelo usuário.

O serviço ligado suporta estas propriedades:

Example:

{
    "name": "CosmosDbSQLAPILinkedService",
    "properties": {
        "type": "CosmosDb",
        "typeProperties": {
            "accountEndpoint": "<account endpoint>",
            "database": "<database name>",
            "credential": {
                "referenceName": "credential1",
                "type": "CredentialReference"
            },
            "subscriptionId": "<subscription id>",
            "tenantId": "<tenant id>",
            "resourceGroup": "<resource group>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Propriedades do conjunto de dados

Para uma lista completa de secções e propriedades que pode usar para definir conjuntos de dados, consulte Conjuntos de dados e serviços ligados.

As seguintes propriedades são suportadas para o conjunto de dados Azure Cosmos DB for NoSQL:

Se usares o conjunto de dados do tipo DocumentDbCollection, Azure Data Factory ainda o suporta as-is para compatibilidade retroativa para atividades de Copiar e Procurar. Não é suportado para Fluxo de Dados. Use o novo modelo daqui para a frente.

Example

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

Copiar propriedades da atividade

Esta secção fornece uma lista das propriedades suportadas pela fonte e pelo destino no Azure Cosmos DB para NoSQL. Para obter uma lista completa de seções e propriedades disponíveis para definir atividades, consulte Pipelines.

Azure Cosmos DB for NoSQL como origem

A secção de origem da Atividade de Cópia suporta as seguintes propriedades:

Exemplo: SELECT c.BusinessEntityID, c.Name.First AS FirstName, c.Name.Middle AS MiddleName, c.Name.Last AS LastName, c.Suffix, c.EmailPromotion FROM c WHERE c.ModifiedDate > \"2009-01-01T00:00:00\" |Não

Se não especificar esta propriedade, o serviço executa a seguinte instrução SQL: select from mycollection | | preferredRegions | A lista preferida de regiões a que se pode ligar ao recuperar dados do Azure Cosmos DB. | Não | | Tamanho da página | O número de documentos por página do resultado da consulta. O padrão é "-1", o que significa que usa o tamanho de página dinâmico definido no lado do serviço, até um máximo de 1000. | Não | | detectDatetime | Se deve detetar data-hora a partir dos valores das strings nos documentos. Os valores permitidos são: true (padrão), false. | Não |

Para compatibilidade retroativa, o serviço continua a suportar a fonte do tipo "DocumentDbCollectionSource". Use o novo modelo daqui para a frente, que oferece capacidades mais avançadas para copiar dados do Azure Cosmos DB.

Example

"activities":[
    {
        "name": "CopyFromCosmosDBSQLAPI",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<Cosmos DB for NoSQL input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "CosmosDbSqlApiSource",
                "query": "SELECT c.BusinessEntityID, c.Name.First AS FirstName, c.Name.Middle AS MiddleName, c.Name.Last AS LastName, c.Suffix, c.EmailPromotion FROM c WHERE c.ModifiedDate > \"2009-01-01T00:00:00\"",
                "preferredRegions": [
                    "East US"
                ]
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

Ao copiar dados de Azure Cosmos DB, a menos que queira exportar documentos JSON as-is, especifique o mapeamento na atividade de cópia. O serviço honra o mapeamento que especificaste na atividade – se uma linha não contiver um valor para uma coluna, o serviço fornece um valor nulo para o valor da coluna. Se você não especificar um mapeamento, o serviço inferirá o esquema usando a primeira linha nos dados. Se a primeira linha não contiver o esquema completo, algumas colunas faltam no resultado da operação de atividade.

Azure Cosmos DB para NoSQL como destino

Para copiar dados para Azure Cosmos DB para NoSQL, defina o tipo sink em Copy Activity para DocumentDbCollectionSink.

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

Se você usar a fonte do tipo "DocumentDbCollectionSink", ela ainda terá suporte as-is para compatibilidade com versões anteriores. Sugere-se que use o novo modelo daqui para a frente, que oferece capacidades mais avançadas para copiar dados do Azure Cosmos DB.

Example

"activities":[
    {
        "name": "CopyToCosmosDBSQLAPI",
        "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": "CosmosDbSqlApiSink",
                "writeBehavior": "upsert"
            }
        }
    }
]

Mapeamento de esquema

Para copiar dados do Azure Cosmos DB para o sumidouro tabular ou vice-versa, consulte o mapeamento de esquema.

Mapeando propriedades de fluxo de dados

Ao transformar dados num fluxo de mapeamento de dados, pode ler e escrever em coleções no Azure Cosmos DB. Para obter mais informações, consulte a transformação de origem e a transformação de coletor no mapeamento de fluxos de dados.

Transformação da fonte

Definições específicas para Azure Cosmos DB estão disponíveis no separador Opções de Origem da transformação de origem.

Inclua as colunas do sistema: Se for verdade, id, _ts e outras colunas do sistema são incluídas nos metadados do seu fluxo de dados de Azure Cosmos DB. Ao atualizar coleções, é importante incluir isso para que você possa pegar o ID de linha existente.

Tamanho da página: o número de documentos por página do resultado da consulta. O padrão é "-1", que usa a página dinâmica do serviço até 1000.

Throughput: Defina um valor opcional para o número de RUs que pretende aplicar à sua coleção de Azure Cosmos DB para cada execução deste fluxo de dados durante a operação de leitura. O mínimo é de 400.

Regiões preferidas: escolha as regiões de leitura preferidas para este processo.

Change feed: Se for verdade, receberá dados de Azure Cosmos DB change feed que é um registo persistente das alterações num contentor pela ordem em que ocorrem desde a última execução, automaticamente. Quando o definir como verdadeiro, não defina tanto Inferir tipos de coluna desviados quanto Permitir desvio de schema como verdadeiro ao mesmo tempo. Para mais detalhes, consulte feed de alterações do Azure Cosmos DB).

Comece do início: Se verdadeiro, você obterá a carga inicial de dados de instantâneo completos na primeira execução, seguida pela captura de dados alterados nas próximas execuções. Se falso, a carga inicial será omitida na primeira execução, seguida pela captura de dados alterados nas próximas execuções. A configuração está alinhada com o mesmo nome de configuração na referência do Azure Cosmos DB. Para mais informações, consulte Azure Cosmos DB change feed.

Transformação do lavatório

As definições específicas do Azure Cosmos DB estão disponíveis no separador Settings da transformação de destino.

Método de atualização: determina quais operações são permitidas no destino do banco de dados. O padrão é permitir apenas inserções. Para atualizar, atualizar ou excluir linhas, uma transformação de linha de alteração é necessária para marcar linhas para essas ações. Para atualizações, upserts e exclusões, uma coluna ou colunas de chave devem ser definidas para determinar qual linha alterar.

Ação de coleção: Determina se a coleção de destino deve ser recriada antes de escrever.

• Nenhuma: Nenhuma ação será tomada em relação à coleção.
• Recriar: A coleção será descartada e recriada

Tamanho do lote: Um inteiro que representa quantos objetos estão a ser gravados na coleção de Azure Cosmos DB em cada lote. Normalmente, começar com o tamanho de lote padrão é suficiente. Para ajustar ainda mais esse valor, observe:

• O Azure Cosmos DB limita o tamanho de um único pedido a 2MB. A fórmula é "Tamanho do Pedido = Tamanho do Documento Único * Tamanho do Lote". Se encontrar um erro que diga "O tamanho do pedido é demasiado grande", reduza o valor do tamanho do lote.
• Quanto maior o tamanho do lote, melhor taxa de transferência o serviço pode alcançar, ao mesmo tempo em que se certifica de alocar RUs suficientes para capacitar sua carga de trabalho.

Chave de partição: insira uma cadeia de caracteres que represente a chave de partição para sua coleção. Exemplo: /movies/title

Throughput: Defina um valor opcional para o número de RUs que deseja aplicar à sua coleção de Azure Cosmos DB para cada execução deste fluxo de dados. O mínimo é de 400.

Write throughput budget: Um inteiro que representa as RUs que pretende alocar para esta operação de escrita Fluxo de Dados, a partir do throughput total alocado à coleção.

Propriedades da atividade de consulta

Para saber detalhes sobre as propriedades, verifique a atividade de pesquisa.

Importar e exportar documentos JSON

Use este conector Azure Cosmos DB para NoSQL de forma muito fácil:

• Copie documentos entre duas coleções do Azure Cosmos DB tal como estão.
• Importar documentos JSON de várias fontes para o Azure Cosmos DB, incluindo do armazenamento Azure Blob, Azure Data Lake Store e outros armazenamentos baseados em ficheiros que o serviço suporta.
• Exporte documentos JSON de uma coleção do Azure Cosmos DB para várias lojas baseadas em ficheiros.

Para obter uma cópia independente do esquema:

• Quando usar a ferramenta Copiar Dados, selecione a opção Exportar as-is para ficheiros JSON ou Azure Cosmos DB collection.
• Ao utilizar a autoria de atividades, escolha o formato JSON com o armazenamento de ficheiros correspondente para origem ou destino.

Migrar de base de dados relacional para Azure Cosmos DB

Quando migra de uma base de dados relacional, como o SQL Server para o Azure Cosmos DB, a atividade de cópia pode facilmente mapear dados tabulares da fonte para achatar documentos JSON no Azure Cosmos DB. Em alguns casos, pode querer redesenhar o modelo de dados para o otimizar para os casos de uso do NoSQL de acordo com a modelação de dados no Azure Cosmos DB, como desnormalizar os dados incorporando todos os subitens relacionados num único documento JSON. Para esse caso, consulte este artigo com um guia guia sobre como o conseguir usando a atividade de cópia.

Azure Cosmos DB change feed (alimentação de alterações)

Azure Data Factory pode obter dados de Azure Cosmos DB change feed ativando-os na transformação de fonte de fluxo de dados de mapeamento. Ao usar esta opção de conector, pode ler os feeds de alterações e aplicar transformações antes de carregar dados transformados nos conjuntos de dados de destino à sua escolha. Não precisas de usar funções do Azure para ler o feed de alterações e depois escrever transformações personalizadas. Use esta opção para mover dados de um contentor para outro, preparar vistas de material baseadas em feed de alterações para fins adequados, automatizar backup ou recuperação de contentores com base no feed de alterações, e permitir muitos mais casos de uso semelhantes usando a capacidade visual de arrastar e largar do Azure Data Factory.

Certifique-se de manter a pipeline e o nome da atividade inalterada, para que o ponto de verificação possa ser registado pelo ADF e permitir que você obtenha automaticamente os dados alterados da última execução. Se mudares o nome do pipeline ou da atividade, o checkpoint reinicia-se, o que te leva a começar do início ou a fazer alterações a partir de agora na próxima corrida. Quando depuras o pipeline, esta funcionalidade funciona da mesma forma. Tenha em atenção que o checkpoint reinicia quando atualiza o navegador durante a execução de depuração. Depois de estar satisfeito com o resultado do pipeline da execução de depuração, você pode continuar a publicar e acionar o pipeline. No momento em que você aciona o pipeline publicado pela primeira vez, ele é reiniciado automaticamente desde o início ou recebe alterações a partir de agora.

Na seção de monitoramento, você sempre tem a chance de executar novamente um pipeline. Quando você está fazendo isso, os dados alterados são sempre capturados do ponto de verificação anterior da execução do pipeline selecionado.

Além disso, o Azure Cosmos DB analytical store agora suporta Change Data Capture (CDC) para Azure Cosmos DB API para NoSQL e Azure Cosmos DB API para Mongo DB (pré-visualização pública). O Azure Cosmos DB analytical store permite-lhe consumir de forma eficiente um fluxo contínuo e incremental de dados alterados (inseridos, atualizados e eliminados) a partir do analytical store.

Conteúdo relacionado

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