Clique no banner para conhecer e adquirir o meu treinamento de Bancos de Dados no Azure

Azure Data Factory (ADF) – Como criar uma documentação offline (em CSV) do seu projeto

Post Views 2,027 views
Reading time 10 minutes

Hey Guys!
Nesse artigo, eu gostaria de compartilhar com vocês, um script Powershell para criar uma documentação do seu projeto offline (em CSV) no Azure Data Factory, uma necessidade muito comum que as pessoas têm, especialmente para listar e rastrear os datasets de origem de forma fácil, e também listar os Integration Runtimes (IR), Dataflows, Linked Services, Pipelines e Triggers.

Segue a lista dos objetos documentados por esse script:

  • Tabelas lidas e gravadas pelo ADF (Datasets)
  • Integration Runtime (IR) — listas, nós e métricas
  • Dataflows
  • Linked Services
  • Pipelines
  • Triggers

Exemplo de resultado da documentação:

A minha motivação para criar esse artigo, foi a necessidade de identificar as tabelas de origem do meu projeto do Data Factory que tinha mais de 300 datasets no total, sendo uns 70 deles eram as tabelas nos sistemas de origem, e o restante eram datasets de transformações.

Quando eu precisei fazer isso, eu encontrei o artigo Documenting Azure Data Factory, que tinha um script Powershell bem completo, mas a parte de datasets não retornava o que eu precisava, que eram mais detalhes referentes às tabelas, linkedservice utilizado, nome da tabela, nome do schema, etc.

Foi então que comecei a estudar a API do ADF e criei a minha própria versão desse script, implementando essas melhorias, além de um filtro a partir do nome do ADF, caso você queira atualizar a documentação de apenas uma instância, ao invés de todas.

Pré-requisito: Instalar o módulo Powershell do Azure (AZ)

Caso você não tenha instalado o módulo Powershell do Azure ainda (não vem instalado por padrão), você precisará instalar esse módulo para utilizar o script desse artigo, e vou te guiar no passo-a-passo logo abaixo.
Clique aqui para instalar o módulo Powershell do Azure (AZ)

Para instalar o módulo Powershell do Azure (AZ), abra o Prompt de Comando (cmd.exe):

Digite o comando powershell, para iniciar a interface do Powershell:

Digite o comando Install-Module -Name Az

Um aviso de repositório não confiável irá aparecer para você. Digite a letra “A” (Sim para todos) para seguir com a instalação.

Pronto! Módulo Powershell do Azure (AZ) instalado com sucesso.

Aviso: Caso o seu PowerShell acuse erro ao tentar executar o comando Install-Module, é porque sua máquina ainda está utilizando o PowerShell 4.0 ou anterior. Se esse é o seu caso, você precisará instalar o Windows Management Framework 5.1, conforme a documentação oficial nos orienta, para adicionar esse módulo ao seu PowerShell ou atualize a versão do seu Powershell para uma versão mais nova.

Caso você já tenha instalado o módulo, pode desconsiderar esse tópico e seguir direto para a utilização do script.

Testando a conexão com o Powershell do Azure

Caso você queira testar se a conexão está funcionando normalmente, utilize o guia abaixo.

Se você acha que está funcionando, pode ignorar essa etapa. Caso você tente executar o script da documentação e encontre mensagens de erro, tente realizar os testes abaixo.
Clique aqui para visualizar o conteúdo

Para testar a conexão com o Powershell do Azure, abra o Prompt de Comando (cmd.exe):

Digite o comando powershell, para iniciar a interface do Powershell:

Vamos precisar agora de digitar o comando Connect-AzAccount para conectar ao Azure pelo Powershell, mas antes, iremos precisar importar o módulo. Para fazer isso, digite o comando Set-ExecutionPolicy Unrestricted para permitir a execução do script, e então, digite o comando Import-Module Az.Accounts:

Digite agora o comando Connect-AzAccount, para se conectar ao Azure pelo Powershell:

Digite suas credenciais e você estará autenticado ao Azure.

Como eu tenho mais de um TentandId na minha conta do Azure, recebi alguns avisos informando isso. A conta seleciona é a primeira retornada, mas para não correr risco de executar o script na subscription errada, vamos definir a subscription que eu quero manualmente utilizando o comando Set-AzConnect -TenantId “xxxx-xxxx-xxxx-xxxx”

Para saber qual o ID do Tentant que você quer utilizar, entre no portal do Azure e abra as propriedades de um dos Azure Data Factories (ADF) que você quer utilizar, e copie a propriedade “Managed Identity Tenant”.

O tenant que eu selecionei também possui mais de uma subscription. Para definir manualmente qual que eu quero utilizar, vou usar o comando Set-AzContext -Subscription “xxxx-xxxx-xxxx-xxxx”

Para descobrir o ID da Subscription, volte ao portal do Azure e abra as propriedades de um dos Azure Data Factories (ADF) que você quer utilizar, e copie a propriedade “Subscription”. Esse ID também está presente na própria URL e também compõe o endereço do Resource ID.

Como utilizar o script Powershell

Para utilizar o script powershell ExportAzureDataFactoryDocumentation.ps1 e começar a documentar suas instâncias do Azure Data Factory (ADF), abra o Prompt de Comando (cmd.exe):

Digite o comando powershell, para iniciar a interface do Powershell:

Navegue até o diretório local onde você baixou o script ExportAzureDataFactoryDocumentation.ps1 utilizando o comando cd “diretorio_local” e digite execute o script abaixo:

Para saber qual o ID do Tentant que você quer utilizar, entre no portal do Azure e abra as propriedades de um dos Azure Data Factories (ADF) que você quer utilizar, e copie a propriedade “Managed Identity Tenant”.

Para descobrir o ID da Subscription, copie a propriedade “Subscription”. Esse ID também está presente na própria URL e também compõe o endereço do Resource ID.

Você também pode utilizar o caminho completo do arquivo sem precisar navegar até o diretório e também filtrar o nome do Data Factory para exportar a documentação só de uma instância ao invés de exportar de todas as instâncias da subscription.

Resultado da execução:

Arquivos gerados com sucesso!

Conteúdo dos arquivos gerados

Vou já mostrar aqui, o que você pode esperar das documentações geradas e quais informações são retornadas.

Lista dos Data Factories

Lista dos Dataflows

Lista dos Datasets

Lista dos Pipelines

Lista dos Integration Runtime (IR)

Lista dos Linked Services

Código-fonte do script ExportAzureDataFactoryDocumentation.ps1

O código desse script está disponível nesse repositório github aqui, onde vocês podem ter acesso sempre à versão mais atualizada do código e também submeter melhorias e novos recursos, mas também vou deixar o código logo aqui abaixo:

Observação: Não ficarei atualizando o código que está aqui no post, então dê preferência ao código que está no Repositório do GitHub.

And that's it, folks!
Espero que tenham gostado desse artigo e até a próxima!