Utilize atividades personalizadas num Azure Data Factory ou Azure Synapse pipeline Analytics

APLICA-SE A: Azure Data Factory Azure Synapse Analytics

Existem dois tipos de atividades que pode utilizar num Azure Data Factory ou no oleoduto Synapse.

Para mover dados de/para uma loja de dados que o serviço não suporta, ou para transformar/processar dados de uma forma que não seja suportada pelo serviço, pode criar uma atividade Personalizada com a sua própria lógica de movimento de dados ou transformação e utilizar a atividade num pipeline. A atividade personalizada executa a sua lógica de código personalizada numa Azure Batch piscina de máquinas virtuais.

Nota

Para interagir com o Azure, recomenda-se o módulo Azure Az PowerShell. Consulte a instalação Azure PowerShell para começar. Para saber como migrar para o módulo do Az PowerShell, veja Migrar o Azure PowerShell do AzureRM para o Az.

Consulte os seguintes artigos se é novo no serviço Azure Batch:

Importante

Ao criar um novo pool de Azure Batch, deve ser utilizado o 'VirtualMachineConfiguration' e NÃO 'CloudServiceConfiguration'. Para mais detalhes, consulte Azure Batch orientação de migração da Pool.

Adicione atividades personalizadas a um oleoduto com UI

Para utilizar uma atividade personalizada num oleoduto, complete os seguintes passos:

  1. Procure por Custom no painel de atividades do oleoduto e arraste uma atividade personalizada para a tela do gasoduto.

  2. Selecione a nova atividade Personalizada na tela se ainda não estiver selecionada.

  3. Selecione o separador Azure Batch para selecionar ou criar um novo serviço Azure Batch ligado que executará a atividade personalizada.

    Mostra a UI para uma atividade personalizada.

  4. Selecione o separador Definições e especifique um comando a executar no Azure Batch e detalhes avançados opcionais.

    Mostra o uI para o separador Definições para uma atividade personalizada.

serviço Azure Batch ligado

O seguinte JSON define uma amostra Azure Batch serviço ligado. Para mais detalhes, consulte ambientes de computação suportados

{
    "name": "AzureBatchLinkedService",
    "properties": {
        "type": "AzureBatch",
        "typeProperties": {
            "accountName": "batchaccount",
            "accessKey": {
                "type": "SecureString",
                "value": "access key"
            },
            "batchUri": "https://batchaccount.region.batch.azure.com",
            "poolName": "poolname",
            "linkedServiceName": {
                "referenceName": "StorageLinkedService",
                "type": "LinkedServiceReference"
            }
        }
    }
}

Para saber mais sobre Azure Batch serviço ligado, consulte o artigo de serviços ligados a Compute.

Atividade personalizada

O seguinte snippet JSON define um oleoduto com uma simples Atividade Personalizada. A definição de atividade tem uma referência ao serviço Azure Batch ligado.

{
  "name": "MyCustomActivityPipeline",
  "properties": {
    "description": "Custom activity sample",
    "activities": [{
      "type": "Custom",
      "name": "MyCustomActivity",
      "linkedServiceName": {
        "referenceName": "AzureBatchLinkedService",
        "type": "LinkedServiceReference"
      },
      "typeProperties": {
        "command": "helloworld.exe",
        "folderPath": "customactv2/helloworld",
        "resourceLinkedService": {
          "referenceName": "StorageLinkedService",
          "type": "LinkedServiceReference"
        }
      }
    }]
  }
}

Nesta amostra, o helloworld.exe é uma aplicação personalizada armazenada na pasta customactv2/helloworld da conta Azure Storage utilizada no resourceLinkedService. A atividade Custom submete esta aplicação personalizada a ser executada no Azure Batch. Pode substituir o comando a qualquer aplicação preferida que possa ser executada no Sistema de Operação alvo dos nós Azure Batch Pool.

A tabela seguinte descreve nomes e descrições de propriedades específicas a esta atividade.

Propriedade Descrição Necessário
name Nome da atividade no oleoduto Yes
descrição Texto descrevendo o que a atividade faz. No
tipo Para atividades personalizadas, o tipo de atividade é personalizado. Yes
linkedServiceName Serviço ligado a Azure Batch. Para saber mais sobre este serviço ligado, consulte o artigo de serviços ligados a Compute . Yes
command Comando da aplicação personalizada a executar. Se a aplicação já estiver disponível no Azure Batch Pool Node, o resourceLinkedService e a pastaPath podem ser ignorados. Por exemplo, pode especificar o comando a ser cmd /c dir, que é suportado de forma nativa pelo nó do Pool do Lote do Windows. Yes
recursoLinkedService Serviço ligado ao armazenamento Azure à conta de Armazenamento onde a aplicação personalizada é armazenada Não*
folderPath Caminho para a pasta da aplicação personalizada e todas as suas dependências

