DateAdd, DateDiff, e TimeZoneOffset funções

Funções	Aplica-se ao
DateAdd DateDiff	Aplicativos do Canvas Fluxos do Copilot Studio Desktop Colunas de fórmulas Dataverse Aplicações orientadas por modelos CLI da Power Platform Funções Dataverse Páginas de energia
TimeZoneOffset	Aplicativos de tela Copilot Studio Fluxos de ambiente de trabalho Aplicações orientadas por modelos Funções do Power Platform CLI Dataverse Power Pages

Adiciona ou localiza a diferença nos valores de data/hora e converte entre a hora local e a UTC.

Descrição

A DateAdd função adiciona um número de unidades a um valor de data/hora. O resultado é um novo valor de data/hora. Também pode subtrair um número de unidades a um valor de data/hora ao especificar um valor negativo.

A DateDiff função retorna a diferença entre dois valores de data/hora. O resultado é um número inteiro de unidades.

Para ambas as funções, as unidades podem ser em TimeUnit.Milliseconds, TimeUnit.Seconds, TimeUnit.Minutes, TimeUnit.Hours, TimeUnit.Days, TimeUnit.Months, TimeUnit.Quarters ou TimeUnit.Years. Por predefinição, ambas as funções utilizam TimeUnit.Days como unidades.

A TimeZoneOffset função retorna o número de minutos entre a hora local do usuário e UTC (Tempo Universal Coordenado).

Você pode usar DateAdd com o para converter entre a hora local do usuário e UTC TimeZoneOffset (Tempo Universal Coordenado). Adicionar TimeZoneOffset converterá uma hora local para UTC, e subtraí-la (adicionando a negativa) converterá de UTC para hora local.

Consulte também Tipos de dados DateTime, Date e Time e como trabalhar com datas e horas para obter mais informações.

Sintaxe

DateAdd( DateTime, Adição [, Unidades ] )

• DateTime - Obrigatório. Valor Data/hora a utilizar.
• Adição - Obrigatório. Número, em Unidades, a adicionar à DateTime.
• Unidades - Opcional. O tipo de Unidades a adicionar: TimeUnit.Milliseconds, TimeUnit.Seconds, TimeUnit.Minutes, TimeUnit.Hours, TimeUnit.Days, TimeUnit.Months, TimeUnit.Quarters ou TimeUnit.Years. Se não for especificado, são utilizados TimeUnit.Days.

DateDiff( StartDateTime, EndDateTime [, Unidades ] )

• StartDateTime - Obrigatório. Valor de data/hora de início.
• EndDateTime - Obrigatório. Valor de data/hora de fim.
• Unidades - Opcional. O tipo de Unidades a subtrair: TimeUnit.Milliseconds, TimeUnit.Seconds, TimeUnit.Minutes, TimeUnit.Hours, TimeUnit.Days, TimeUnit.Months, TimeUnit.Quarters ou TimeUnit.Years. Se não for especificado, são utilizados TimeUnit.Days.

TimeZoneOffset( [ DateTime ] )

• DateTime - Opcional. Valor de data/hora cujo desvio deve ser devolvido. Por predefinição, é utilizada a data/hora atual.

Exemplos

Em todos estes exemplos, vamos assumir 15 de julho de 2013, 13:02 como data e hora atuais.

Simples DateAdd

Simples DateDiff

Diferença de datas com resultados fracionários

A função DateDiff retorna apenas um número inteiro das unidades que estão sendo subtraídas, e a precisão é dada na unidade especificada. Para calcular a diferença com uma maior precisão, utilize uma unidade mais pequena e converta o resultado adequadamente, como nos exemplos abaixo.

Converter em UTC

Para converter para UTC (Tempo Universal Coordenado), adicione o TimeZoneOffset para o tempo determinado.

Por exemplo, imagine que a atual data e hora é 15 de julho de 2013, 13:02 na Hora de Verão do Pacífico (PDT, UTC-7). Para determinar a hora atual em UTC, utilize:

• DateAdd( Agora(), TimeZoneOffset(), TimeUnit.Minutes )

TimeZoneOffset padrão para a hora atual, para que você não precise passar um argumento.

Para ver o resultado, utilize a função Text com o formato dd-mm-yyyy hh:mm, que irá devolver 15-07-2013 20:02.

Converter da UTC

Para converter do UTC, subtraia o TimeZoneOffset (adicionando o negativo) para o tempo dado.

Por exemplo, imagine que a data e hora UTC 15 de julho de 2013, 20:02 é armazenada numa variável designada StartTime. Para ajustar a hora ao fuso horário do utilizador, utilize:

• DateAdd( StartTime, −TimeZoneOffset( StartTime ), TimeUnit.Minutes )

Observe o sinal negativo antes TimeZoneOffset de subtrair o deslocamento em vez de adicioná-lo.

Para ver o resultado, utilize a função Text com o formato dd-mm-yyyy hh:mm, o que irá resultar em 15-07-2013 13:02 se estiver na Hora de Verão do Pacífico.