Copiar dados de ou para Azure Data Explorer usando o Azure Data Factory ou o Synapse Analytics

APLICA-SE A: Azure Data Factory Azure Synapse Analytics

Este artigo descreve como usar a atividade de cópia em pipelines do Azure Data Factory e do Synapse Analytics para copiar dados de ou para Azure Data Explorer. Ele é baseado no artigo Visão geral da atividade Copy, que apresenta uma visão geral ampla da atividade Copy.

Funcionalidades com suporte

Esse conector Azure Data Explorer tem suporte para os seguintes recursos:

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

Você pode copiar dados de qualquer armazenamento de dados de origem com suporte para Azure Data Explorer. Você também pode copiar dados do Azure Data Explorer para qualquer armazenamento de dados de coletor com suporte. Para ver uma lista de armazenamentos de dados com suporte da atividade Copy como origens ou coletores, confira a tabela Armazenamentos de dados com suporte.

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

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

Introdução

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

• Ferramenta Copiar Dados
• Azure portal
• .NET SDK
• SDK Python
• Azure PowerShell
• REST API
• modelo Azure Resource Manager

Criar um serviço vinculado para Azure Data Explorer usando a interface do usuário

Use as etapas a seguir para criar um serviço vinculado para Azure Data Explorer na interface do usuário do portal Azure.

1. Navegue até a guia Gerenciar no workspace do Azure Data Factory ou do Synapse e selecione Serviços Vinculados e clique em Novo:

   • Azure Data Factory
   • Azure Synapse

   

2. Pesquise pelo Explorer e selecione o conector do Azure Data Explorer (Kusto).

   

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

Propriedades do serviço vinculado

O conector Azure Data Explorer dá suporte aos seguintes tipos de autenticação. Consulte as seções correspondentes para obter detalhes:

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

Autenticação de entidade 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. Registre um aplicativo com o plataforma de identidade da Microsoft. Para saber como, consulte Quickstart: Registrar um aplicativo com o plataforma de identidade da Microsoft. Anote estes valores; ele são usados para definir o serviço vinculado:

   • ID do aplicativo
   • Chave do aplicativo
   • ID do locatário

2. Conceda à entidade de serviço as permissões corretas no Azure Data Explorer. Consulte Manage Azure Data Explorer permissões de banco de dados para obter informações detalhadas sobre funções e permissões e sobre o gerenciamento de permissões. Em geral, você precisa:

   • Como fonte, conceder pelo menos a função Visualizador de banco de dados ao banco de dados
   • Como um coletor, conceder pelo menos a função de Usuário de banco de dados ao banco de dados

As propriedades a seguir têm suporte para o serviço vinculado Azure Data Explorer:

Exemplo: usar a autenticação de chave de entidade 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 gerenciadas para recursos do Azure, consulte Identidades Gerenciadas para Recursos do Azure.

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

1. Recuperar as informações de identidade gerenciada copiando o valor de ID do objeto de identidade gerenciada gerado junto com seu alocador ou no Synapse Workspace.

2. Conceda à identidade gerenciada as permissões corretas no Azure Data Explorer. Consulte Manage Azure Data Explorer permissões de banco de dados para obter informações detalhadas sobre funções e permissões e sobre o gerenciamento de permissões. Em geral, você precisa:

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

As propriedades a seguir têm suporte para o serviço vinculado Azure Data Explorer:

Exemplo: usar a 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 gerenciadas para recursos do Azure, consulte Identidades gerenciadas para recursos do Azure

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

1. Criar uma ou várias identidades gerenciadas atribuídas pelo usuário e conceder permissão no Azure Data Explorer. Consulte Manage Azure Data Explorer permissões de banco de dados para obter informações detalhadas sobre funções e permissões e sobre o gerenciamento de permissões. Em geral, você precisa:

   • Como fonte, conceder pelo menos a função Visualizador de banco de dados ao banco de dados
   • Como coletor, conceder pelo menos a função Ingestor de banco de dados ao banco de dados

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

As propriedades a seguir têm suporte para o serviço vinculado Azure Data Explorer:

Exemplo: usar 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 das seções e propriedades disponíveis para definir os conjuntos de dados, confira Conjuntos de dados. Esta seção lista as propriedades compatíveis com o conjunto de dados Azure Data Explorer.

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

Há suporte para as seguintes propriedades:

Exemplo de propriedades do 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 das seções e propriedades disponíveis para definir as atividades, confira Pipelines e atividades. Esta seção fornece uma lista de propriedades que o Azure Data Explorer suporta em origens e destinos.

Azure Data Explorer como origem

Para copiar dados de Azure Data Explorer, defina a propriedade type na fonte atividade Copy como AzureDataExplorerSource. As propriedades a seguir têm suporte na seção source 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 coletor

Para copiar dados do Azure Data Explorer, defina a propriedade type no coletor da atividade de cópia como AzureDataExplorerSink. As propriedades a seguir têm suporte na seção sink da 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"
            }
        ]
    }
]

Propriedades do fluxo de dados de mapeamento

Ao transformar dados no fluxo de dados de mapeamento, você pode ler e gravar em tabelas em Azure Data Explorer. Para obter mais informações, confira transformação de origem e transformação do coletor nos fluxos de dados de mapeamento. Você pode optar por usar um conjunto de dados Azure Data Explorer ou um conjunto de dados inline como tipo de origem e coletor.

Transformação de origem

A tabela abaixo lista as propriedades compatíveis na fonte do Azure Data Explorer. Você pode editar essas propriedades na guia Opções de origem.

Exemplos de scripts de origem do Azure Data Explorer

Quando você usa Azure Data Explorer conjunto de dados como tipo de origem, o script de fluxo de dados associado é:

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

Se você usar um conjuntos 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 de coletor

A tabela abaixo lista as propriedades compatíveis com o coletor do Azure Data Explorer. Você pode editar essas propriedades na guia Configurações. Ao usar o conjunto de dados embutido, será possível ver configurações de arquivo adicionais, que são as mesmas das propriedades descritas na seção Propriedades do conjunto de dados.

exemplos de script para destino de dados do Azure Data Explorer

Quando você usa um conjunto de dados do Azure Data Explorer como tipo de destino, 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 um conjuntos 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

Pesquisar propriedades de atividade

Para obter mais informações sobre as propriedades, confira Atividade de pesquisa.

Conteúdo relacionado

• Para obter uma lista de armazenamentos de dados que a atividade Copy suporta, como fontes e coletores, consulte Armazenamentos de dados compatíveis.

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