Se tiver dependências armazenadas em subpastas - isto é, numa estrutura hierárquica de pastas em modo de pasta - a estrutura da pasta é atualmente achatada quando os ficheiros são copiados para Azure Batch. Ou seja, todos os ficheiros são copiados numa única pasta sem sub-dobras. Para contornar este comportamento, considere comprimir os ficheiros, copiar o ficheiro comprimido e, em seguida, desapertá-lo com código personalizado no local pretendido.
Não*
referênciaObjects Uma série de serviços e conjuntos de dados existentes. Os serviços e conjuntos de dados ligados referenciados são passados para a aplicação personalizada no formato JSON para que o seu código personalizado possa referenciar recursos do serviço No
prorrogações Propriedades definidas pelo utilizador que podem ser passadas para a aplicação personalizada em formato JSON para que o seu código personalizado possa referenciar propriedades adicionais No
retençãoTimeInDays O tempo de retenção para os ficheiros submetidos para atividade personalizada. O valor predefinido é de 30 dias. No

* As propriedades resourceLinkedService e folderPath devem ser especificadas ou ambas omitidas.

Nota

Se estiver a passar serviços ligados como referênciaObjects em Atividade Personalizada, é uma boa prática de segurança passar um Azure Key Vault serviço ligado ativado (uma vez que não contém quaisquer cordas seguras) e buscar as credenciais usando o nome secreto diretamente do Key Vault do código. Pode encontrar aqui um exemplo que faz referências ao serviço ligado a AKV, recupera as credenciais a partir de Key Vault e, em seguida, acede ao armazenamento no código.

Nota

Atualmente apenas o armazenamento Azure Blob é suportado para recursosLinkedService em atividade personalizada, e é o único serviço ligado que é criado por padrão e nenhuma opção para escolher outros conectores como ADLS Gen2.

Permissões de atividade personalizadas

A atividade personalizada define a conta Azure Batch utilizador automático para acesso não administrativo com âmbito de tarefa (a especificação de utilizador automático predefinido). Não é possível alterar o nível de permissão da conta de utilizador automático. Para obter mais informações, consulte executar tarefas em contas de utilizador em Batch | Contas de utilizador automático.

Executando comandos

Pode executar diretamente um comando utilizando a Atividade Personalizada. O exemplo a seguir corre o comando "echo hello world" no Azure Batch de grupos e imprime a saída para o stdout.

{
  "name": "MyCustomActivity",
  "properties": {
    "description": "Custom activity sample",
    "activities": [{
      "type": "Custom",
      "name": "MyCustomActivity",
      "linkedServiceName": {
        "referenceName": "AzureBatchLinkedService",
        "type": "LinkedServiceReference"
      },
      "typeProperties": {
        "command": "cmd /c echo hello world"
      }
    }]
  }
}

Objetos e propriedades de passagem

Esta amostra mostra como pode utilizar os Pedidos de Referência e Properties estendidos para passar objetos e propriedades definidas pelo utilizador do serviço para a sua aplicação personalizada.

{
  "name": "MyCustomActivityPipeline",
  "properties": {
    "description": "Custom activity sample",
    "activities": [{
      "type": "Custom",
      "name": "MyCustomActivity",
      "linkedServiceName": {
        "referenceName": "AzureBatchLinkedService",
        "type": "LinkedServiceReference"
      },
      "typeProperties": {
        "command": "SampleApp.exe",
        "folderPath": "customactv2/SampleApp",
        "resourceLinkedService": {
          "referenceName": "StorageLinkedService",
          "type": "LinkedServiceReference"
        },
        "referenceObjects": {
          "linkedServices": [{
            "referenceName": "AzureBatchLinkedService",
            "type": "LinkedServiceReference"
          }]
        },
        "extendedProperties": {          
          "connectionString": {
            "type": "SecureString",
            "value": "aSampleSecureString"
          },
          "PropertyBagPropertyName1": "PropertyBagValue1",
          "propertyBagPropertyName2": "PropertyBagValue2",
          "dateTime1": "2015-04-12T12:13:14Z"
        }
      }
    }]
  }
}

