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

  • Artigo

APLICA-SE A: Azure Data Factory Azure Synapse Analytics

Dica

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

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.

Dica

Para saber mais sobre a integração Azure Data Explorer com o serviço geralmente, eia Integrar Azure Data Explorer.

Funcionalidades com suporte

Esse conector do Azure Data Explorer tem suporte para as seguintes funcionalidades:

Funcionalidades com suporte IR
Atividade de cópia (origem/coletor) 6/6
Fluxo de dados de mapeamento (origem/coletor) 2
Atividade de pesquisa 6/6

① 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.

Observação

A cópia de dados do Azure Data Explorer ou para ele por meio de um armazenamento de dados local usando o runtime de integração auto-hospedada tem suporte na versão 3.14 e posteriores.

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

Dica

Para ver um passo a passo do conector do Azure Data Explorer, confira Copiar dados de/para o Azure Data Explorer e Cópia em massa de um banco de dados para o Azure Data Explorer.

Para executar a atividade de Cópia com um pipeline, será possível usar as ferramentas ou os SDKs abaixo:

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:

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

    Screenshot of the Azure Data Explorer (Kusto) connector.

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

    Screenshot of linked service configuration for Azure Data Explorer.

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

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

Observação

Quando você usa a interface do usuário para criação, por padrão, sua conta de usuário de logon é usada para listar clusters, bancos de dados e tabelas do Azure Data Explorer. Você pode optar por listar os objetos que estão usando a entidade de serviço clicando no menu suspenso ao lado do botão Atualizar ou por inserir manualmente o nome caso não tenha permissão para essas operações.

As seguintes propriedades têm suporte no serviço vinculado do Azure Data Explorer:

Propriedade Descrição Obrigatório
type A propriedade type deve ser definida como AzureDataExplorer. Sim
endpoint URL de ponto de extremidade do cluster do Azure Data Explorer com o formato https://<clusterName>.<regionName>.kusto.windows.net. Sim
Banco de Dados Nome do banco de dados. Sim
locatário Especifique as informações de locatário (domínio nome ou ID do Locatário) em que o aplicativo reside. Isso é conhecido como "ID de autoridade" na cadeia de conexão Kusto. Recupere-as passando o ponteiro do mouse no canto superior direito do portal do Azure. Sim
servicePrincipalId Especifique a ID do cliente do aplicativo. Isso é conhecido como "ID do cliente do aplicativo do Microsoft Entra" na cadeia de conexão Kusto. Sim
servicePrincipalKey Especifique a chave do aplicativo. Isso é conhecido como "chave do aplicativo do Microsoft Entra" na cadeia de conexão Kusto. Marque este campo como um SecureString para armazená-lo com segurança ou referencie um segredo armazenado no Azure Key Vault. Sim
connectVia O runtime de integração a ser usado para se conectar ao armazenamento de dados. Você pode usar o Azure Integration Runtime ou um runtime de integração auto-hospedada se o seu armazenamento de dados estiver em uma rede privada. Se não especificado, o Azure Integration Runtime padrão será usado. Não

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.

Observação

Quando você usa a interface do usuário para criação, sua conta de usuário de logon é usada para listar clusters, bancos de dados e tabelas do Azure Data Explorer. Insira o nome manualmente se você não tiver permissão para essas operações.

As seguintes propriedades têm suporte no serviço vinculado do Azure Data Explorer:

Propriedade Descrição Obrigatório
type A propriedade type deve ser definida como AzureDataExplorer. Sim
endpoint URL de ponto de extremidade do cluster do Azure Data Explorer com o formato https://<clusterName>.<regionName>.kusto.windows.net. Sim
Banco de Dados Nome do banco de dados. Sim
connectVia O runtime de integração a ser usado para se conectar ao armazenamento de dados. Você pode usar o Azure Integration Runtime ou um runtime de integração auto-hospedada se o seu armazenamento de dados estiver em uma rede privada. Se não especificado, o Azure Integration Runtime padrão será usado. Não

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:

