Copiar dados para ou a partir do Azure Data Explorer usando Azure Data Factory ou Synapse Analytics

APLICA-SE A: Azure Data Factory Azure Synapse Analytics

Este artigo descreve como utilizar a atividade de cópia nos pipelines Azure Data Factory e Synapse Analytics para copiar dados para ou de Azure Data Explorer. Ele se baseia no artigo de visão geral da atividade de cópia, que oferece uma visão geral da atividade de cópia.

Capacidades suportadas

Este conector Azure Data Explorer é suportado para as seguintes capacidades:

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

Pode copiar dados de qualquer armazenamento de dados de origem suportado para o Azure Data Explorer. Também pode copiar dados do Azure Data Explorer para qualquer repositório de dados de destino suportado. Para obter uma lista de armazenamentos de dados que a atividade de cópia suporta como fontes ou destinos, consulte a tabela de armazenamentos de dados suportados.

Com o conector Azure Data Explorer, pode fazer o seguinte:

• Copiar dados usando autenticação de token de aplicação do Microsoft Entra com um principal de serviço .
• Como fonte, recupere dados usando uma consulta KQL (Kusto).
• Como um coletor, acrescente dados a uma tabela de destino.

Começar

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 ao Azure Data Explorer usando UI

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

1. Navegue até ao separador Gerir no seu espaço de trabalho Azure Data Factory ou Synapse e selecione Serviços Ligados, depois clique em Novo:

   • Azure Data Factory
   • Azure Synapse

   

2. Procure por Explorer e selecione o conector Azure Data Explorer (Kusto).

   

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 são usadas para definir entidades específicas do conector Azure Data Explorer.

Propriedades do serviço vinculado

O conector Azure Data Explorer suporta os seguintes tipos de autenticação. Consulte as seções correspondentes para obter detalhes:

• 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 do principal de serviço

Para usar a autenticação da entidade de serviço, siga estas etapas para obter uma entidade de serviço e conceder permissões:

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 de Locatário

2. Conceda ao principal do serviço as permissões corretas no Azure Data Explorer. Consulte Gerenciar permissões Azure Data Explorer bases de dados para informações detalhadas sobre funções e permissões e sobre gestão de permissões. Em geral, deve:

   • Como origem, conceda pelo menos a função de visualizador de banco de dados ao seu banco de dados
   • Como sink, conceda pelo menos a função de Utilizador da Base de Dados ao seu banco de dados

As seguintes propriedades são suportadas para o serviço ligado Azure Data Explorer:

Exemplo: usando autenticação por chave do principal de serviço

{
    "name": "AzureDataExplorerLinkedService",
    "properties": {
        "type": "AzureDataExplorer",
        "typeProperties": {
            "endpoint": "https://<clusterName>.<regionName>.kusto.windows.net ",
            "database": "<database name>",
            "tenant": "<tenant name/id e.g. microsoft.onmicrosoft.com>",
            "servicePrincipalId": "<service principal id>",
            "servicePrincipalKey": {
                "type": "SecureString",
                "value": "<service principal key>"
            }
        }
    }
}

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

Para saber mais sobre identidades geridas para recursos Azure, consulte Identidades geridas para recursos Azure.

Para usar a autenticação de identidade gerenciada atribuída pelo sistema, siga estas etapas para conceder permissões:

1. Recupere as informações de identidade geridas copiando o valor do ID do objeto de identidade geridas gerado juntamente com a sua fábrica ou com o espaço de trabalho Synapse.

2. Conceda à identidade gerida as permissões corretas no Azure Data Explorer. Consulte Gerenciar permissões Azure Data Explorer bases de dados para informações detalhadas sobre funções e permissões e sobre gestão de permissões. Em geral, deve:

   • Como origem, conceda a função Visualizador de banco de dados ao seu banco de dados.
   • Como coletor, conceda as funções Ingestor de banco de dados e Visualizador de banco de dados ao seu banco de dados.

As seguintes propriedades são suportadas para o serviço ligado Azure Data Explorer:

Exemplo: usando autenticação de identidade gerenciada atribuída pelo sistema

{
    "name": "AzureDataExplorerLinkedService",
    "properties": {
        "type": "AzureDataExplorer",
        "typeProperties": {
            "endpoint": "https://<clusterName>.<regionName>.kusto.windows.net ",
            "database": "<database name>",
        }
    }
}

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

Para saber mais sobre identidades geridas para recursos Azure, consulte Identidades geridas para recursos Azure

Para usar a autenticação de identidade gerenciada atribuída pelo usuário, siga estas etapas:

1. Crie uma ou várias identidades geridas atribuídas pelo utilizador e conceda permissão em Azure Data Explorer. Consulte Gerenciar permissões Azure Data Explorer bases de dados para informações detalhadas sobre funções e permissões e sobre gestão de permissões. Em geral, deve:

   • Como origem, conceda pelo menos a função de visualizador de banco de dados ao seu banco de dados
   • Como destino, conceda pelo menos a função de ingestor de bases de dados ao seu banco de dados

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

As seguintes propriedades são suportadas para o serviço ligado Azure Data Explorer:

Exemplo: usando a autenticação de identidade gerenciada atribuída pelo usuário