Quando a atividade é executada, os Pedidos de Referência e as Extensões estendidas são armazenados nos seguintes ficheiros que são implantados na mesma pasta de execução do SampleApp.exe:

  • activity.json

    As lojas ampliaram as propriedades e propriedades da atividade personalizada.

  • linkedServices.json

    Armazena uma série de Serviços Linked definidos na propriedade ReferenceObjects.

  • datasets.json

    Armazena uma série de conjuntos de dados definidos na propriedade ReferenceObjects.

Os códigos de amostra que seguem demonstram como o SampleApp.exe pode aceder às informações necessárias a partir dos ficheiros JSON:

using Newtonsoft.Json;
using System;
using System.IO;

namespace SampleApp
{
    class Program
    {
        static void Main(string[] args)
        {
            //From Extend Properties
            dynamic activity = JsonConvert.DeserializeObject(File.ReadAllText("activity.json"));
            Console.WriteLine(activity.typeProperties.extendedProperties.connectionString.value);

            // From LinkedServices
            dynamic linkedServices = JsonConvert.DeserializeObject(File.ReadAllText("linkedServices.json"));
            Console.WriteLine(linkedServices[0].properties.typeProperties.accountName);
        }
    }
}

Recuperar saídas de execução

Pode iniciar uma corrida de gasoduto utilizando o seguinte comando PowerShell:

$runId = Invoke-AzDataFactoryV2Pipeline -DataFactoryName $dataFactoryName -ResourceGroupName $resourceGroupName -PipelineName $pipelineName

Quando o gasoduto estiver em funcionamento, pode verificar a saída de execução utilizando os seguintes comandos:

while ($True) {
    $result = Get-AzDataFactoryV2ActivityRun -DataFactoryName $dataFactoryName -ResourceGroupName $resourceGroupName -PipelineRunId $runId -RunStartedAfter (Get-Date).AddMinutes(-30) -RunStartedBefore (Get-Date).AddMinutes(30)

    if(!$result) {
        Write-Host "Waiting for pipeline to start..." -foregroundcolor "Yellow"
    }
    elseif (($result | Where-Object { $_.Status -eq "InProgress" } | Measure-Object).count -ne 0) {
        Write-Host "Pipeline run status: In Progress" -foregroundcolor "Yellow"
    }
    else {
        Write-Host "Pipeline '"$pipelineName"' run finished. Result:" -foregroundcolor "Yellow"
        $result
        break
    }
    ($result | Format-List | Out-String)
    Start-Sleep -Seconds 15
}

Write-Host "Activity `Output` section:" -foregroundcolor "Yellow"
$result.Output -join "`r`n"

Write-Host "Activity `Error` section:" -foregroundcolor "Yellow"
$result.Error -join "`r`n"

A sesta e o stderr da sua aplicação personalizada são guardados no contentor adfjobs no Serviço Ligado ao Armazenamento Azure que definiu ao criar Azure Batch Serviço Linked com um GUID da tarefa. Pode obter o caminho detalhado da saída Activity Run, como mostrado no seguinte corte:

Pipeline ' MyCustomActivity' run finished. Result:

ResourceGroupName : resourcegroupname
DataFactoryName   : datafactoryname
ActivityName      : MyCustomActivity
PipelineRunId     : xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
PipelineName      : MyCustomActivity
Input             : {command}
Output            : {exitcode, outputs, effectiveIntegrationRuntime}
LinkedServiceName :
ActivityRunStart  : 10/5/2017 3:33:06 PM
ActivityRunEnd    : 10/5/2017 3:33:28 PM
DurationInMs      : 21203
Status            : Succeeded
Error             : {errorCode, message, failureType, target}

Activity Output section:
"exitcode": 0
"outputs": [
  "https://<container>.blob.core.windows.net/adfjobs/<GUID>/output/stdout.txt",
  "https://<container>.blob.core.windows.net/adfjobs/<GUID>/output/stderr.txt"
]
"effectiveIntegrationRuntime": "DefaultIntegrationRuntime (East US)"
Activity Error section:
"errorCode": ""
"message": ""
"failureType": ""
"target": "MyCustomActivity"

Se quiser consumir o conteúdo de stdout.txt em atividades a jusante, pode obter o caminho para o ficheiro stdout.txt com a expressão "@activity ('MyCustomActivity').outputs[0]".

