Como usar a atividade Get Metadata no Azure Data Factory

A atividade Get Metadata no Azure Data Factory serve para perguntar ao armazenamento "este ficheiro existe? que tamanho tem? que ficheiros estão nesta pasta?" antes de copiar seja o que for. Saber usar a atividade Get Metadata no Azure Data Factory evita pipelines que falham a meio porque a origem ainda não chegou, e abre a porta a pipelines dinâmicos que reagem ao que encontram.

Pré-requisitos

• Uma subscrição Azure com uma instância de Azure Data Factory já criada.
• Uma conta de Azure Data Lake Storage Gen2 (ou Blob Storage) com uma pasta de exemplo, por exemplo raw/vendas/.
• Um linked service para esse armazenamento, com permissões de leitura.
• Noções básicas do ADF Studio: pipelines, datasets e atividades.

Passo 1: Criar o dataset da pasta de origem

No ADF Studio, vá a Author > Datasets > New dataset e escolha Azure Data Lake Storage Gen2 com o formato DelimitedText. No separador Connection, indique o container e o caminho da pasta, mas deixe o nome do ficheiro vazio quando quiser inspecionar a pasta inteira.

Dica: crie dois datasets — um a apontar para a pasta (ds_pasta_vendas) e outro para um ficheiro concreto (ds_ficheiro_vendas). A atividade Get Metadata devolve campos diferentes consoante o alvo seja uma pasta ou um ficheiro.

Passo 2: Adicionar a atividade Get Metadata ao pipeline

Crie um pipeline novo (pl_metadata_demo), arraste a atividade Get Metadata a partir do grupo General e dê-lhe o nome GetMetadataPasta. No separador Dataset, selecione ds_pasta_vendas.

Passo 3: Escolher os campos na Field list

Ainda no separador Dataset, clique em New dentro da Field list e acrescente os campos que quer ler. Os mais úteis são:

• exists — devolve true ou false; funciona para ficheiros e para pastas.
• childItems — lista o conteúdo de uma pasta (apenas para pastas).
• itemName e itemType — nome e tipo (File ou Folder).
• size e lastModified — tamanho em bytes e data da última alteração (apenas para ficheiros).

Em JSON, a atividade fica assim:

{
  "name": "GetMetadataPasta",
  "type": "GetMetadata",
  "typeProperties": {
    "dataset": { "referenceName": "ds_pasta_vendas", "type": "DatasetReference" },
    "fieldList": [ "exists", "childItems" ],
    "storeSettings": { "type": "AzureBlobFSReadSettings" },
    "formatSettings": { "type": "DelimitedTextReadSettings" }
  }
}

Passo 4: Validar se a origem existe com If Condition

Adicione a seguir uma atividade If Condition e ligue-a ao Get Metadata pela seta verde (Success). Na expressão, leia o output da atividade anterior:

@activity('GetMetadataPasta').output.exists

No ramo True coloque a atividade Copy Data que carrega os dados. No ramo False coloque uma atividade Fail com uma mensagem clara, do género "A pasta raw/vendas ainda não recebeu ficheiros". O pipeline deixa de rebentar com um erro críptico e passa a falhar de forma controlada.

Passo 5: Percorrer os ficheiros da pasta com ForEach

O campo childItems devolve um array de objetos com name e type. Passe esse array a uma atividade ForEach:

Items:  @activity('GetMetadataPasta').output.childItems

Dentro do ForEach, no dataset de origem da Copy Data:
  parâmetro nomeFicheiro = @item().name

Assim o pipeline copia todos os ficheiros que encontrar, sem ter os nomes escritos à mão. Para processar apenas CSV, coloque antes uma atividade Filter com a condição @endswith(item().name, '.csv').

Erro comum: a atividade falha em vez de devolver false

Se o Get Metadata rebentar com "The required Blob is missing" em vez de devolver exists: false, quase de certeza que se esqueceu de incluir exists na Field list. Com esse campo presente, a atividade responde false em vez de lançar erro — é exatamente isso que permite validar a origem sem partir o pipeline.

Verificar o resultado

Clique em Debug e, no painel Output, carregue no ícone de óculos da atividade GetMetadataPasta. Deve ver um JSON semelhante a este:

{
  "exists": true,
  "childItems": [
    { "name": "vendas_2026_07.csv", "type": "File" },
    { "name": "vendas_2026_06.csv", "type": "File" }
  ]
}

Se childItems vier vazio, confirme o caminho da pasta e as permissões do linked service — a identidade gerida do Data Factory precisa da função Storage Blob Data Reader na conta de armazenamento.

Conclusão

Get Metadata + If Condition + ForEach é a base de quase todos os pipelines dinâmicos do Azure Data Factory: verificar, decidir e iterar. O passo natural seguinte é cruzar o campo lastModified com uma variável de watermark para copiar apenas os ficheiros novos desde a última execução. Que verificação gostaria de ter no seu pipeline antes de a cópia arrancar?