{
    "name": "AzureDataExplorerLinkedService",
    "properties": {
        "type": "AzureDataExplorer",
        "typeProperties": {
            "endpoint": "https://<clusterName>.<regionName>.kusto.windows.net ",
            "database": "<database name>",
            "credential": {
                "referenceName": "credential1",
                "type": "CredentialReference"
            }
        }
    }
}

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. Esta secção lista as propriedades que o conjunto de dados Azure Data Explorer suporta.

Para copiar dados para Azure Data Explorer, defina a propriedade de tipo do conjunto de dados para AzureDataExplorerTable.

As seguintes propriedades são suportadas:

Exemplo de propriedades de conjunto de dados:

{
   "name": "AzureDataExplorerDataset",
    "properties": {
        "type": "AzureDataExplorerTable",
        "typeProperties": {
            "table": "<table name>"
        },
        "schema": [],
        "linkedServiceName": {
            "referenceName": "<Azure Data Explorer linked service name>",
            "type": "LinkedServiceReference"
        }
    }
}

Propriedades da atividade de cópia

Para obter uma lista completa de seções e propriedades disponíveis para definir atividades, consulte Pipelines e atividades. Esta secção fornece uma lista de propriedades que o Azure Data Explorer suporta fontes e sinks.

Azure Data Explorer como fonte

Para copiar dados de Azure Data Explorer, defina a propriedade type na fonte atividade Copy para AzureDataExplorerSource. As seguintes propriedades são suportadas na seção de origem da atividade de cópia:

Exemplo:

"activities":[
    {
        "name": "CopyFromAzureDataExplorer",
        "type": "Copy",
        "typeProperties": {
            "source": {
                "type": "AzureDataExplorerSource",
                "query": "TestTable1 | take 10",
                "queryTimeout": "00:10:00"
            },
            "sink": {
                "type": "<sink type>"
            }
        },
        "inputs": [
            {
                "referenceName": "<Azure Data Explorer input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ]
    }
]

Azure Data Explorer como destino

Para copiar dados para o Azure Data Explorer, configure a propriedade type no destino da atividade de cópia para AzureDataExplorerSink. As seguintes propriedades são suportadas na seção coletor de atividade de cópia:

Exemplo:

"activities":[
    {
        "name": "CopyToAzureDataExplorer",
        "type": "Copy",
        "typeProperties": {
            "source": {
                "type": "<source type>"
            },
            "sink": {
                "type": "AzureDataExplorerSink",
                "ingestionMappingName": "<optional Azure Data Explorer mapping name>",
                "additionalProperties": {<additional settings for data ingestion>}
            }
        },
        "inputs": [
            {
                "referenceName": "<input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<Azure Data Explorer output dataset name>",
                "type": "DatasetReference"
            }
        ]
    }
]

Mapeando propriedades de fluxo de dados

Ao transformar dados no mapeamento do fluxo de dados, pode ler e escrever em tabelas no Azure Data Explorer. Para obter mais informações, consulte a transformação de origem e a transformação de coletor no mapeamento de fluxos de dados. Pode optar por usar um conjunto de dados Azure Data Explorer ou um conjunto de dados inline como tipo de origem e sumidouro.

Transformação da fonte

A tabela abaixo lista as propriedades suportadas pelo Azure Data Explorer source. Você pode editar essas propriedades na guia Opções de origem .

Exemplos de scripts de origem do Azure Data Explorer

Quando utiliza o conjunto de dados do Azure Data Explorer como tipo de fonte, o script de fluxo de dados associado é:

source(allowSchemaDrift: true,
	validateSchema: false,
	query: 'table | take 10',
	format: 'query') ~> AzureDataExplorerSource

Se você usar o conjunto de dados embutido, o script de fluxo de dados associado será:

source(allowSchemaDrift: true,
    validateSchema: false,
    format: 'query',
    query: 'table | take 10',
    store: 'azuredataexplorer') ~> AzureDataExplorerSource

Transformação do lavatório

A tabela abaixo lista as propriedades suportadas pelo Azure Data Explorer sink. Você pode editar essas propriedades na guia Configurações. Ao usar o conjunto de dados embutido, você verá configurações adicionais, que são as mesmas que as propriedades descritas na seção de propriedades do conjunto de dados.

Azure Data Explorer exemplos de scripts de destino

Quando usa o conjunto de dados do Azure Data Explorer como tipo sink, o script de fluxo de dados associado é:

IncomingStream sink(allowSchemaDrift: true,
	validateSchema: false,
	format: 'table',
	preSQLs:['pre SQL scripts'],
	postSQLs:['post SQL script'],
	skipDuplicateMapInputs: true,
	skipDuplicateMapOutputs: true) ~> AzureDataExplorerSink

Se você usar o conjunto de dados embutido, o script de fluxo de dados associado será:

IncomingStream sink(allowSchemaDrift: true,
    validateSchema: false,
    format: 'table',
    store: 'azuredataexplorer',
    skipDuplicateMapInputs: true,
    skipDuplicateMapOutputs: true) ~> AzureDataExplorerSink

Propriedades da atividade de consulta

Para obter mais informações sobre as propriedades, consulte Atividade de Pesquisa.

Conteúdos relacionados

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

• Saiba mais sobre como copiar dados da Azure Data Factory e da Synapse Analytics para Azure Data Explorer.