Importante

  • A atividade.json, linkedServices.json e datasets.json são armazenados na pasta de tempo de execução da tarefa Batch. Para este exemplo, a atividade.json, linkedServices.json e datasets.json são armazenados no https://adfv2storage.blob.core.windows.net/adfjobs/<GUID>/runtime/ caminho. Se necessário, tem de limpá-las separadamente.
  • Para os Serviços Ligados que utilizam o Self-Hosted Integration Runtime, as informações sensíveis como chaves ou palavras-passe são encriptadas pela Self-Hosted Integration Runtime para garantir estadias credenciais no ambiente de rede privada definida pelo cliente. Alguns campos sensíveis podem estar em falta quando referenciados pelo seu código de aplicação personalizado desta forma. Utilize SecureString em properties estendidas em vez de utilizar a referência do Serviço Linked, se necessário.

Passar saídas para outra atividade

Pode enviar valores personalizados do seu código numa Atividade Personalizada de volta ao serviço. Pode fazê-lo escrevendo-os a outputs.json partir da sua candidatura. O serviço copia o conteúdo outputs.json e anexa-o à Produção de Atividade como o valor do customOutput imóvel. (O limite de tamanho é de 2MB.) Se quiser consumir o conteúdo de outputs.json atividades a jusante, pode obter o valor utilizando a expressão @activity('<MyCustomActivity>').output.customOutput.

Recuperar saídas SecureString

Os valores de propriedade sensíveis designados como tipo SecureString, como mostrado em alguns dos exemplos deste artigo, estão mascarados no separador Monitor na interface do utilizador. No entanto, na execução do gasoduto, uma propriedade SecureString é serializada como JSON dentro do activity.json ficheiro como texto simples. Por exemplo:

"extendedProperties": {
  "connectionString": {
    "type": "SecureString",
    "value": "aSampleSecureString"
  }
}

Esta serialização não é verdadeiramente segura, e não se destina a ser segura. A intenção é uma sugestão para o serviço para mascarar o valor no separador Monitor.

Para aceder a propriedades do tipo SecureString a partir de uma atividade personalizada, leia o activity.json ficheiro, que é colocado na mesma pasta que o seu .EXE, deserialize o JSON e, em seguida, aceda à propriedade JSON (properties estendidas => [nome de propriedade] => valor).

Compare a atividade personalizada v2 e a versão 1 (personalizada) Atividade do DotNet

Na versão 1 Azure Data Factory, implementa-se uma Atividade DotNet (Personalizada) criando um projeto da Biblioteca classe .NET com uma classe que implementa o Execute método da IDotNetActivity interface. Os Serviços Ligados, Conjuntos de Dados e Propriedades Estendidas na carga útil JSON de uma Atividade DotNet (Personalizada) são passados para o método de execução como objetos fortemente digitados. Para mais detalhes sobre o comportamento da versão 1, consulte (Personalizado) DotNet na versão 1. Devido a esta implementação, o código de atividade da sua versão 1 DotNet tem de ser alvo .NET Framework 4.5.2. A versão 1 DotNet Activity também tem de ser executada nos nós Azure Batch Pool baseados no Windows.

Nos gasodutos Azure Data Factory V2 e Synapse, não é obrigado a implementar uma interface .NET. Agora pode executar diretamente comandos, scripts e o seu próprio código personalizado, compilado como um executável. Para configurar esta implementação, você especifica o Command imóvel juntamente com o folderPath imóvel. A Atividade Personalizada envia o executável e as suas dependências para folderpath e executa o comando para si.

Os Serviços Ligados, Conjuntos de Dados (definidos em referênciaObjects) e Propriedades Estendidas definidas na carga útil JSON de uma Fábrica de Dados v2 ou Pipeline Synapse A Atividade Personalizada pode ser acedida pelos seus ficheiros JSON. Pode aceder às propriedades necessárias utilizando um serializador JSON, como mostrado na amostra de código SampleApp.exe anterior.

Com as alterações introduzidas na Data Factory V2 e na Synapse pipeline Custom Activity, pode escrever a sua lógica de código personalizado no seu idioma preferido e executá-la em Sistemas de Operação Windows e Linux suportados por Azure Batch.

O quadro que se segue descreve as diferenças entre a Atividade Personalizada da Fábrica de Dados V2 e o gasoduto Synapse e a versão 1 (Custom) DotNet Da dotNet:

