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

APLICA-SE A: Azure Data Factory Azure Synapse Analytics

Este artigo descreve como usar a atividade Copy no Azure Data Factory ou Synapse Analytics para copiar dados do Azure Data Explorer ou para ele. 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 do Azure Data Explorer tem suporte para as seguintes funcionalidades:

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

Você pode copiar dados de qualquer armazenamento de dados de origem com suporte para o 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 do 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, será possível usar as ferramentas ou os SDKs abaixo:

• A ferramenta Copiar Dados
• O portal do Azure
• O SDK do .NET
• O SDK do Python
• PowerShell do Azure
• A API REST
• O modelo do Azure Resource Manager

Criar um serviço vinculado ao Azure Data Explorer com a interface do usuário

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

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

   • Azure Data Factory
   • Azure Synapse

   

2. Pesquise 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 da configuração do conector

As seções abaixo fornecem detalhes sobre as propriedades que são usadas para definir entidades específicas ao conector do Azure Data Explorer.

Propriedades do serviço vinculado

O conector do Azure Data Explorer dá suporte aos tipos de autenticação a seguir. 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. Registrar um aplicativo na plataforma de identidade da Microsoft. Para saber como, confira Início Rápido: registrar um aplicativo na 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. Confira Gerenciar permissões de banco de dados do Azure Data Explorer para obter informações detalhadas sobre funções e permissões e sobre como gerenciar 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 seguintes propriedades têm suporte no serviço vinculado do 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 as identidades gerenciadas para recursos do Azure, confira 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. Confira Gerenciar permissões de banco de dados do Azure Data Explorer para obter informações detalhadas sobre funções e permissões e sobre como gerenciar 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 seguintes propriedades têm suporte no serviço vinculado do 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 as identidades gerenciadas para recursos do Azure, confira Identidades gerenciadas para recursos do Azure

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

1. Crie uma ou várias identidades gerenciadas atribuídas pelo usuário e conceda permissão no Azure Data Explorer. Confira Gerenciar permissões de banco de dados do Azure Data Explorer para obter informações detalhadas sobre funções e permissões e sobre como gerenciar 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 seguintes propriedades têm suporte no serviço vinculado do 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 a que o conjunto de dados do Azure Data Explorer dá suporte.

Para copiar dados para o 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 das propriedades com suporte das fontes e coletores do Azure Data Explorer.

Azure Data Explorer como fonte

Para copiar dados do Azure Data Explorer, defina a propriedade type na fonte da atividade de Cópia 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ê poderá ler e gravar em tabelas no 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 do Azure Data Explorer ou um conjunto de dados em linha como fonte e tipo de coletor.

Transformação de origem

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

Exemplos do script de origem do Azure Data Explorer

Quando você usa o conjunto de dados do Azure Data Explorer como tipo de origem, o script do 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 do script do coletor do Azure Data Explorer

Quando você usa o conjunto de dados do Azure Data Explorer como tipo de coletor, o script do 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 de Azure Data Factory e Synapse Analytics para o Azure Data Explorer.