Propriedade Descrição Obrigatório
type A propriedade type deve ser definida como AzureDataExplorer. Sim
endpoint URL de ponto de extremidade do cluster do Azure Data Explorer com o formato https://<clusterName>.<regionName>.kusto.windows.net. Sim
Banco de Dados Nome do banco de dados. Sim
credenciais Especifique a identidade gerenciada atribuída pelo usuário como o objeto da credencial. Sim
connectVia O runtime de integração a ser usado para se conectar ao armazenamento de dados. Você pode usar o Azure Integration Runtime ou um runtime de integração auto-hospedada se o seu armazenamento de dados estiver em uma rede privada. Se não especificado, o Azure Integration Runtime padrão será usado. Não

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:

Propriedade Descrição Obrigatório
type A propriedade type deve ser definida como AzureDataExplorerTable. Sim
table O nome da tabela à qual o serviço vinculado se refere. Não para coletor; não para fonte

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:

Propriedade Descrição Obrigatório
type A propriedade type da fonte da atividade Copy deve ser definida como: AzureDataExplorerSource Sim
Consulta Uma solicitação somente leitura fornecida em um formato KQL. Use a consulta KQL personalizada como referência. Sim
queryTimeout O tempo de espera antes que a solicitação de consulta atinja o tempo limite. O valor padrão é 10 min (00:10:00); o valor máximo permitido é 1 hora (01:00:00). Não
noTruncation Indica se o conjunto de resultados retornado deve ser truncado. Por padrão, o resultado é truncado após 500.000 registros ou 64 megabytes (MB). O truncamento é altamente recomendável para garantir o comportamento correto da atividade. Não

Observação

Por padrão, a fonte do Azure Data Explorer tem um limite de tamanho de 500.000 registros ou 64 MB. Para recuperar todos os registros sem truncamento, você pode especificar set notruncation; no início da consulta. Para saber mais, confira Limites de consulta.

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:

Propriedade Descrição Obrigatório
type A propriedade type do coletor da atividade Copy deve ser definida como: AzureDataExplorerSink. Sim
ingestionMappingName Nome de um mapeamento pré-criado em uma tabela do Kusto. Para mapear as colunas da origem para o Azure Data Explorer (o que se aplica a todos os formatos e armazenamentos de origem com suporte, incluindo os formatos CSV/JSON/Avro), você pode usar o mapeamento de coluna de atividade Copy (implicitamente por nome ou explicitamente como configurado) e/ou mapeamentos do Azure Data Explorer. Não
additionalProperties Um recipiente de propriedades que pode ser usado para especificar qualquer uma das propriedades de ingestão que não estão sendo definidas pelo coletor do Azure Data Explorer. Especificamente, pode ser útil para especificar marcas de ingestão. Saiba mais no documento de ingestão de dados do Azure Data Explorer. Não

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.

Nome Descrição Obrigatório Valores permitidos Propriedade do script do Fluxo de Dados
Tabela Se você selecionar Tabela como entrada, o fluxo de dados buscará todos os dados da tabela especificada no conjunto de dados do Azure Data Explorer ou nas opções de origem ao usar o conjunto de dados embutido. Não String (somente para o conjuntos de dados em linha)
tableName
Consulta Uma solicitação somente leitura fornecida em um formato KQL. Use a consulta KQL personalizada como referência. Não String Consulta
Tempo limite O tempo de espera antes da expiração da solicitação de consulta. O padrão é “172.000” (2 dias) Não Integer tempo limite

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.

Nome Descrição Obrigatório Valores permitidos Propriedade do script do Fluxo de Dados
Ação tabela determina se deve-se recriar ou remover todas as linhas da tabela de destino antes da gravação.
- None: nenhuma ação será feita na tabela.
- Recreate: a tabela será descartada e recriada. Necessário ao criar uma tabela dinamicamente.
- Truncate: todas as linhas da tabela de destino serão removidas.		 Não true ou false recreate
truncate
Pré-scripts e Pós-scripts SQL Especifique vários scripts de comandos de controle Kusto que serão executados antes (pré-processamento) e após (pós-processamento) que os dados sejam gravados no banco de dados do coletor. Não String preSQLs; postSQLs
Tempo limite O tempo de espera antes da expiração da solicitação de consulta. O padrão é “172.000” (2 dias) Não Integer tempo limite

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