Diferenças Atividade Personalizada versão 1 (Personalizada) Atividade do DotNet
Como a lógica personalizada é definida Ao fornecer um executável Implementando um .NET DLL
Ambiente de execução da lógica personalizada Janelas ou Linux Janelas (.NET Framework 4.5.2)
Executando scripts Suporta a execução direta de scripts (por exemplo "cmd/c echo hello world" no Windows VM) Requer implementação no .NET DLL
Conjunto de dados necessário Opcional Obrigado a acorrentar atividades e passar informações
Passar informações da atividade para a lógica personalizada Através de ReferenceObjects (LinkedServices and Datasets) e ExtendedProperties (propriedades personalizadas) Através de Extensões (propriedades personalizadas), Conjuntos de dados de entrada e saída
Recuperar informação em lógica personalizada Parses activity.json, linkedServices.json e datasets.json armazenados na mesma pasta do executável Através de .NET SDK (.NET Frame 4.5.2)
Registo Escreve diretamente para STDOUT Implementação do Madeiriro em .NET DLL

Se tiver o código .NET existente escrito para uma atividade dotnet versão 1 (Personalizada), tem de modificar o seu código para que funcione com a versão atual da Atividade Personalizada. Atualize o seu código seguindo estas diretrizes de alto nível:

  • Mude o projeto de uma Biblioteca classe .NET para uma App de Consola.
  • Inicie a sua aplicação com o Main método. O Execute método da IDotNetActivity interface já não é necessário.
  • Leia e analise os Serviços Ligados, Conjuntos de Dados e Atividade com um serializador JSON, e não tão fortemente digitado. Passe os valores das propriedades requeridas para a sua lógica de código personalizado principal. Consulte o código SampleApp.exe anterior como exemplo.
  • O objeto Madeireiro já não está suportado. A saída do seu executável pode ser impressa para a consola e é guardada para stdout.txt.
  • O pacote Microsoft.Azure.Management.DataFactories NuGet já não é necessário.
  • Compilar o seu código, fazer o upload do executável e das suas dependências para o Azure Storage e definir o caminho na folderPath propriedade.

Para uma amostra completa de como a amostra de DLL e pipeline de ponta a ponta descrita na versão 1 da Data Factory Utilize atividades personalizadas num gasoduto Azure Data Factory pode ser reescrito como uma Atividade Personalizada para os gasodutos Data Factory v2 e Synapse, consulte a amostra de Atividade Personalizada.

Auto-dimensionamento de Azure Batch

Também pode criar uma piscina Azure Batch com funcionalidade de autoescala. Por exemplo, pode criar um lote Azure com 0 VMs dedicados e uma fórmula de autoescala com base no número de tarefas pendentes.

A fórmula da amostra aqui consegue o seguinte comportamento: Quando a piscina é criada inicialmente, começa com 1 VM. $PendingTasks métrica define o número de tarefas em execução + estado ativo (em fila). A fórmula encontra o número médio de tarefas pendentes nos últimos 180 segundos e define o TargetDedicated em conformidade. Garante que o TargetDedicated nunca vai além dos 25 VMs. Assim, à medida que novas tarefas são submetidas, o pool cresce automaticamente e à medida que as tarefas terminam, os VM tornam-se gratuitos um a um e os autoscaling encolhem esses VMs. startingNumberOfVMs e maxNumberofVMs podem ser ajustados às suas necessidades.

Fórmula de autoescala:

startingNumberOfVMs = 1;
maxNumberofVMs = 25;
pendingTaskSamplePercent = $PendingTasks.GetSamplePercent(180 * TimeInterval_Second);
pendingTaskSamples = pendingTaskSamplePercent < 70 ? startingNumberOfVMs : avg($PendingTasks.GetSample(180 * TimeInterval_Second));
$TargetDedicated=min(maxNumberofVMs,pendingTaskSamples);

Consulte os nós computacional de escala automática numa piscina Azure Batch para obter mais detalhes.

Se a piscina estiver a utilizar o autoScaleEvaluationInterval predefinido, o serviço Batch pode demorar 15-30 minutos a preparar o VM antes de executar a atividade personalizada. Se a piscina estiver a utilizar um autoScaleEvaluationInterval diferente, o serviço Batch pode demorar automaticamente a Reavaliação de Escala + 10 minutos.

Passos seguintes

Veja os seguintes artigos que explicam como transformar dados de outras formas: