Representa o horário civil (ou, às vezes, o horário físico).
Esse tipo pode representar um horário civil de uma das seguintes maneiras:
Quando utcOffset é definido e timeZone não é definido: um horário civil em um dia do calendário com um deslocamento específico do UTC.
Quando timeZone é definido e utcOffset não é definido: uma hora civil em um dia do calendário em um fuso horário específico.
Quando nem timeZone nem utcOffset estão definidos: uma hora civil em um dia do calendário no horário local.
A data é referente ao calendário gregoriano proléptico.
Se o ano, o mês ou o dia forem 0, o DateTime será considerado sem um ano, mês ou dia específico, respectivamente.
Esse tipo também pode ser usado para representar um horário físico se todos os campos de data e hora estiverem definidos e se um dos casos de time_offset estiver definido. Considere usar a mensagem Timestamp para o tempo físico. Se o caso de uso também quiser armazenar o fuso horário do usuário, isso poderá ser feito em outro campo.
Esse tipo é mais flexível do que alguns aplicativos podem querer. Documente e valide as limitações do seu aplicativo.
Representação JSON
{"year": integer,"month": integer,"day": integer,"hours": integer,"minutes": integer,"seconds": integer,"nanos": integer,// Union field time_offset can be only one of the following:"utcOffset": string,"timeZone": {object (TimeZone)}// End of list of possible types for union field time_offset.}
Campos
year
integer
Opcional. Ano da data. Precisa ser de 1 a 9999 ou 0 se especificar uma data/hora sem um ano.
month
integer
Opcional. Mês do ano. Precisa ser de 1 a 12 ou 0 se especificar uma data/hora sem um mês.
day
integer
Opcional. Dia do mês. Precisa ser um valor entre 1 e 31 válido para o ano e o mês, ou 0 se o tipo de dados for "data/hora" sem dia.
hours
integer
Opcional. Horas do dia no formato de 24 horas. Precisa ser de 0 a 23, o padrão é 0 (meia-noite). Uma API pode permitir o valor "24:00:00" para o horário de fechamento da empresa, por exemplo.
minutes
integer
Opcional. Minutos da hora do dia. Precisa ser de 0 a 59, o padrão é 0.
seconds
integer
Opcional. Segundos do minutos do horário. Normalmente precisa ser de 0 a 59, padrão 0. Uma API pode permitir o valor 60 se permitir segundos bissextos.
nanos
integer
Opcional. Frações de segundos em nanossegundos. Precisa ser de 0 a 999.999.999. O padrão é 0.
Campo de união time_offset. Opcional. Especifica o deslocamento UTC ou o fuso horário do DateTime. Escolha com cuidado entre eles, considerando que os dados de fuso horário podem mudar no futuro (por exemplo, um país modifica as datas de início/término do horário de verão, e as datas e horários no período afetado já foram armazenadas). Se omitido, o DateTime será considerado no horário local. time_offset pode ser apenas de um dos tipos a seguir:
Deslocamento de UTC. Precisa ser um segundo inteiro, entre -18 horas e +18 horas. Por exemplo, um deslocamento UTC de -4:00 seria representado como { seconds: -14400 }.
Duração em segundos com até nove dígitos fracionários, terminando em "s". Exemplo: "3.5s".
[[["Fácil de entender","easyToUnderstand","thumb-up"],["Meu problema foi resolvido","solvedMyProblem","thumb-up"],["Outro","otherUp","thumb-up"]],[["Não contém as informações de que eu preciso","missingTheInformationINeed","thumb-down"],["Muito complicado / etapas demais","tooComplicatedTooManySteps","thumb-down"],["Desatualizado","outOfDate","thumb-down"],["Problema na tradução","translationIssue","thumb-down"],["Problema com as amostras / o código","samplesCodeIssue","thumb-down"],["Outro","otherDown","thumb-down"]],["Última atualização 2025-08-29 UTC."],[],[],null,["# DateTime\n\n- [JSON representation](#SCHEMA_REPRESENTATION)\n\nRepresents civil time (or occasionally physical time).\n\nThis type can represent a civil time in one of a few possible ways:\n\n- When utcOffset is set and timeZone is unset: a civil time on a calendar day with a particular offset from UTC.\n- When timeZone is set and utcOffset is unset: a civil time on a calendar day in a particular time zone.\n- When neither timeZone nor utcOffset is set: a civil time on a calendar day in local time.\n\nThe date is relative to the Proleptic Gregorian Calendar.\n\nIf year, month, or day are 0, the DateTime is considered not to have a specific year, month, or day respectively.\n\nThis type may also be used to represent a physical time if all the date and time fields are set and either case of the `time_offset` oneof is set. Consider using `Timestamp` message for physical time instead. If your use case also would like to store the user's timezone, that can be done in another field.\n\nThis type is more flexible than some applications may want. Make sure to document and validate your application's limitations.\n\n| JSON representation |\n|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| ``` { \"year\": integer, \"month\": integer, \"day\": integer, \"hours\": integer, \"minutes\": integer, \"seconds\": integer, \"nanos\": integer, // Union field `time_offset` can be only one of the following: \"utcOffset\": string, \"timeZone\": { object (/maps/documentation/weather/reference/rest/v1/TimeZone) } // End of list of possible types for union field `time_offset`. } ``` |\n\n| Fields ||\n|---------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `year` | `integer` Optional. Year of date. Must be from 1 to 9999, or 0 if specifying a datetime without a year. |\n| `month` | `integer` Optional. Month of year. Must be from 1 to 12, or 0 if specifying a datetime without a month. |\n| `day` | `integer` Optional. Day of month. Must be from 1 to 31 and valid for the year and month, or 0 if specifying a datetime without a day. |\n| `hours` | `integer` Optional. Hours of day in 24 hour format. Should be from 0 to 23, defaults to 0 (midnight). An API may choose to allow the value \"24:00:00\" for scenarios like business closing time. |\n| `minutes` | `integer` Optional. Minutes of hour of day. Must be from 0 to 59, defaults to 0. |\n| `seconds` | `integer` Optional. Seconds of minutes of the time. Must normally be from 0 to 59, defaults to 0. An API may allow the value 60 if it allows leap-seconds. |\n| `nanos` | `integer` Optional. Fractions of seconds in nanoseconds. Must be from 0 to 999,999,999, defaults to 0. |\n| Union field `time_offset`. Optional. Specifies either the UTC offset or the time zone of the DateTime. Choose carefully between them, considering that time zone data may change in the future (for example, a country modifies their DST start/end dates, and future DateTimes in the affected range had already been stored). If omitted, the DateTime is considered to be in local time. `time_offset` can be only one of the following: ||\n| `utc``Offset` | `string (`[Duration](https://protobuf.dev/reference/protobuf/google.protobuf/#duration)` format)` UTC offset. Must be whole seconds, between -18 hours and +18 hours. For example, a UTC offset of -4:00 would be represented as { seconds: -14400 }. A duration in seconds with up to nine fractional digits, ending with '`s`'. Example: `\"3.5s\"`. |\n| `time``Zone` | `object (`[TimeZone](/maps/documentation/weather/reference/rest/v1/TimeZone)`)` Time zone. |"]]
