Power Automate formatDateTime: sintaxe, cadeias de formato e exemplos

By Mirko Peters · 2026-11-12

Power Automate formatDateTime explicado: sintaxe, as cadeias de formato que realmente importam, fusos horários com convertTimeZone e os erros por trás de datas e horas incorretas.

Automatically translated with AI from the original post. Read the English original

O formatDateTime do Power Automate transforma uma data e uma hora no texto que você quer. A sintaxe é formatDateTime(timestamp, format, locale), em que o formato e o locale são opcionais e o resultado é uma string. Por exemplo, formatDateTime(utcNow(), 'dd-MM-yyyy') retorna a data UTC atual como dia, mês e ano. Este artigo é para quem cria fluxos e acaba sempre com datas como 2023-10-22T00:00:00Z em e-mails, nomes de arquivos ou colunas do SharePoint. Ele cobre a sintaxe, as cadeias de formato que você mais vai usar, a armadilha do fuso horário, uma tabela com padrões comuns e os erros por trás de resultados incorretos.

Pontos-chave

• A sintaxe é formatDateTime(timestamp, format, locale), em que o formato e o locale são opcionais e o resultado é sempre uma string.
• Sem um formato, a função retorna o padrão de ida e volta ISO 8601, por exemplo 2018-03-15T00:00:00.0000000.
• Maiúsculas e minúsculas importam nas cadeias de formato: MM é o mês e mm são os minutos; HH é a hora de 24 horas, enquanto hh é a hora de 12 horas.
• O Power Automate trabalha em UTC por padrão; por isso, converta o fuso horário primeiro com convertTimeZone ou convertFromUtc e só depois formate o resultado.
• Coloque valores digitados e cadeias de formato entre aspas simples, mas nunca coloque conteúdo dinâmico entre aspas simples.

Como o formatDateTime funciona

A função recebe um timestamp e o reescreve. O artigo da Microsoft sobre como formatar valores de data e hora em um fluxo descreve o primeiro argumento como a data e a hora que você quer formatar. Ele pode ser digitado manualmente ou vir do conteúdo dinâmico. Valores digitados devem estar no formato ISO 8601, como 2009-06-15T13:45:30. O segundo argumento é a cadeia de formato. Um único caractere é uma cadeia de formato padrão. Mais de um caractere é uma cadeia de formato personalizada, que controla a posição e a precisão do mês, do dia, do ano, da hora, dos segundos e assim por diante.

Três detalhes da referência de expressões de fluxo de trabalho da Microsoft merecem ser lembrados:

• O formato é opcional. Se você omiti-lo, o padrão é o, que a Microsoft descreve como ISO 8601 com as informações de fuso horário preservadas. formatDateTime('03/15/2018') retorna '2018-03-15T00:00:00.0000000'.
• Um formato inválido gera um erro. A execução do fluxo falha, então um erro de digitação no padrão aparece no seu histórico de execuções.
• O locale é opcional. Se você omiti-lo, será en-us. Um locale inválido também gera erro. É assim que você obtém nomes de meses e dias em outro idioma: formatDateTime('01/31/2016', 'dddd MMMM d', 'fr-fr') retorna 'dimanche janvier 31', enquanto a mesma chamada sem o locale retorna 'Sunday January 31'.

O valor de retorno é uma string, e isso importa na prática. Depois que você formata uma data, o resultado é texto, e você não deve usá-lo em cálculos de data. Faça o cálculo primeiro com funções como addDays ou addToTime e formate por último. No Power Automate, o valor formatado normalmente vai para o corpo de um email, para um nome de arquivo ou para uma coluna de texto.

Como usar formatDateTime no Power Automate, passo a passo

O artigo da Microsoft mostra uma forma clara de inserir a expressão em um fluxo.

1. Selecione o campo de entrada da ação onde o valor formatado deve ficar, por exemplo o Corpo de uma ação Enviar um email (V2).
2. Selecione Adicionar conteúdo dinâmico e abra a guia Expressão. No designer de fluxos, isso aparece como o botão fx.
3. Digite formatDateTime( ou encontre a função na lista de funções de Data e hora.
4. Adicione o valor. Digite um valor fixo entre aspas simples ou escolha conteúdo dinâmico. Não coloque aspas simples em volta de conteúdo dinâmico.
5. Adicione a string de formato entre aspas simples, por exemplo 'MM/dd/yyyy'.
6. Selecione OK para inserir a expressão.

O padrão da página da Microsoft fica assim: formatDateTime('2023-10-22', 'dd/MM/yyyy hh:mm tt') para um valor fixo entre aspas, e a mesma chamada com um item de conteúdo dinâmico no lugar do valor entre aspas, sem aspas.

O exemplo prático do artigo usa um fluxo acionado manualmente com uma entrada Data. A expressão é formatDateTime(triggerBody()?['date'], 'MM/dd/yyyy'). Com a data 2023-10-22, o email mostra a data no formato MM/dd/yyyy.

Para testar uma expressão antes de construir em cima dela, use uma ação Compor com um timestamp fixo entre aspas simples, execute o fluxo e leia a saída no histórico de execuções. Leva um minuto e evita corrigir um formato quebrado em um fluxo que já envia emails reais.

Strings de formato que você realmente vai usar

As strings padrão são uma única letra. Os exemplos da Microsoft para o timestamp 2009-06-15T13:45:30:

• 'g' retorna 6/15/2009 1:45 PM, o padrão geral de data e hora com hora curta.
• 'D' retorna Monday, June 15, 2009, o padrão de data longa.

A documentação do .NET lista mais letras padrão. Exemplos com o mesmo timestamp: 'd' gera 6/15/2009, 't' gera 1:45 PM, 'T' gera 1:45:30 PM, 's' gera o formato ordenável 2009-06-15T13:45:30, e 'Y' gera June 2009. A maioria segue as regras de cultura, então a mesma letra pode aparecer diferente com outro locale. As que sempre têm a mesma aparência em qualquer lugar são o, r, s e u.

As strings personalizadas dão controle. Estes são os especificadores que importam para fluxos:

• yyyy é o ano com quatro dígitos, e yy o ano com dois dígitos.
• MM é o mês com zero à esquerda, MMM o nome abreviado do mês e MMMM o nome completo do mês. M é o mês sem zero à esquerda.
• dd é o dia com zero à esquerda, ddd o nome abreviado do dia e dddd o nome completo do dia.
• HH é a hora no formato de 24 horas, com zero à esquerda. hh é a hora no formato de 12 horas, com zero à esquerda.
• mm é o minuto, ss o segundo e fff os milissegundos.
• tt é AM ou PM.

Seguindo essa tabela, formatDateTime('2009-06-15T13:45:30', 'yyyy-MM-dd') gera 2009-06-15, e 'hh:mm tt' gera 01:45 PM. O artigo da Microsoft sobre fluxos também mostra formatDateTime(utcNow(), 'MMMM dd, yyyy, HH:mm'), que retorna a data e a hora UTC atuais no padrão June 15, 2009, 16:50, usando uma data de exemplo fixa.

Duas peculiaridades vêm das regras do .NET. Primeiro, uma única letra sempre é interpretada como especificador de formato padrão. Se você quiser usar um especificador personalizado de um único caractere, coloque um sinal de porcentagem na frente dele, por exemplo '%d'. Segundo, para inserir um texto fixo em um padrão, escape o caractere com uma barra invertida ou coloque o texto entre aspas. Outros caracteres que não são especificadores são copiados para a saída exatamente como estão. A barra e os dois-pontos são substituídos pelos separadores da configuração regional, o que pode surpreender você ao passar outra configuração regional.

Fusos horários: formate depois de converter

O Power Automate usa UTC por padrão, e utcNow() retorna a data e a hora atuais em UTC. Se seus usuários estiverem em Berlim ou em Nova York, o horário no seu e-mail ficará errado, a menos que você faça a conversão antes.

O artigo da Microsoft combina as duas funções: formatDateTime(convertTimeZone(utcNow(), 'UTC', 'Eastern Standard Time'), 'yyyy-MM-dd HH:mm:ss'). A função interna altera o fuso horário, e a externa formata o resultado. Os nomes dos fusos horários são os nomes do Windows, como UTC, Pacific Standard Time e Eastern Standard Time. Para outras regiões, use o nome correspondente de fuso horário do Windows listado na documentação da Microsoft.

A referência de fluxos de trabalho também descreve convertFromUtc, que recebe um carimbo de data/hora UTC e um fuso horário de destino, e retorna o horário convertido sem o deslocamento UTC. Seu exemplo: convertFromUtc('2018-01-01T08:00:00.0000000Z', 'Pacific Standard Time') retorna "2018-01-01T00:00:00.0000000". Também existe convertToUtc, que faz o caminho inverso. E o Power Automate tem a ação Converter fuso horário, com as entradas Horário base, Fuso horário de origem, Fuso horário de destino e, opcionalmente, Cadeia de caracteres de formato, caso você prefira uma ação a uma expressão.

Se a entrada não for ISO 8601 válido, espere um erro como "The date time string must match ISO8601 format." Uma data digitada como 15/03/2018 é a causa típica. Para datas que chegam em formato local, a referência descreve parseDateTime com uma configuração regional e um formato, por exemplo parseDateTime('21052019', 'fr-fr', 'ddMMyyyy'), que retorna '2019-05-21T00:00:00.0000000'. Interprete primeiro, depois formate.

Erros comuns

• Usar mm para o mês. mm em minúsculas é o minuto, e MM é o mês. Uma data formatada como dd/mm/yyyy mostra os minutos onde deveria estar o mês.
• Combinar HH com tt. O exemplo da própria Microsoft, 'M/dd/yyyy HH:mm:ss tt', produz 6/15/2009 13:45:30 PM, o que é contraditório. Use hh com tt, ou HH sem ele.
• Colocar aspas no conteúdo dinâmico. O conteúdo dinâmico não deve ter aspas simples, senão o fluxo trata o nome como texto comum.
• Esquecer o fuso horário. O padrão é UTC. Converta antes de formatar.
• Fazer cálculos com o resultado. A saída é uma cadeia de caracteres. Calcule primeiro e formate por último.
• Confiar nos exemplos de saída de utcNow(). As datas na documentação são exemplos fixos. O seu resultado reflete a hora atual.
• Passar uma data que não está em ISO. Interprete-a primeiro com uma configuração regional e um formato.

Tópicos relacionados para explorar

• Converter fusos horários: o artigo da Microsoft sobre conversão de fusos horários cobre a ação e a expressão.
• Adicionar ou subtrair tempo: addDays e addToTime aceitam o mesmo formato opcional, então você pode deslocar e formatar em uma única chamada.
• Interpretar formatos de data locais: parseDateTime recebe uma configuração regional e um formato para datas que não chegam em ISO 8601.
• A lista completa de funções: a referência de expressões de fluxo de trabalho documenta todas as funções de data e hora.
• Todos os especificadores personalizados: a página cadeias de caracteres de formato de data e hora personalizado lista todas as letras.

Próximo passo

Para obter resultados confiáveis do formatDateTime no Power Automate, comece com uma data ISO 8601, converta o fuso horário antes de formatar e teste o padrão em uma ação Compose. Depois, leia o artigo da Microsoft sobre como personalizar ou formatar valores de data e hora em um fluxo, e mantenha uma lista curta com os padrões que sua equipe usa com mais frequência.